@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/core/pause-icon-catalogue.js

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// core/pause-icon-catalogue — WHICH ICONS THE ACCESSIBILITY BAR HAS, and in what order (ADR-0221; issue #203).
+//
+// The list, what each entry declares, and the lookup by key. 🔴 It left `ui/pause-icons` because that module had grown to 666
+// lines and 122 decision nodes, and because this is DATA: it draws nothing, listens to nothing, stores nothing. A leaf module
+// with zero imports, which is why the bar's contents can be read without mounting a document.
+//
+// ⚠️ AND IT LEFT FIRST FOR A REASON OF DIRECTION, not of size: the next cut is the MARKUP, and the markup needs the catalogue.
+// With both in the same file, extracting the markup alone would make the two modules import each other — the cycle ADR-0173
+// forbids. Data at the bottom, drawing above it.
+//
+// 📌 THE ORDER IS THE INTERFACE. A child who navigates the bar by keyboard has learnt where each icon is, and inserting one in
+// the middle displaces every other — the same cost §2 of ADR-0044 refuses to pay in the pause card. A new icon goes at the END.
+//
+// 📌 What this module does NOT decide: which icons the bar actually mounts. That is `iconsThatAct` in `ui/pause-icons`, by the
+// rule of ADR-0106 §5 — an icon exists only where something acts on it.
+/** The accessibility shortcut bar at the top of every pause screen (and of the splash `#title-icons`).
+ *  Sound-bound icons (blind/TTS) require a private audio output; the webcam and the voice require the device to have one.
+ *  The order and behaviour came verbatim from the monolith, which left with the cartridge (#111); the names became
+ *  i18n keys in the Phase-5 pass. */
+// `n` is the i18n KEY of the icon's name (the emoji `e` is NOT translated — it is the same glyph in every language).
+export const PAUSE_ICONS = [
+    // FIRST, the menus (the Dev, 2026-09-16: «Menu deve ser o primeiro ícone»): the SELECT door as an icon, for a hand with no
+    // SELECT under it. Mounted only where there is a card to open (`abrirMenus`).
+    { k: 'menu', e: '☰', n: 'icon.menu' },
+    { k: 'blind', e: '🦯', n: 'icon.blind' },
+    { k: 'tts', e: '🗨️', n: 'icon.tts' },
+    { k: 'libras', e: '🦻', n: 'icon.libras' }, // 🦻 (the Dev, 2026-09-16): 🤟 is playing by hand gestures
+    { k: 'tea', e: '🧩', n: 'icon.tea' },
+    { k: 'altmove', e: '☝️', n: 'icon.altmove' }, // ☝️ and not 🦾 (the Dev): the gesture is ONE FINGER pressing, which is what toggling asks for
+    { k: 'contrast', e: '🌗', n: 'icon.contrast' },
+    { k: 'cvd', e: '🚥', n: 'icon.cvd' },
+    // playing through the webcam, ONE icon (ADR-0215): off · hands · face · eyes, each with its lines; where 🧑 and 👀 were
+    { k: 'camera', e: '📷', n: 'icon.camera' },
+    // playing by SPEAKING (ADR-0189, issue #184): it left «em construção» on 2026-09-21, when the words, the recogniser, the
+    // microphone and the wiring existed — not a day before, because an icon that announces itself and changes nothing is the
+    // defect ADR-0106 §5 names.
+    { k: 'voice', e: '👄', n: 'icon.voice' },
+    /*
+     * THE ELEVENTH (ADR-0149 §1), at the END for the reason of order written in this file's header, not of importance.
+     *
+     * 📌 A CYCLE AND NOT A DOOR. The typography panel still exists in the Settings with its thirty faces; this button is the
+     * choice a child makes WITHOUT leaving the screen, in one press, and that is why it is a short curated list and not a menu.
+     */
+    { k: 'tipografia', e: '🔤', n: 'icon.tipografia' },
+    // THE TWELFTH (ADR-0180): the game speed, its own button beside toggle keys, at the end for the same reason as the eleventh.
+    // An hourglass and no animal: a snail, a turtle or a hare can read as an insult to the child who needs the slower game.
+    { k: 'velocidade', e: '⏳', n: 'icon.velocidade' },
+    // THE LAST BUTTON, the language (the Dev, 2026-09-16): Brazil → United States → Mexico, each press; menus, the footer, speech and
+    // recognition follow it. Its glyph is a DRAWN flag (`ui/locale-flags`), since flag emoji show as letters on Windows.
+    { k: 'idioma', e: '🇧🇷', n: 'icon.idioma' },
+];
+const ICON_BY_KEY = new Map(PAUSE_ICONS.map((ic) => [ic.k, ic]));
+export function pauseIcon(k) { return ICON_BY_KEY.get(k); }

