@the-inclusionist/engine 8.0.0 → 10.0.0

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

@@ -1,74 +1,71 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// input/latch-store.ts — A ALTERNÂNCIA, LIDA E ESCRITA NO ARMAZENAMENTO (ADR-0113).
+// input/latch-store.ts — THE TOGGLE, READ FROM AND WRITTEN TO STORAGE (ADR-0113).
 //
-// ========================= O QUE ESTE MÓDULO É, E POR QUE É SEPARADO =========================
-// O `input/latch-scope` é a REGRA e não toca em nada: recebe uma `LeituraDaAlternancia` já feita e responde.
-// Este módulo é a única coisa que faltava entre ela e o mundo — quem vai ao armazenamento buscar os três
-// valores que a regra pede, e quem grava o que a criança escolhe.
+// ========================= WHAT THIS MODULE IS, AND WHY IT IS APART =========================
+// `input/latch-scope` is the RULE and touches nothing: it takes a finished `LatchReading` and answers. This module is the
+// one thing that was missing between it and the world — whoever goes to storage for the three values the rule asks for,
+// and whoever writes what the child chooses.
 //
-// 📌 SEPARADO DE PROPÓSITO, e não por arrumação: a regra é pura e tem gate próprio; misturar armazenamento
-// dentro dela obrigaria todo caso da regra a montar um `localStorage` de mentira para afirmar uma coisa que
-// não depende dele. É a mesma divisão que o `render/viz-axes` (modelo) e o `render/viz-setters` (escrita)
-// já fazem neste repositório.
+// 📌 APART ON PURPOSE, not for tidiness: the rule is pure and has its own gate; mixing storage into it would make every
+// case of the rule build a fake `localStorage` to assert something that does not depend on it. The same split
+// `render/viz-axes` (model) and `render/viz-setters` (writing) make in this repository.
 //
-// ⚠️ E O QUE ELE NÃO FAZ: não sabe QUAL transporte está em uso. Isso é do `input/transporte-em-uso`, e chega
-// aqui como argumento. Um módulo de armazenamento que adivinhasse o transporte escreveria a escolha de uma
-// criança na chave de outro aparelho — em silêncio, que é o defeito que o ADR-0113 existe para evitar.
-import { chaveDaAlternancia, chaveLegadaDaAlternancia, alternanciaDe, alternanciaEhEscolha, } from './latch-scope.js';
+// ⚠️ AND WHAT IT DOES NOT DO: it does not know WHICH transport is in use. That is `input/transport-in-use`'s, and it
+// arrives here as an argument. A storage module that guessed the transport would write one child's choice under another
+// device's key — in silence, the defect ADR-0113 exists to prevent.
+import { latchKey, legacyLatchKey, latchOf, latchIsOptional, } from './latch-scope.js';
 /**
- * TRÊS ESTADOS E NÃO DOIS: `true`, `false`, e NUNCA ESCRITO.
+ * THREE STATES, NOT TWO: `true`, `false`, and NEVER WRITTEN.
  *
- * 🔴 ESTA FUNÇÃO EXISTE PARA NÃO SE USAR `getBool`, e a diferença custa o ajuste de uma criança. O `getBool`
- * colapsa «nunca escrito» em `false`. Com ele, o `doTransporte` de uma criança que nunca mexeu neste aparelho
- * chegaria à regra como `false` — e a regra responde na PRIMEIRA linha que encontra um valor, logo devolveria
- * `false` e **nunca consultaria a chave legada**, que é onde vive o ajuste que ela já tinha.
+ * 🔴 THIS FUNCTION EXISTS SO `getBool` IS NOT USED, and the difference costs a child's setting. `getBool` collapses
+ * "never written" into `false`. With it, the per-transport value of a child who never touched this device would reach the
+ * rule as `false` — and the rule answers at the FIRST line that finds a value, so it would return `false` and **never
+ * consult the legacy key**, where the setting they already had lives.
  *
- * ⚠️ É por isso que o `latch-scope` tipa os dois campos como `boolean | null` e tem um caso próprio a dizer
- * que «`false` guardado é um VALOR, e não uma ausência». Este é o lado do armazenamento da mesma frase.
+ * ⚠️ That is why `latch-scope` types both fields `boolean | null` and has a case of its own saying "a stored `false` is a
+ * VALUE, not an absence". This is the storage side of the same sentence.
  */
