@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/input/devices.js

@@ -1,13 +1,12 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// input/devices.ts — rótulos/mapeamentos de gamepad e toque (dados). Módulo-folha, ZERO deps.
-// PAD_DESIGNS: como rotular os 4 botões de ação por modelo de controle (o navegador detecta genérico no
-// Windows). TOUCH_DEFAULT: mapa padrão dos 9 slots de toque.
-// A leitura de pads (pollPads) e o layout de toque ficam no game.js. (Fase 2, subsistema input)
+// input/devices.ts — gamepad and touch labels and mappings (data). A leaf module, NO dependencies.
+// PAD_DESIGNS: how to label the 4 action buttons per pad model (the browser detects a generic one on Windows).
+// TOUCH_DEFAULT: the default map of the 13 touch slots (the 4 shoulder ones since ADR-0160).
 //
-// POR QUE CHAVES E NÃO TEXTO: a tabela é uma `const` de módulo, avaliada UMA vez no import. Se guardasse
-// `t('…')` já resolvido, o idioma congelaria no boot — `dict` em core/i18n é um `let` que `setLocale`
-// reatribui, e quem leu antes da troca nunca mais vê a troca. Guardando a chave, quem resolve é o ponto de
-// Este módulo continua ZERO deps de propósito: chave é dado, `t` é comportamento e mora no consumidor.
+// WHY KEYS AND NOT TEXT: the table is a module `const`, evaluated ONCE at import. If it held an already resolved `t('…')`,
+// the language would freeze at boot — whoever read before a switch would never see the switch. Holding the key, the
+// place of use resolves it. This module stays dependency-free on purpose: a key is data, `t` is behaviour and lives in
+// the consumer.
 export const PAD_DESIGNS = {
     generic: { '0': ['0', '#3a4a6a'], '1': ['1', '#3a4a6a'], '2': ['2', '#3a4a6a'], '3': ['3', '#3a4a6a'] },
     microsoft: { '0': ['A', '#2fae4e'], '1': ['B', '#d23b3b'], '2': ['X', '#2f6fd2'], '3': ['Y', '#d9a400'] },
@@ -15,17 +14,19 @@ export const PAD_DESIGNS = {
     nintendo: { '0': ['B', '#d9a400'], '1': ['A', '#d23b3b'], '2': ['Y', '#2fae4e'], '3': ['X', '#2f6fd2'] },
 };
 /**
- * Glifos de controle que NÃO SE LEEM — chave i18n do nome falado de cada um (ADR-0044, item 4).
+ * Pad glyphs that CANNOT BE READ ALOUD — the i18n key of each one's spoken name (ADR-0044, item 4).
  *
- * Um leitor de tela lê `✕` como "sinal de multiplicação", ou não lê nada, e `△` costuma sair mudo. É por isso
- * que a legenda da pausa carregava `aria-hidden="true"`: escondiam-se o ruído E a informação juntos. Aqui está
- * a metade que faltava para poder tirar o atributo — o glifo continua na tela para quem o reconhece, e a
- * PALAVRA existe para quem o escuta.
+ * A screen reader reads `✕` as "multiplication sign", or reads nothing, and `△` usually comes out mute. That is why the
+ * pause legend carried `aria-hidden="true"`: the noise AND the information were hidden together. Here is the half that
+ * was missing to take the attribute off — the glyph stays on screen for whoever recognises it, and the WORD exists for
+ * whoever hears it.
  *
- * Só os quatro do PlayStation entram. `A`, `B`, `X`, `Y` e `0`–`3` já se leem, e traduzi-los para "letra A"
- * seria acrescentar ruído em nome de acessibilidade — o defeito que este item conserta pelo avesso.
+ * Only the four PlayStation ones are here. `A`, `B`, `X`, `Y` and `0`–`3` already read, and translating them to "letter
+ * A" would add noise in accessibility's name — the defect this item fixes, inside out.
  */
 export const PAD_GLYPH_SPOKEN = {
     '✕': 'pad.glyph.cross', '○': 'pad.glyph.circle', '□': 'pad.glyph.square', '△': 'pad.glyph.triangle',
 };
-export const TOUCH_DEFAULT = { up: 'up', down: 'down', left: 'left', right: 'right', start: 'start', b0: 'action2', b1: 'action3', b2: 'action1', b3: 'action4' };
+export const TOUCH_DEFAULT = { up: 'up', down: 'down', left: 'left', right: 'right', start: 'start', b0: 'action2', b1: 'action3', b2: 'action1', b3: 'action4',
+    // The SHOULDERS (ADR-0160): L1/L2 in the top-left corner, R1/R2 in the right. They show only if the game names them (ADR-0162).
+    bl1: 'leftShoulder', bl2: 'leftTrigger', br1: 'rightShoulder', br2: 'rightTrigger' };

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

@@ -1,58 +1,49 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** As seis bordas de entrada, pelo nome do campo que elas levantam no jogador. */
+/** The six input edges, by the name of the field they raise on the player. */
 export type EdgeFlag = 'jumpEdge' | 'runEdge' | 'leftEdge' | 'rightEdge' | 'swapEdge' | 'specialEdge';
-/** As seis ações que levantam borda. Nomeado (e não `string`) para o compilador casar com o `ActionKey` de
- *  input/gamepad, que é quem lê a tabela passando a ação adiante. */
+/** The six actions that raise an edge. Named (not `string`) so the compiler matches it with the pad transport, which
+ *  reads the table passing the action on. */
 export type EdgeAction = 'action2' | 'action1' | 'left' | 'right' | 'action4' | 'action3';
-/** Ação → borda, na ORDEM em que os três caminhos as levantam. */
+/** Action → edge, in the ORDER the three paths raise them. */
 export declare const EDGE_BY_ACTION: ReadonlyArray<readonly [EdgeAction, EdgeFlag]>;
 /**
- * Este jogador pode levantar a borda desta ação?
+ * May this player raise this action's edge?
  *
- * Hoje há uma regra só, e ela é de acessibilidade: no modo Fácil o `run` não levanta borda — sem correr, e
- * portanto sem escalada de parede. Vale para teclado, controle e toque, que é justamente o ponto.
- * Se um dia houver uma segunda regra, ela entra AQUI e passa a valer nos três de uma vez.
+ * There is one rule today, and it is about accessibility: in Easy mode `action1` raises no edge — no running, and so no
+ * wall climbing. It holds for keyboard, pad and touch, which is exactly the point. A second rule would enter HERE and
+ * hold for all three at once.
  */
 export declare function edgeAllowed(action: EdgeAction, easy: boolean | undefined): boolean;
 /**
- * As seis intenções de navegação de menu — a mesma história das bordas, um andar acima.
+ * The six menu-navigation intents — the edges' story, one floor up.
  *
- * Estava declarada QUATRO vezes: `input/gamepad`, `ui/menu-nav`, `ui/activities-menu` e, sob o nome
- * `TitleNav`, `input/keydown`. Três delas traziam um comentário dizendo "MESMA forma que…", que é uma cópia
- * pedindo para ser notada. E já tinham divergido: a de `ui/activities-menu` declarava os seis campos
- * OPCIONAIS e as outras três, obrigatórios — de modo que `navTitle` aceitava `{}` enquanto quem a alimenta
- * sempre manda os seis.
+ * It was declared FOUR times, and three of them carried a comment saying "SAME shape as…", which is a copy asking to be
+ * noticed. They had already diverged: one declared the six fields OPTIONAL and the other three required.
  *
- * Mora em `input/` porque é uma intenção de ENTRADA: quem a produz são os tradutores (teclado, controle,
- * toque, e amanhã voz e webcam) e quem a consome é a UI. `input/` nunca importa de `ui/`; `ui/` já importa de
- * `input/devices`. A direção é essa.
+ * It lives in `input/` because it is an INPUT intent: the translators (keyboard, pad, touch, voice, camera) produce it and
+ * the UI consumes it. `input/` never imports `ui/`; `ui/` imports `input/`. That is the direction.
  *
- * OPCIONAIS de propósito, ao contrário das bordas: um tradutor manda só o que aconteceu. `{ down: true }` é
- * uma frase completa — "para baixo" —, e obrigar os outros cinco `false` faria cada chamada carregar cinco
- * negações que ninguém lê. É a forma que `ui/activities-menu` já usava, e é a certa; o que estava errado era
- * as outras três discordarem dela.
+ * OPTIONAL on purpose, unlike the edges: a translator sends only what happened. `{ down: true }` is a whole sentence —
+ * "down" — and requiring the other five `false`s would make every call carry five negations nobody reads.
  */
 export interface NavKeys {
     up?: boolean;
     down?: boolean;
     left?: boolean;
     right?: boolean;
-    /** Confirmar / entrar. */
+    /** Confirm / enter. */
     yes?: boolean;
-    /** Voltar / cancelar. */
+    /** Back / cancel. */
     no?: boolean;
 }
 /**
- * Alguma intenção foi expressa neste quadro? Sem intenção, a tecla NÃO é consumida — nem `preventDefault`,
- * nem `stopPropagation`, nem `navTitle`.
+ * Was any intent expressed this frame? With no intent, the key is NOT consumed — no `preventDefault`, no
+ * `stopPropagation`, no navigation.
  *
- * Estava escrita DUAS vezes, com o mesmo corpo e nomes diferentes: `hasIntent` em `ui/menu-nav` e
- * `hasTitleIntent` em `input/keydown`. Quase deixei as duas onde estavam, no raciocínio de que mover o tipo
- * para cá e criar uma função nova seria trocar seis por meia dúzia — o raciocínio estava certo e o número,
- * errado: não era uma cópia, eram duas, e o canônico apaga as duas. Os dois módulos reexportam com o nome
- * que os chamadores e os testes deles já usam.
+ * It was written TWICE, with the same body under two names; the canonical one erases both, and the two modules re-export
+ * it under the names their callers and tests already use.
  *
- * O `!!` importa: com os campos opcionais, a cadeia de `||` devolve `boolean | undefined`. Foi o compilador
- * que apontou, ao estreitar o tipo — as duas funções vinham devolvendo `undefined` como se fosse `false`.
+ * The `!!` matters: with optional fields, the `||` chain returns `boolean | undefined`. The compiler pointed it out when
+ * the type narrowed — both functions had been returning `undefined` as if it were `false`.
  */
 export declare function hasNavIntent(k: NavKeys): boolean;

package/dist-pkg/input/edges.js

@@ -1,48 +1,43 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// input/edges — a tabela "ação → borda de entrada", e a regra de quem pode levantá-la. Módulo FOLHA: zero
-// imports, nada de DOM, nada de estado.
+// input/edges — the "action → input edge" table, and the rule of who may raise it. A LEAF module: no imports, no DOM,
+// no state.
 //
-// POR QUE ISTO EXISTE COMO MÓDULO
-// Uma "borda" é o instante em que o jogador ACABOU de acionar algo — `jumpEdge`, `runEdge`, `leftEdge`… — em
-// oposição a manter pressionado. Quem levanta borda são os três caminhos de entrada, e cada um tinha a sua
-// própria cópia da mesma tabela: `input/keydown.ts`, `input/gamepad.ts` (seis `if` à mão) e
-// `input/touch-bindings.ts`. Três cópias que precisavam concordar, e nada obrigando.
+// WHY THIS EXISTS AS A MODULE
+// An "edge" is the instant the player JUST triggered something — `jumpEdge`, `runEdge`, `leftEdge`… — as opposed to
+// holding it. The three input paths raise edges, and each had its own copy of the same table: three copies that had to
+// agree, with nothing forcing them.
 //
-// Elas divergiram. A cópia do toque não tinha a guarda do modo Fácil, e como `runEdge` NÃO é a velocidade de
-// corrida — é o gatilho que gruda e solta da parede, a escalada tipo aranha de `updateCling` em
-// `game/physics.ts:177` e `:179` — o resultado foi que a criança em modo Fácil (que existe para dificuldade
-// motora) não conseguia escalar com teclado nem com controle, e conseguia com o botão da tela. No tablet de
-// escola pública, o toque não é o caminho alternativo: é o único. O sintoma foi corrigido antes deste módulo;
-// este módulo é o que impede a divergência de voltar, porque agora só há um lugar onde ela poderia morar.
+// They diverged. The touch copy lacked the Easy-mode guard, and since `runEdge` is not the running speed — it is the
+// trigger that clings to and lets go of a wall — a child in Easy mode (which exists for motor difficulty) could not climb
+// with keyboard or pad and could with the on-screen button. On a public-school tablet, touch is not the alternative path:
+// it is the only one. The symptom was fixed before this module; this module is what keeps the divergence from coming
+// back, because there is only one place left for it to live.
 //
-// A ORDEM DA TABELA É OBSERVÁVEL: `edgesFor` devolve a lista na ordem em que percorre, e há teste ancorando-a.
-/** Ação → borda, na ORDEM em que os três caminhos as levantam. */
+// THE TABLE'S ORDER IS OBSERVABLE: the edges come back in the order it is walked, and a test anchors it.
+/** Action → edge, in the ORDER the three paths raise them. */
 export const EDGE_BY_ACTION = Object.freeze([
     ['action2', 'jumpEdge'], ['action1', 'runEdge'], ['left', 'leftEdge'],
     ['right', 'rightEdge'], ['action4', 'swapEdge'], ['action3', 'specialEdge'],
 ]);
 /**
- * Este jogador pode levantar a borda desta ação?
+ * May this player raise this action's edge?
  *
- * Hoje há uma regra só, e ela é de acessibilidade: no modo Fácil o `run` não levanta borda — sem correr, e
- * portanto sem escalada de parede. Vale para teclado, controle e toque, que é justamente o ponto.
- * Se um dia houver uma segunda regra, ela entra AQUI e passa a valer nos três de uma vez.
+ * There is one rule today, and it is about accessibility: in Easy mode `action1` raises no edge — no running, and so no
+ * wall climbing. It holds for keyboard, pad and touch, which is exactly the point. A second rule would enter HERE and
+ * hold for all three at once.
  */
 export function edgeAllowed(action, easy) {
     return !(action === 'action1' && !!easy);
 }
 /**
- * Alguma intenção foi expressa neste quadro? Sem intenção, a tecla NÃO é consumida — nem `preventDefault`,
- * nem `stopPropagation`, nem `navTitle`.
+ * Was any intent expressed this frame? With no intent, the key is NOT consumed — no `preventDefault`, no
+ * `stopPropagation`, no navigation.
  *
- * Estava escrita DUAS vezes, com o mesmo corpo e nomes diferentes: `hasIntent` em `ui/menu-nav` e
- * `hasTitleIntent` em `input/keydown`. Quase deixei as duas onde estavam, no raciocínio de que mover o tipo
- * para cá e criar uma função nova seria trocar seis por meia dúzia — o raciocínio estava certo e o número,
- * errado: não era uma cópia, eram duas, e o canônico apaga as duas. Os dois módulos reexportam com o nome
- * que os chamadores e os testes deles já usam.
+ * It was written TWICE, with the same body under two names; the canonical one erases both, and the two modules re-export
+ * it under the names their callers and tests already use.
  *
- * O `!!` importa: com os campos opcionais, a cadeia de `||` devolve `boolean | undefined`. Foi o compilador
- * que apontou, ao estreitar o tipo — as duas funções vinham devolvendo `undefined` como se fosse `false`.
+ * The `!!` matters: with optional fields, the `||` chain returns `boolean | undefined`. The compiler pointed it out when
+ * the type narrowed — both functions had been returning `undefined` as if it were `false`.
  */
 export function hasNavIntent(k) {
     return !!(k.yes || k.no || k.up || k.down || k.left || k.right);

package/dist-pkg/input/empathy-filter.d.ts

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * THE TWO MOTOR EMPATHY SIMULATIONS, AS DECISIONS ON GAME KEYS (ADR-0181). Pure: the root applies the decision to the event
+ * before any cartridge hears it.
+ *
+ * A simulation makes play harder on purpose, to show what a motor disability costs; it is never an accommodation.
+ *   · «um botão por vez»: while one game key is held, a second is never accepted — nor its release;
+ *   · «sem força para segurar»: a held key reads as one tap — the press passes and is released at once; its repeats and its
+ *     real release do not reach the game.
+ */
+export type KeyDecision = 'passar' | 'barrar' | 'tocar';
+export interface EmpathySimulation {
+    readonly noChords: boolean;
+    readonly noGripStrength: boolean;
+}
+export interface EmpathyFilter {
+    /** A game key goes down. `tocar`: let it through and release it at once. */
+    keydown(code: string, repeat: boolean, sim: EmpathySimulation): KeyDecision;
+    /** A game key comes up. */
+    keyup(code: string): KeyDecision;
+}
+export declare function createEmpathyFilter(): EmpathyFilter;

package/dist-pkg/input/empathy-filter.js

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+export function createEmpathyFilter() {
+    const accepted = new Set(); // held, and the game saw them go down
+    const touched = new Set(); // physically held, already released to the game as a tap
+    const blocked = new Set(); // held, and the game never saw them
+    const anotherHeld = (code) => [...accepted, ...touched].some((k) => k !== code);
+    return {
+        keydown(code, repeat, sim) {
+            if (touched.has(code) || blocked.has(code))
+                return 'barrar';
+            if (sim.noChords && anotherHeld(code)) {
+                blocked.add(code);
+                return 'barrar';
+            }
+            if (sim.noGripStrength) {
+                if (repeat && accepted.has(code))
+                    return 'barrar';
+                accepted.delete(code);
+                touched.add(code);
+                return 'tocar';
+            }
+            accepted.add(code);
+            return 'passar';
+        },
+        keyup(code) {
+            if (touched.delete(code))
+                return 'barrar';
+            if (blocked.delete(code))
+                return 'barrar';
+            accepted.delete(code);
+            return 'passar';
+        },
+    };
+}

package/dist-pkg/input/face-map.d.ts

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Action } from '../core/actions.js';
+export type FaceExpression = 'browsUp' | 'frown' | 'headLeft' | 'headRight' | 'squeeze' | 'pressLips' | 'openMouth' | 'smile' | 'pucker' | 'lookRightThenLeft' | 'mouthLeft' | 'lookLeftThenRight' | 'mouthRight';
+/** The Dev's map (ADR-0210 erratum): each expression and the action it presses. SELECT has no expression. */
+export declare const FACE_MAP: {
+    readonly [E in FaceExpression]: Action;
+};
+/** The blendshapes the map reads — a closed list. */
+export declare const FACE_BLENDSHAPES: readonly ["browInnerUp", "browOuterUpLeft", "browOuterUpRight", "browDownLeft", "browDownRight", "mouthPressLeft", "mouthPressRight", "jawOpen", "mouthSmileLeft", "mouthSmileRight", "mouthUpperUpLeft", "mouthUpperUpRight", "mouthPucker", "mouthLeft", "mouthRight", "eyeLookOutLeft", "eyeLookInLeft", "eyeLookOutRight", "eyeLookInRight", "eyeBlinkLeft", "eyeBlinkRight", "eyeSquintLeft", "eyeSquintRight"];
+export type FaceBlendshape = (typeof FACE_BLENDSHAPES)[number];
+export type FaceScores = Partial<Readonly<Record<FaceBlendshape, number>>>;
+export type ExpressionLevels = {
+    readonly [E in FaceExpression]?: number;
+};
+/** The Face Landmarker's categories, keeping the ones the map reads. */
+export declare function faceScoresFromCategories(categories: ReadonlyArray<{
+    readonly categoryName: string;
+    readonly score: number;
+}> | null | undefined): FaceScores;
+/** The calibrated rest: each blendshape's median, and where the nose sat. */
+export interface FaceRest {
+    readonly scores: FaceScores;
+    readonly headX: number;
+}
+/**
+ * The head turned, from the nose tip's offset against the middle of the face's two sides (landmarks 1, 234, 454), in face widths, from the
+ * rest. In the camera's unmirrored image the player's left is +x. `FULL_TURN` 0.65 puts the 0.3 mark near 18° (the Dev asked for a less
+ * sensitive head; geometry, not measured on a face).
+ */
+export declare const FULL_TURN = 0.65;
+export declare function headTurn(landmarks: ReadonlyArray<{
+    readonly x: number;
+    readonly y: number;
+}> | null | undefined, restX?: number): {
+    x: number | null;
+    left: number;
+    right: number;
+};
+/** The raw levels of one frame, from the scores and the head turn, against the rest. */
+export declare function faceLevels(s: FaceScores, rest: FaceRest, turn: {
+    left: number;
+    right: number;
+}): ExpressionLevels;
+/** START's squeeze mark: above the relaxed narrowing (0.30–0.34) and the eye a real frown squeezes (0.36–0.49) in the Dev's runs. */
+export declare const SQUEEZE_MARK = 0.5;
+/** The exclusions: a held specific expression clears the generic one it drags along; a squeeze at START's mark clears the frown. */
+export declare function resolveFace(levels: ExpressionLevels, mark: number): ExpressionLevels;
+/** The pucker's own mark (0.6): below it, it is not a pucker. */
+export declare const PUCKER_MARK = 0.6;
+export declare function ownMarks(levels: ExpressionLevels): ExpressionLevels;
+/**
+ * The crossed look. In: the look to each side (in the levels, under the button it ends on). Out: the button levels. A first side counts
+ * only if it peaked at `peakMin` and then left the mark; the second must reach `peakMin` within `windowMs` and stay `holdMs`; held, it
+ * stays down while the look stays at the mark; a turned head cancels any crossing.
+ */
+export declare function createCrossedLook({ mark, peakMin, windowMs, holdMs }: {
+    mark: number;
+    peakMin?: number;
+    windowMs?: number;
+    holdMs?: number;
+}): (ms: number, levels: ExpressionLevels) => ExpressionLevels;
+/** START's long squeeze: its level passes only after staying at `SQUEEZE_MARK` for `ms` (the usual hold comes on top: about 1 s). */
+export declare function createLongSqueeze(ms?: number): (now: number, levels: ExpressionLevels) => ExpressionLevels;
+export declare function createMouthHold({ mark, ms }: {
+    mark: number;
+    ms?: number;
+}): (now: number, levels: ExpressionLevels) => ExpressionLevels;
+/** The whole reader: a frame's scores and landmarks in, the actions held and the ones that just started out. */
+export declare function createFaceMapReader({ rest, mark, holdMs }: {
+    rest: FaceRest;
+    mark?: number;
+    holdMs?: number;
+}): (ms: number, scores: FaceScores, landmarks?: ReadonlyArray<{
+    readonly x: number;
+    readonly y: number;
+}> | null) => {
+    held: Action[];
+    started: Action[];
+};
+/**
+ * THE FACE'S REST, MEASURED BY ITSELF (the Dev, 2026-09-16: «sozinho, quando o rosto fica parado olhando para o centro da tela por 3 s+»).
+ * Frames gather while the face stays still — every blendshape and the nose within `maxSpread` of their median — for `restMs` in a row;
+ * any movement restarts the count, so the rest is never taken from a child who is talking, reading or looking around.
+ */
+export declare function createFaceRest({ restMs, maxSpread }?: {
+    restMs?: number;
+    maxSpread?: number;
+}): (ms: number, scores: FaceScores, headX: number | null) => {
+    rest: FaceRest | null;
+    stillMs: number;
+};
+/** The rest from a few seconds of samples: each blendshape's median, and the nose's. */
+export declare function faceRestFromSamples(samples: ReadonlyArray<{
+    readonly scores: FaceScores;
+    readonly headX: number | null;
+}>): FaceRest;