package/dist-pkg/core/ring.d.ts

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * TAKES ONE STEP ROUND A RING — past the last comes the first, and before the first is the last.
+ *
+ * It was `clampIndex`, which stuck at the ends. ADR-0044 overturned that for a reason of use, not taste: with ONE MENU
+ * PER SCREEN every list can be a ring, and the least wanted item (`quit`) is ONE key from the most urgent (`resume`)
+ * without sitting next to it. A child who cannot see does not sweep the list looking for its end — they ask "and
+ * before the first?" and get an answer.
+ *
+ * XAG 106 allows the ring exactly for a LINEAR menu and forbids it for a 2-D grid of blocks, where "back to the first"
+ * has no spatial meaning.
+ *
+ * ⚠️ WALKING A LIST IS A RING; ADJUSTING A VALUE IS A LIMIT. The select and range steps stay pinned at their ends, and
+ * the difference is real: jumping from the loudest volume to the quietest with one key is a fright, not a convenience —
+ * and in a game with audio cues for blindness, a volume fright is harm.
+ */
+export declare function stepInRing(len: number, idx: number, delta: number): number;

package/dist-pkg/core/ring.js

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// core/ring — THE RING ARITHMETIC, and nothing else.
+//
+// It lived in `ui/menu-nav` and left when item 7 of ADR-0044 made `ui/pause-icons` need it too: `menu-nav` already
+// imported `pause-icons`, and the way back would close an import CYCLE. A cycle in ESM does not blow up at once — it
+// blows up at boot, in the TDZ, when one of the two reads the other during evaluation: the kind of defect that shows
+// once, in production, and vanishes when investigated.
+//
+// A leaf module on purpose: no dependencies, one function, no I/O.
+/**
+ * TAKES ONE STEP ROUND A RING — past the last comes the first, and before the first is the last.
+ *
+ * It was `clampIndex`, which stuck at the ends. ADR-0044 overturned that for a reason of use, not taste: with ONE MENU
+ * PER SCREEN every list can be a ring, and the least wanted item (`quit`) is ONE key from the most urgent (`resume`)
+ * without sitting next to it. A child who cannot see does not sweep the list looking for its end — they ask "and
+ * before the first?" and get an answer.
+ *
+ * XAG 106 allows the ring exactly for a LINEAR menu and forbids it for a 2-D grid of blocks, where "back to the first"
+ * has no spatial meaning.
+ *
+ * ⚠️ WALKING A LIST IS A RING; ADJUSTING A VALUE IS A LIMIT. The select and range steps stay pinned at their ends, and
+ * the difference is real: jumping from the loudest volume to the quietest with one key is a fright, not a convenience —
+ * and in a game with audio cues for blindness, a volume fright is harm.
+ */
+export function stepInRing(len, idx, delta) {
+    if (len <= 0)
+        return 0;
+    return ((idx + delta) % len + len) % len; // the extra `+ len`: `%` of a negative in JS is negative
+}

package/dist-pkg/core/rng.d.ts

@@ -1,20 +1,15 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** Uma corrente de números pseudoaleatórios independente de qualquer outra. */
+/** A stream of pseudo-random numbers independent of any other. */
 export interface Rng {
     /** [0, 1). */
     readonly rnd: () => number;
-    /** Inteiro em [lo, hi], ambos inclusive. */
+    /** An integer in [lo, hi], both inclusive. */
     readonly randInt: (lo: number, hi: number) => number;
-    /** Cópia baralhada (Fisher-Yates); não toca no original. */
+    /** A shuffled copy (Fisher-Yates); the original is untouched. */
     readonly shuffle: <T>(arr: readonly T[]) => T[];
-    /** Reposiciona ESTA corrente. Não alcança nenhuma outra. */
+    /** Repositions THIS stream. Reaches no other. */
     readonly reseed: (s: number) => void;
 }