-export function lerTriEstado(armazem, chave) {
-    const v = armazem.get(chave, null);
+export function readTriState(store, key) {
+    const v = store.get(key, null);
     return v == null ? null : v === '1';
 }
 /**
- * A LEITURA COMPLETA que a regra pede, montada a partir do armazenamento.
+ * THE WHOLE READING the rule asks for, built from storage.
  *
- * `base` é `togglemove` ou `togglerun` — os dois nomes que já existem no armazenamento da criança.
+ * `base` is `togglemove` or `togglerun` — the two names that already exist in the child's storage.
  */
-export function leituraDaAlternancia(armazem, base, jogador, transporte, padrao) {
+export function readLatch(store, base, player, transport, fallback) {
     return {
-        doTransporte: lerTriEstado(armazem, chaveDaAlternancia(base, jogador, transporte)),
-        doLegado: lerTriEstado(armazem, chaveLegadaDaAlternancia(base, jogador)),
-        padrao,
+        fromTransport: readTriState(store, latchKey(base, player, transport)),
+        fromLegacy: readTriState(store, legacyLatchKey(base, player)),
+        byDefault: fallback,
     };
 }
 /**
- * A ALTERNÂNCIA DESTE JOGADOR NESTE TRANSPORTE — a pergunta inteira, numa chamada.
+ * THIS PLAYER'S TOGGLE ON THIS TRANSPORT — the whole question, in one call.
  *
- * 📌 TROCAR DE TRANSPORTE TROCA A RESPOSTA SEM ESCREVER NADA, que é a cláusula 1 do ADR-0113 em código: o
- * valor pertence ao mapeamento do controle, como um caps-lock, e mudar de controle é mudar de mapeamento.
+ * 📌 SWITCHING TRANSPORT SWITCHES THE ANSWER WITHOUT WRITING ANYTHING, clause 1 of ADR-0113 in code: the value belongs to
+ * the controls' mapping, like a caps lock, and changing controls is changing mapping.
  */
-export function alternanciaGuardada(armazem, base, jogador, transporte, padrao) {
-    return alternanciaDe(transporte, leituraDaAlternancia(armazem, base, jogador, transporte, padrao));
+export function storedLatch(store, base, player, transport, fallback) {
+    return latchOf(transport, readLatch(store, base, player, transport, fallback));
 }
 /**
- * GRAVA A ESCOLHA DA CRIANÇA para o transporte em uso. Devolve se gravou.
+ * WRITES THE CHILD'S CHOICE for the transport in use. Returns whether it wrote.
  *
- * ⚠️ RECUSA NOS TRANSPORTES DE UM COMANDO, e a recusa é um `false` devolvido e não um lançamento: em olhos,
- * rosto, gestos e fala a alternância é o que faz a entrada funcionar (ADR-0113 cláusula 3), então não há
- * escolha a gravar. Quem chama usa a resposta para DESABILITAR o controle COM MOTIVO — que é a metade que
- * falta e que vive na interface, não aqui.
+ * ⚠️ IT REFUSES ON ONE-COMMAND TRANSPORTS, and the refusal is a returned `false`, not a throw: on eyes, face, gestures and
+ * speech the toggle is what makes the input work (ADR-0113 clause 3), so there is no choice to write. The caller uses the
+ * answer to DISABLE the control WITH A REASON — the other half, which lives in the interface, not here.
  *
- * 📌 Gravar mesmo assim seria pior do que inútil: a criança mexeria no ícone, o valor iria para o disco, e o
- * jogo continuaria a ignorá-lo — um controle que mente sobre ter funcionado.
+ * 📌 Writing anyway would be worse than useless: the child would touch the icon, the value would go to disk, and the game
+ * would keep ignoring it — a control that lies about having worked.
  */
-// ⚠️ RECEBE O ESCRITOR E NÃO UM ARMAZÉM, e a mudança é de 2026-09-08, quando o painel foi ligar-se a isto.
-// O `ui/settings-motor` já tem um `store: { setBool }` injectado — exigir-lhe um objecto com `get`/`set`
-// crus obrigaria a inventar um adaptador no ponto de uso, e um adaptador ali é onde uma segunda forma de
-// escrever a mesma chave nasce. Uma função é o mínimo que a escrita precisa.
-export function gravarAlternancia(escrever, base, jogador, transporte, ligada) {
-    if (!alternanciaEhEscolha(transporte))
+// ⚠️ IT TAKES THE WRITER AND NOT A STORE: the mobility panel already has a `store: { setBool }` injected, and demanding an
+// object with raw `get`/`set` would force an adapter at the call site — where a second way of writing the same key is
+// born. A function is the minimum the write needs.
+export function writeLatch(write, base, player, transport, isOn) {
+    if (!latchIsOptional(transport))
         return false;
-    escrever(chaveDaAlternancia(base, jogador, transporte), ligada);
+    write(latchKey(base, player, transport), isOn);
     return true;
 }

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

@@ -1,47 +1,46 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import type { PlayerView } from '../core/entity.js';
-import { type ArmazemDaAlternancia } from './latch-store.js';
+import { type LatchStore } from './latch-store.js';
 /**
- * O MÍNIMO DO JOGADOR que a alternância toca — dois campos, e nenhum deles é do contrato do jogo.
+ * The MINIMUM OF THE PLAYER the toggle touches — two fields, neither of them part of the game's contract.
  *
- * 📌 `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.
+ * 📌 `PlayerView` and not the whole player: this module has nothing to do with sprites, physics or camera, and a wide type
+ * here would make a gate need a whole fake player to assert two lines.
  *
- * ⚠️ 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.
+ * ⚠️ AND IT MOVED HERE INSTEAD OF BEING BORN A SECOND TIME. This line existed word for word in the mobility panel —
+ * writing it again would be a second copy of a type. The panel publishes it by ALIAS, so the names snapshot does not read
+ * it as removed.
  */
-export type JogadorDaAlternancia = PlayerView<'toggleMove' | 'walkDir'>;
+export type LatchPlayer = PlayerView<'toggleMove' | 'walkDir'>;
 /**
- * A base com que a alternância de MARCHA vive no armazenamento da criança.
+ * The base under which the WALKING toggle lives in the child's storage.
  *
- * ⚠️ 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.
+ * ⚠️ ITS SIBLING (`togglerun`, the RUN toggle) DOES NOT ENTER HERE, and the absence is declared rather than forgotten:
+ * `p.toggleRun` has a ROUND reader in the cartridge, with its own latch saying whether it is running NOW — `walkDir = 0`
+ * is not the right gesture for it, and inventing one without that reader in front of me would decide for a game I did not
+ * open. `input/latch-store` already takes the base as an argument, so when it enters it needs no second form of the same
+ * question.
  */
 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.
+ * PUTS THE WALKING TOGGLE ON THE PLAYER, with the rule that goes with it. Returns whether anything CHANGED.
  *
- * ⚠️ 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.
+ * ⚠️ `walkDir = 0` runs only when the toggle FALLS. Zeroing it on every call would take the direction from whoever is
+ * walking, once per edge — the defect inside out, and more frequent.
  *
- * 📌 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.
+ * 📌 Returning "changed" is not convenience: a caller on the edge runs this many times a second, and announcing or
+ * reflecting on every call would fill the screen reader with the same sentence.
  */
-export declare function aplicarAlternancia(p: JogadorDaAlternancia, ligada: boolean): boolean;
+export declare function applyLatch(p: LatchPlayer, on: boolean): boolean;
 /**
- * A ALTERNÂNCIA DESTE JOGADOR, RESOLVIDA PARA O TRANSPORTE EM USO E ESCRITA NELE. Devolve se mudou.
+ * THIS PLAYER'S TOGGLE, RESOLVED FOR THE TRANSPORT IN USE AND WRITTEN ON THEM. Returns whether it changed.
  *
- * É 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.
+ * Clause 1 of ADR-0113 in code, and the property it promises is NEGATIVE: calling this when the device changes changes
+ * the answer **without writing to storage**. A sync that stored the resolved value would erase, on the first edge, the
+ * choice the child made on the other device.
  *
- * ⚠️ 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.
+ * ⚠️ AND ON THE FOUR ASSISTED TRANSPORTS IT ANSWERS `true` WITHOUT CONSULTING ANYTHING — the rule lives in `latch-scope`
+ * with its reason: on eyes, face, gestures and speech the toggle is what makes the input work, and inheriting a `false`
+ * the child chose on the keyboard would leave them with a gaze control that does not respond.
  */
-export declare function sincronizarAlternancia(p: JogadorDaAlternancia, armazem: ArmazemDaAlternancia, jogador: number, transporte: string, padrao: boolean): boolean;
+export declare function syncLatch(p: LatchPlayer, store: LatchStore, player: number, transport: string, byDefault: boolean): boolean;

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

@@ -1,43 +1,43 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import { alternanciaGuardada } from './latch-store.js';
+import { storedLatch } from './latch-store.js';
 /**
- * A base com que a alternância de MARCHA vive no armazenamento da criança.
+ * The base under which the WALKING toggle lives in the child's storage.
  *
- * ⚠️ 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.
+ * ⚠️ ITS SIBLING (`togglerun`, the RUN toggle) DOES NOT ENTER HERE, and the absence is declared rather than forgotten:
+ * `p.toggleRun` has a ROUND reader in the cartridge, with its own latch saying whether it is running NOW — `walkDir = 0`
+ * is not the right gesture for it, and inventing one without that reader in front of me would decide for a game I did not
+ * open. `input/latch-store` already takes the base as an argument, so when it enters it needs no second form of the same
+ * question.
  */
 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.
+ * PUTS THE WALKING TOGGLE ON THE PLAYER, with the rule that goes with it. Returns whether anything CHANGED.
  *
- * ⚠️ 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.
+ * ⚠️ `walkDir = 0` runs only when the toggle FALLS. Zeroing it on every call would take the direction from whoever is
+ * walking, once per edge — the defect inside out, and more frequent.
  *
- * 📌 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.
+ * 📌 Returning "changed" is not convenience: a caller on the edge runs this many times a second, and announcing or
+ * reflecting on every call would fill the screen reader with the same sentence.
  */
-export function aplicarAlternancia(p, ligada) {
-    if (p.toggleMove === ligada)
+export function applyLatch(p, on) {
+    if (p.toggleMove === on)
         return false;
-    p.toggleMove = ligada;
-    if (!ligada)
+    p.toggleMove = on;
+    if (!on)
         p.walkDir = 0;
     return true;
 }
 /**
- * A ALTERNÂNCIA DESTE JOGADOR, RESOLVIDA PARA O TRANSPORTE EM USO E ESCRITA NELE. Devolve se mudou.
+ * THIS PLAYER'S TOGGLE, RESOLVED FOR THE TRANSPORT IN USE AND WRITTEN ON THEM. Returns whether it changed.
  *
- * É 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.
+ * Clause 1 of ADR-0113 in code, and the property it promises is NEGATIVE: calling this when the device changes changes
+ * the answer **without writing to storage**. A sync that stored the resolved value would erase, on the first edge, the
+ * choice the child made on the other device.
  *
- * ⚠️ 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.
+ * ⚠️ AND ON THE FOUR ASSISTED TRANSPORTS IT ANSWERS `true` WITHOUT CONSULTING ANYTHING — the rule lives in `latch-scope`
+ * with its reason: on eyes, face, gestures and speech the toggle is what makes the input work, and inheriting a `false`
+ * the child chose on the keyboard would leave them with a gaze control that does not respond.
  */
-export function sincronizarAlternancia(p, armazem, jogador, transporte, padrao) {
-    return aplicarAlternancia(p, alternanciaGuardada(armazem, BASE_DA_MARCHA, jogador, transporte, padrao));
+export function syncLatch(p, store, player, transport, byDefault) {
+    return applyLatch(p, storedLatch(store, BASE_DA_MARCHA, player, transport, byDefault));
 }

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

@@ -1,30 +1,27 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** Sentido travado: -1 esquerda, 0 parado, 1 direita. */
+/** The latched direction: -1 left, 0 stopped, 1 right. */
 export type LatchDir = -1 | 0 | 1;
-/** Fração da velocidade de caminhada quando o jogador SEGURA o botão no sentido travado. */
+/** The fraction of walking speed when the player HOLDS the button in the latched direction. */
 export declare const LATCH_HELD: number;
-/** Fração quando a direção está travada mas nenhum botão está pressionado — o "andar sozinho". */
+/** The fraction when the direction is latched but no button is pressed — "walking alone". */
 export declare const LATCH_IDLE: number;
 /**
- * O próximo sentido travado, dado o atual e as bordas de toque deste quadro.
+ * The next latched direction, given the current one and this frame's tap edges.
  *
- * Um toque no sentido em que já se anda PARA (é o mesmo botão que liga e desliga — não há botão de parar, e
- * inventar um custaria a quem tem um dedo só o dobro de alcances). Um toque no sentido oposto inverte
- * direto, sem passar pelo zero: quem toca "esquerda" andando para a direita quer ir para a esquerda, não
- * quer parar e tocar de novo.
+ * A tap in the direction already walked STOPS (the same button turns it on and off — there is no stop button, and
+ * inventing one would cost a one-finger player twice the reach). A tap in the opposite direction reverses straight away,
+ * without passing through zero: whoever taps "left" while walking right wants to go left, not stop and tap again.
  *
- * As duas bordas no MESMO quadro são possíveis (dois dedos, ou um switch duplo mal calibrado) e a ordem
- * importa: esquerda é avaliada primeiro e direita depois, então direita vence. É o comportamento que a
- * física sempre teve — duas linhas `if` em sequência —, preservado aqui de propósito e agora com um teste que
- * o fixa, em vez de ser um efeito não intencional da ordem em que alguém escreveu dois `if`.
+ * Both edges in the SAME frame are possible (two fingers, or a badly calibrated double switch) and the order matters:
+ * left is evaluated first and right after, so right wins. It is the behaviour the physics always had, kept on purpose and
+ * pinned by a test instead of being an accident of the order two `if`s were written in.
  */
 export declare function nextLatchedDir(current: LatchDir, leftEdge: boolean, rightEdge: boolean): LatchDir;
 /**
- * O multiplicador da velocidade de caminhada, COM sinal: o sentido travado vezes a fração que corresponde a
- * estar ou não segurando o botão daquele sentido.
+ * The walking-speed multiplier, WITH sign: the latched direction times the fraction for holding or not holding that
+ * direction's button.
  *
- * Devolve o produto (e não só a fração) porque parado é 0 e nenhuma fração precisa opinar sobre isso —
- * exatamente como a física fazia ao multiplicar por `dir`. Quem chama multiplica por `TUNE.hWalk`; a
- * constante de ajuste do jogo não entra neste módulo.
+ * It returns the product (not only the fraction) because stopped is 0 and no fraction needs an opinion on that. The
+ * caller multiplies by its own walking speed; the game's tuning constant does not enter this module.
  */
 export declare function latchedDrive(dir: LatchDir, holdingLeft: boolean, holdingRight: boolean): number;

package/dist-pkg/input/latch.js

@@ -1,45 +1,38 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// input/latch — SEGURAR VIRA ALTERNAR. Passo 2 do ADR-0027, metade da "entrada como dado".
+// input/latch — HOLDING BECOMES TOGGLING. Step 2 of ADR-0027, half of "input as data".
 //
-// O QUE É. Quem não consegue MANTER um botão pressionado — espasticidade, tremor, fadiga, um único dedo, um
-// switch de sopro — não perde o jogo: um TOQUE trava a direção, e o personagem segue andando sozinho. Tocar de
-// novo no mesmo sentido para; tocar no sentido oposto inverte. Segurar, para quem consegue, acelera.
+// WHAT IT IS. Whoever cannot KEEP a button pressed — spasticity, tremor, fatigue, a single finger, a sip-and-puff switch —
+// does not lose the game: a TAP latches the direction, and the character keeps walking alone. Tapping the same way again
+// stops; tapping the opposite way reverses. Holding, for whoever can, speeds up.
 //
-// POR QUE SAIU DA FÍSICA. A política morava dentro de `game/physics.ts`, no meio do cálculo do movimento
-// horizontal. Três consequências, todas ruins:
-//   1. Uma decisão de ENTRADA estava escrita como se fosse uma regra do jogo, num arquivo que ninguém abre
-//      para mexer em acessibilidade motora.
-//   2. Só o movimento horizontal tinha caminho de alternância. Pulo, corrida e troca de poder não têm — e não
-//      por decisão, por acidente de onde o código foi parar. Este módulo é onde essa lacuna se fecha quando
-//      for fechada; NÃO a fecho agora, porque cada ação precisa da sua própria resposta de desenho (o que
-//      significa "pulo travado"?) e inventar isso sem o Dev seria pior que a lacuna.
-//   3. A engine não podia oferecer a alternância a OUTRO jogo sem levar a física do plataforma junto.
+// WHY IT IS NOT IN THE PHYSICS. The policy used to live inside a game's physics, in the middle of the horizontal
+// movement. An INPUT decision was written as if it were a game rule, in a file nobody opens to work on motor
+// accessibility — and the engine could not offer the toggle to ANOTHER game without taking the platformer's physics
+// along. Jumping and swapping still have no toggle path: each needs its own design answer (what does "a latched jump"
+// mean?), and inventing it without the Dev would be worse than the gap.
 //
-// DE QUE LADO DA LINHA ISTO CAI. O ADR-0027 separa PRESENTAÇÃO (como o estado vira pixel e som), OPERAÇÃO
-// (como a intenção vira entrada) e REGRA (o que é alcançável). O critério objetivo: uma adaptação cruza a
-// linha quando altera o CONJUNTO DE ESTADOS ALCANÇÁVEIS ou a PROBABILIDADE de alcançá-los. A alternância não
-// altera nem um nem outro — o jogador chega exatamente aos mesmos lugares, gastando menos motricidade. É
-// OPERAÇÃO, e por isso a engine a oferece e o jogo não pode recusar. (O modo Fácil, no mesmo botão hoje, é
-// REGRA: hitbox de +4px, proteção de beirada e gravidade 2/3 mudam o que é alcançável. Não estão aqui.)
+// WHICH SIDE OF THE LINE THIS FALLS ON. ADR-0027 separates PRESENTATION (how state becomes pixel and sound), OPERATION
+// (how intent becomes input) and RULE (what is reachable). The objective test: an adaptation crosses the line when it
+// changes the SET OF REACHABLE STATES or the PROBABILITY of reaching them. The toggle changes neither — the player reaches
+// exactly the same places, spending less motor effort. It is OPERATION, so the engine offers it and a game may not refuse
+// it. (Easy mode is RULE: a bigger hitbox, edge protection and lower gravity change what is reachable. They are not here.)
 //
-// PURO DE PROPÓSITO: sem `document`, sem PIXI, sem `TUNE`. Recebe números e devolve números, roda no project
-// `node` do Vitest, e não sabe que existe um plataforma do outro lado.
-/** Fração da velocidade de caminhada quando o jogador SEGURA o botão no sentido travado. */
+// PURE ON PURPOSE: no `document`, no PIXI, no game tuning. It takes numbers and returns numbers, runs in the Vitest
+// `node` project, and does not know there is a platformer on the other side.
+/** The fraction of walking speed when the player HOLDS the button in the latched direction. */
 export const LATCH_HELD = 2 / 3;
-/** Fração quando a direção está travada mas nenhum botão está pressionado — o "andar sozinho". */
+/** The fraction when the direction is latched but no button is pressed — "walking alone". */
 export const LATCH_IDLE = 1 / 3;
 /**
- * O próximo sentido travado, dado o atual e as bordas de toque deste quadro.
+ * The next latched direction, given the current one and this frame's tap edges.
  *
- * Um toque no sentido em que já se anda PARA (é o mesmo botão que liga e desliga — não há botão de parar, e
- * inventar um custaria a quem tem um dedo só o dobro de alcances). Um toque no sentido oposto inverte
- * direto, sem passar pelo zero: quem toca "esquerda" andando para a direita quer ir para a esquerda, não
- * quer parar e tocar de novo.
+ * A tap in the direction already walked STOPS (the same button turns it on and off — there is no stop button, and
+ * inventing one would cost a one-finger player twice the reach). A tap in the opposite direction reverses straight away,
+ * without passing through zero: whoever taps "left" while walking right wants to go left, not stop and tap again.
  *
- * As duas bordas no MESMO quadro são possíveis (dois dedos, ou um switch duplo mal calibrado) e a ordem
- * importa: esquerda é avaliada primeiro e direita depois, então direita vence. É o comportamento que a
- * física sempre teve — duas linhas `if` em sequência —, preservado aqui de propósito e agora com um teste que
- * o fixa, em vez de ser um efeito não intencional da ordem em que alguém escreveu dois `if`.
+ * Both edges in the SAME frame are possible (two fingers, or a badly calibrated double switch) and the order matters:
+ * left is evaluated first and right after, so right wins. It is the behaviour the physics always had, kept on purpose and
+ * pinned by a test instead of being an accident of the order two `if`s were written in.
  */
 export function nextLatchedDir(current, leftEdge, rightEdge) {
     let dir = current;
@@ -50,12 +43,11 @@ export function nextLatchedDir(current, leftEdge, rightEdge) {
     return dir;
 }
 /**
- * O multiplicador da velocidade de caminhada, COM sinal: o sentido travado vezes a fração que corresponde a
- * estar ou não segurando o botão daquele sentido.
+ * The walking-speed multiplier, WITH sign: the latched direction times the fraction for holding or not holding that
+ * direction's button.
  *
- * Devolve o produto (e não só a fração) porque parado é 0 e nenhuma fração precisa opinar sobre isso —
- * exatamente como a física fazia ao multiplicar por `dir`. Quem chama multiplica por `TUNE.hWalk`; a
- * constante de ajuste do jogo não entra neste módulo.
+ * It returns the product (not only the fraction) because stopped is 0 and no fraction needs an opinion on that. The
+ * caller multiplies by its own walking speed; the game's tuning constant does not enter this module.
  */
 export function latchedDrive(dir, holdingLeft, holdingRight) {
     const holding = (dir === -1 && holdingLeft) || (dir === 1 && holdingRight);

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

@@ -1,22 +1,19 @@
 // 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>>>;
+/** What the game declares: only what it wants to change. `null` on a button is "this position does not exist in this game". */
+export type PadMapping = (players: number, seat: number) => Partial<Record<Action, number | null>> | null;
+export type PadTable = Readonly<Record<Action, Binding<number>>>;
+/** The button table for an arrangement and seat — what `createPadTable` returns and `GamepadCtx.padTable` receives. */
+export type PadTableFor = (players: number, seat: number) => PadTable;
 /**
- * REGISTA O PADRÃO DO JOGO. Chamado uma vez pelo arranque; `null` limpa (é o que um jogo sem opinião produz).
+ * THE BUTTON TABLE OF ONE GAME'S MAPPING, for each arrangement and seat — the engine's factory with the game's default on
+ * top. `null` = a game with no opinion: the factory itself, the same object.
  *
- * ⚠️ 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.
+ * 📌 MEMOISED because it is read in the polling loop, once per pad per frame: merging two objects sixty times a second
+ * per player is garbage no child sees and the collector pays for. The key is `players:seat`.
+ * ⚠️ AND THE MEMO IS THIS TABLE'S, one per mapping (ADR-0232 D4): a root that mounts another cartridge builds another
+ * table. As a module registration it was one memo for the page, and a second mount — another game, another root, one
+ * test after another — read the previous game's table unless every writer remembered to clear it.
  */
-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;
+export declare function createPadTable(mapping: PadMapping | null): PadTableFor;

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

@@ -1,34 +1,27 @@
 // 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).
+ * THE BUTTON TABLE OF ONE GAME'S MAPPING, for each arrangement and seat — the engine's factory with the game's default on
+ * top. `null` = a game with no opinion: the factory itself, the same object.
  *
- * ⚠️ 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.
+ * 📌 MEMOISED because it is read in the polling loop, once per pad per frame: merging two objects sixty times a second
+ * per player is garbage no child sees and the collector pays for. The key is `players:seat`.
+ * ⚠️ AND THE MEMO IS THIS TABLE'S, one per mapping (ADR-0232 D4): a root that mounts another cartridge builds another
+ * table. As a module registration it was one memo for the page, and a second mount — another game, another root, one
+ * test after another — read the previous game's table unless every writer remembered to clear it.
  */
-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;
+export function createPadTable(mapping) {
+    const memo = new Map();
+    return (players, seat) => {
+        if (!mapping)
+            return GAMEPAD_STANDARD;
+        const key = `${players}:${seat}`;
+        const cached = memo.get(key);
+        if (cached)
+            return cached;
+        const changes = mapping(players, seat);
+        const table = changes ? Object.freeze({ ...GAMEPAD_STANDARD, ...changes }) : GAMEPAD_STANDARD;
+        memo.set(key, table);
+        return table;
+    };
 }