-/** A semente do jogo próprio da engine. Um consumidor externo escolhe a sua. */
-export declare const SEMENTE_PADRAO = 20260601;
-export declare const createRng: (semente?: number) => Rng;
-export declare const reseed: (s: number) => void;
-export declare const rnd: () => number;
-export declare const randInt: (lo: number, hi: number) => number;
-export declare const shuffle: <T>(arr: readonly T[]) => T[];
-export declare const rngDecoracao: Rng;
+/** The seed of the engine's own game. An outside consumer picks its own. */
+export declare const DEFAULT_SEED = 20260601;
+export declare const createRng: (seed?: number) => Rng;

package/dist-pkg/core/rng.js

@@ -1,34 +1,31 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// core/rng.ts — RNG semeado (LCG determinístico) p/ reprodutibilidade (coin placement / testes estáveis).
-// Módulo-folha PURO, ZERO deps.
+// core/rng.ts — a seeded RNG (deterministic LCG) for reproducibility (placement, stable tests).
+// A PURE leaf module, no dependencies.
 //
-// ⚠️ DUAS COISAS MUDARAM AQUI NA MESMA MIGRAÇÃO, E ISSO É DE PROPÓSITO (issue #107).
+// ⚠️ TWO THINGS ARE HERE ON PURPOSE (issue #107).
 //
-// 1. `createRng(semente)` existe. A regra D13 do ADR-0038 — «um módulo que guarda estado exporta uma
-//    fábrica `createX()`» — nomeava este módulo desde sempre e a conversão nunca aconteceu. O preço foi
-//    medido pelo `game-15puzzle`, o segundo consumidor externo: com uma única corrente compartilhada por
-//    doze módulos (`game/*`, `render/fx`, `render/weather`, `render/draw`), «embaralhamento determinístico
-//    a partir da semente S» só é reproduzível numa página onde mais nada desenha — e a engine existe
-//    justamente para que o jogo NÃO esteja sozinho na página. Cada consumidor faz a sua corrente.
+// 1. `createRng(seed)`. ADR-0038's D13 — "a module that keeps state exports a `createX()` factory" — named this
+//    module. With one stream shared by every consumer, "a deterministic shuffle from seed S" is reproducible only on a
+//    page where nothing else draws — and the engine exists precisely so the game is NOT alone on the page. Each
+//    consumer makes its own stream.
+//    📌 And the module holds NO stream of its own (ADR-0232 D4, issue #207): the shared `rnd`/`randInt`/`shuffle`/`reseed`
+//    and the decoration stream were module state a second game on the page shared. A game that wants ornament apart from
+//    its draws builds a second stream with another seed — the platformer's is `createRng(DEFAULT_SEED ^ 0x5eed)` — because
+//    particles drawn from the game's stream would move the game's draw.
 //
-// 2. A aritmética do LCG estava a perder precisão. `_seed * 1103515245` com `_seed` perto de 2³¹ chega a
-//    ~2,37×10¹⁸, acima de 2⁵³: os bits BAIXOS — exatamente os que o `& 0x7fffffff` guarda — eram
-//    arredondados fora antes de a máscara correr. `Math.imul` faz a multiplicação em 32 bits, que é o que
-//    um LCG de 32 bits sempre quis dizer.
+// 2. `Math.imul`, not `*`. `_seed * 1103515245` with `_seed` near 2³¹ reaches ~2.37×10¹⁸, above 2⁵³: the LOW bits —
+//    exactly the ones `& 0x7fffffff` keeps — were rounded away before the mask ran. `Math.imul` multiplies in 32 bits,
+//    which is what a 32-bit LCG always meant.
 //
-// ⚠️ POR QUE AS DUAS JUNTAS. Cada uma sozinha muda a sequência semeada. Fazer uma hoje e a outra depois
-// mudaria as sequências DUAS vezes, e da segunda vez ninguém se lembraria do porquê — o defeito ficaria a
-// parecer regressão. Uma migração, uma mudança de sequência, uma explicação.
-//
-// ⚠️ O QUE NÃO MUDA: continua determinístico. A aritmética antiga também era reprodutível (ponto flutuante
-// é determinístico), e foi por isso que o defeito nunca apareceu: não era aleatoriedade errada, era um
-// gerador PIOR do que o que foi escrito. Fixtures que dependiam dos valores concretos mudam de valor.
-/** A semente do jogo próprio da engine. Um consumidor externo escolhe a sua. */
-export const SEMENTE_PADRAO = 20260601;
-export const createRng = (semente = SEMENTE_PADRAO) => {
-    let _seed = semente >>> 0;
-    // `Math.imul` e não `*`: ver o cabeçalho. O `+ 12345` cabe em segurança porque `imul` já devolveu
-    // um inteiro de 32 bits com sinal, e a máscara `& 0x7fffffff` desfaz o sinal.
+// ⚠️ Both changed the seeded sequence, so they landed together: one migration, one sequence change, one explanation.
+// The old arithmetic was reproducible too (floating point is deterministic), which is why the defect never showed:
+// not wrong randomness, a WORSE generator than the one written.
+/** The seed of the engine's own game. An outside consumer picks its own. */
+export const DEFAULT_SEED = 20260601;
+export const createRng = (seed = DEFAULT_SEED) => {
+    let _seed = seed >>> 0;
+    // `Math.imul` and not `*`: see the header. The `+ 12345` fits safely because `imul` already returned a signed 32-bit
+    // integer, and the `& 0x7fffffff` mask undoes the sign.
     const rnd = () => (_seed = (Math.imul(_seed, 1103515245) + 12345) & 0x7fffffff) / 0x7fffffff;
     const randInt = (lo, hi) => lo + Math.floor(rnd() * (hi - lo + 1));
     const shuffle = (arr) => {
@@ -42,30 +39,3 @@ export const createRng = (semente = SEMENTE_PADRAO) => {
     const reseed = (s) => { _seed = s >>> 0; };
     return { rnd, randInt, shuffle, reseed };
 };
-// ⚠️ ESTE BLOCO TINHA DATA DE MORTE ESCRITA, E ELA NÃO CHEGOU — A PREMISSA É QUE MORREU.
-// Dizia: «Existe porque `game/` ainda vive aqui dentro (issue #111). Quando `game/` sair, isto sai com ele.»
-// O `game/` saiu em 2026-09-07 — e saiu para OUTRO REPOSITÓRIO, onde continua a consumir estes quatro pelo
-// pacote. Medido no dia: `@the-inclusionist/game-platformer` importa `rnd`, `randInt` e `shuffle` em OITO
-// módulos (`quiz`, `physics`, `life`, `traffic`, `fractions`, `coins`, `coin-spawning`,
-// `literacy-distractors`) mais o `main.ts`.
-//
-// Ou seja, o que se previu como «sai junto» virou o oposto: saindo, o cartucho tornou-os SUPERFÍCIE
-// PÚBLICA de um pacote publicado. Removê-los agora é quebra de contrato maior, não limpeza.
-//
-// ⚠️ E A ADVERTÊNCIA CONTINUA VERDADEIRA, o que é o incómodo: são estado partilhado de módulo, que é
-// exatamente o defeito que a fábrica acima conserta. Um segundo jogo na mesma página divide esta corrente
-// com o primeiro. O caminho de saída é o consumidor passar a `createRng(suaSemente)` — e isso é migração
-// dele, com aviso e um major, não uma remoção unilateral daqui.
-const _padrao = createRng(SEMENTE_PADRAO);
-export const reseed = _padrao.reseed;
-export const rnd = _padrao.rnd;
-export const randInt = _padrao.randInt;
-export const shuffle = _padrao.shuffle;
-// ⚠️ A CORRENTE DA DECORAÇÃO, separada da de cima porque a mistura era o defeito CONCRETO.
-// `render/fx` tira um número por partícula, `render/weather` por gota, `render/draw` dois por tremor de
-// câmara — dezenas por quadro. Saindo da mesma corrente das moedas, «semeie com S e o mapa sai igual»
-// passava a depender de quantas partículas a tela desenhou antes, o que ninguém controla nem repara.
-// Enfeite NÃO pode mover o sorteio do jogo. São dois assuntos, e agora são duas correntes.
-// A semente é outra de propósito: se fosse a mesma, as duas correntes andariam em paralelo e o enfeite
-// ficaria correlacionado com o mapa — determinístico, mas visivelmente repetitivo.
-export const rngDecoracao = createRng(SEMENTE_PADRAO ^ 0x5eed);

package/dist-pkg/core/route.d.ts

@@ -1,42 +1,42 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import type { Role, Spot, Topology } from './contract.js';
 /**
- * Os papéis que uma rota atravessa. Leitura do `core/contract`, com o `hazard` de fora por decisão declarada
- * no cabeçalho — e `goal` de fora porque ele entra pela regra do último passo, não pela do meio.
+ * The roles a route crosses. A reading of `core/contract`, with `hazard` left out by the decision declared in the
+ * header — and `goal` left out because it comes in by the last-step rule, not the in-between one.
  */
-export declare const PAPEIS_ATRAVESSAVEIS: ReadonlySet<Role>;
-/** Este papel deixa passar? */
-export declare function atravessavel(papel: Role): boolean;
+export declare const WALKABLE_ROLES: ReadonlySet<Role>;
+/** Does this role let one through? */
+export declare function isWalkable(role: Role): boolean;
 export interface RouteCtx {
-    /** Campo 1 do contrato. A métrica decide QUANTOS vizinhos um ponto tem. */
+    /** Field 1 of the contract. The metric decides HOW MANY neighbours a spot has. */
     readonly topology: Topology;
-    /** Campo 2 do contrato: o que há neste ponto. Obrigatório na `GameDeclaration`, logo sempre disponível. */
+    /** Field 2 of the contract: what is at this spot. Mandatory in `GameDeclaration`, so always available. */
     readonly roleAt: (at: Spot) => Role;
     /**
-     * Teto de pontos visitados. Estourou → `null`, que é «não sei».
+     * Ceiling of visited spots. Hit → `null`, which is "I cannot say".
      *
-     * 4096 é ~64×64 numa grade e cobre com folga os tabuleiros que existem hoje; num mapa de plataforma grande
-     * ele corta antes de a busca custar um quadro. O número é PARÂMETRO porque o custo aceitável é de quem
-     * chama: uma pista por quadro tolera muito menos do que um cálculo ao carregar a fase.
+     * 4096 is ~64×64 on a grid and covers today's boards with room to spare; on a large platform map it cuts before the
+     * search costs a frame. The number is a PARAMETER because the acceptable cost belongs to the caller: a cue every
+     * frame tolerates far less than a calculation when a level loads.
      */
-    readonly orcamento?: number;
+    readonly budget?: number;
 }
-export interface Rota {
-    /** O PRÓXIMO ponto a pisar — a um passo de onde se está. É isto que uma pista aponta. */
-    readonly proximo: Spot;
-    /** Qual dos alvos a rota alcançou. Pode não ser o mais próximo em linha reta, e é esse o ponto. */
-    readonly ate: Spot;
-    /** Quantos passos ao longo do caminho. ⚠️ NÃO é `distance()`, que mede a reta que atravessa parede. */
-    readonly passos: number;
+export interface Route {
+    /** The NEXT spot to step on — one step from where one is. This is what a cue points at. */
+    readonly next: Spot;
+    /** Which target the route reached. It may not be the nearest in a straight line, and that is the point. */
+    readonly reached: Spot;
+    /** How many steps along the path. ⚠️ NOT `distance()`, which measures the straight line through walls. */
+    readonly steps: number;
 }
 /**
- * A rota de `de` até o mais próximo ALCANÇÁVEL dos `alvos` — largura primeiro, sobre o que se atravessa.
+ * The route from `de` to the nearest REACHABLE of the `targets` — breadth first, over what can be crossed.
  *
- * `null` quando não há alvo, quando nenhum é alcançável, quando a topologia não tem espaço (`hotspots`), ou
- * quando o orçamento estourou. Os quatro casos são o mesmo para quem chama: **não sei dizer por onde**.
+ * `null` when there is no target, when none is reachable, when the topology has no space (`hotspots`), or when the
+ * budget ran out. The four cases are one for the caller: **I cannot say which way**.
  *
- * ⚠️ «MAIS PRÓXIMO» AQUI É AO LONGO DO CAMINHO, e é a diferença inteira. Um alvo a três células em linha reta
- * do outro lado de uma parede está mais LONGE do que um a oito células por um corredor aberto — e é o segundo
- * que a criança consegue alcançar.
+ * ⚠️ "NEAREST" HERE IS ALONG THE PATH, and that is the whole difference. A target three cells away in a straight line
+ * on the other side of a wall is FARTHER than one eight cells down an open corridor — and it is the second one the
+ * child can reach.
  */
-export declare function rotaAte(ctx: RouteCtx, de: Spot, alvos: readonly Spot[]): Rota | null;
+export declare function routeTo(ctx: RouteCtx, de: Spot, targets: readonly Spot[]): Route | null;