@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/core/route.js

@@ -1,158 +1,163 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// core/route — POR ONDE SE VAI ATÉ LÁ, e não só onde é lá (#84, item 1).
+// core/route — WHICH WAY TO GET THERE, not only where there is (#84, item 1).
 //
-// ========================= O DEFEITO QUE ISTO EXISTE PARA CONSERTAR =========================
-// A issue #84 escreve-o em duas linhas, e elas são o módulo inteiro:
+// ========================= THE DEFECT THIS EXISTS TO FIX =========================
+// Without it, every cue points in a STRAIGHT LINE at the target, and a straight line goes through walls: the guide
+// tells the child to walk into a solid block, and they have no way to know why.
 //
-//     «Sem isso, qualquer pista aponta em LINHA RETA para o alvo, e a linha reta atravessa parede: hoje
-//      `alvoMaisProximo()` mede distância pela métrica declarada e `panFor()` só compara `x`, então o guia
-//      manda a criança andar para dentro de um bloco sólido e ela não tem como saber por quê.»
+// ⚠️ AND THEY REALLY HAVE NO WAY TO KNOW. A child who can see ignores an arrow pointing at a wall without noticing they
+// ignored it. A child who depends on the cue does what it says — and then does it again, because the cue keeps saying
+// the same. A wrong cue is worse than none: no cue at least lets them explore.
 //
-// ⚠️ E ELA NÃO TEM MESMO COMO SABER. Uma criança que vê ignora uma seta que aponta para uma parede sem sequer
-// reparar que a ignorou. Quem depende da pista faz o que ela diz — e depois faz outra vez, porque a pista
-// continua a dizer o mesmo. A pista errada é pior do que pista nenhuma: pista nenhuma deixa-a explorar.
+// ========================= WHAT "CROSSABLE" IS, AND WHY IT IS NOT MY INVENTION =========================
+// #84 asks for "the directions where there is AIR OR WATER". Those two words are already in the contract, and each
+// `Role` says of itself whether it can be crossed — the set below is a READING of `core/contract`, not a new decision:
 //
-// ========================= O QUE É «ATRAVESSÁVEL», E POR QUE NÃO É INVENÇÃO MINHA =========================
-// A #84 pede «as direções por onde há AR OU ÁGUA». Essas duas palavras já estão no contrato, e cada `Role`
-// diz de si mesmo se se atravessa — o conjunto abaixo é uma LEITURA do `core/contract`, não uma decisão nova:
+//   free       crossable, with no meaning of its own              → the air
+//   water      crossed by swimming                                → the water
+//   climb      height changes by interacting with it              → the ladder: it is BY it that one climbs
+//   key        satisfies a gate                                   → an object lying there, not a barrier
+//   structure  scenery: floor, wall, what holds things up         → NO
+//   gate       bars until a condition                             → NO: barring is what it does
+//   hazard     hurts on contact                                   → NO, and it is the only one I chose
+//   goal       what the round asks for                            → a case apart, see `targets` below
 //
-//   free       «atravessável e sem significado próprio»          → o ar
-//   water      «atravessa-se nadando»                            → a água
-//   climb      «muda-se de altura interagindo com isto»          → a escada: é POR ELA que se sobe
-//   key        «satisfaz um gate»                                → um objeto pousado, não uma barreira
-//   structure  «cenário: chão, parede, o que sustenta»           → NÃO
-//   gate       «barra até uma condição»                          → NÃO: barrar é o que ele faz
-//   hazard     «machuca ao encostar»                             → NÃO, e é a única onde eu escolhi
-//   goal       «o que a rodada pede»                             → caso à parte, ver `alvo` abaixo
+// ⚠️ `hazard` IS THE CHOICE, and I declare it: its metric does not say whether it can be crossed, it says what it
+// costs. A route over a spike is a route that sends the child into damage. A game where the spike is a compulsory
+// passage will have to say so another way; none does today.
 //
-// ⚠️ O `hazard` É A ESCOLHA, e declaro-a: a métrica dele não diz se se atravessa, diz o que custa. Rota que
-// passa por espinho é rota que manda a criança levar dano — e no modo cego e no modo cadeirante o próprio
-// `core/collision.isSolidType` já o trata como sólido, por decisão de acessibilidade. Encaminhar por cima
-// dele contradiria a camada que existe para a proteger. Um jogo em que o espinho seja passagem obrigatória
-// terá de dizê-lo por outro meio; hoje nenhum diz.
+// ========================= THE TARGET IS ALWAYS STEPPABLE, THE PATH IS NOT =========================
+// A `goal` may be declared on a cell that cannot be crossed (a flag inside a gate). Refusing to enter it would make
+// the route never arrive anywhere. The rule is asymmetric on purpose: **the last step is always allowed; the ones in
+// between obey the set.** It is the difference between "entering the gate" and "crossing the gate to go on".
 //
-// ========================= O ALVO É SEMPRE PISÁVEL, E O CAMINHO NÃO =========================
-// Um `goal` pode estar declarado numa célula que não se atravessa (uma bandeira dentro de um portão). Recusar
-// entrar nela faria a rota nunca chegar a lado nenhum. A regra é assimétrica de propósito: **o último passo é
-// sempre permitido; os do meio obedecem ao conjunto.** É a diferença entre «entrar no portão» e «atravessar o
-// portão para continuar do outro lado».
+// ========================= THE BUDGET, WHICH THE CONTRACT ITSELF ASKED FOR =========================
+// ⚠️ `core/contract` warns, in its section 5, that in a CONTINUOUS space the spots cannot be enumerated, and on a large
+// map enumerating would cost a frame. This module cannot ignore that because it is convenient. So it has a CEILING of
+// visited cells and returns `null` when it is hit. `null` means **"I cannot say"**, not "there is no path" — a caller
+// has to treat both alike, which is what an honest cue does: it goes quiet.
 //
-// ========================= O ORÇAMENTO, QUE O PRÓPRIO CONTRATO PEDIU =========================
-// ⚠️ `core/contract` avisa, na sua secção 5: «num espaço CONTÍNUO não há como enumerar os pontos, e num mapa
-// grande enumerar seria caro por quadro». Este módulo não pode ignorar esse aviso só porque é conveniente.
-// Por isso tem TETO de células visitadas e devolve `null` ao estourá-lo. `null` quer dizer **«não sei»**, e
-// não «não há caminho» — quem chamar tem de tratar os dois iguais, que é o que uma pista honesta faz: cala-se.
-//
-// E não importa nada além do contrato: é lógica pura, aferida no project `node`.
+// And it imports nothing but the contract: pure logic, measured in the `node` project.
 import { distance } 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 const PAPEIS_ATRAVESSAVEIS = new Set(['free', 'water', 'climb', 'key']);
-/** Este papel deixa passar? */
-export function atravessavel(papel) {
-    return PAPEIS_ATRAVESSAVEIS.has(papel);
+export const WALKABLE_ROLES = new Set(['free', 'water', 'climb', 'key']);
+/** Does this role let one through? */
+export function isWalkable(role) {
+    return WALKABLE_ROLES.has(role);
 }
-const ORCAMENTO_PADRAO = 4096;
-/** Chave de um ponto na fila. Arredondada, porque no contínuo os pontos nascem de somas de `passo`. */
-const chave = (s, casas) => s.x.toFixed(casas) + '|' + s.y.toFixed(casas) + '|' + (s.z ?? 0).toFixed(casas);
+const DEFAULT_BUDGET = 4096;
+/** A spot's key in the queue. Rounded, because in continuous space spots are born from sums of `stride`. */
+const key = (s, cells) => s.x.toFixed(cells) + '|' + s.y.toFixed(cells) + '|' + (s.z ?? 0).toFixed(cells);
 /**
- * Os deslocamentos de UM passo, na métrica declarada.
+ * The offsets of ONE step, in the declared metric.
  *
- * ⚠️ `free` (L², espaço contínuo sem passo discreto) NÃO TEM VIZINHOS — e fingir que tem é a aproximação que
- * este módulo faz e declara: ele anda numa GRELHA de lado `unit`, nas oito direções. A alternativa seria não
- * responder nada num jogo de plataforma, que é justamente o gênero da issue. Quem ler uma rota `free` está a
- * ler uma amostragem, não uma trajetória — e é por isso que `passos` é uma contagem de células e não uma
- * medida física.
+ * ⚠️ `free` (L², continuous space with no discrete step) HAS NO NEIGHBOURS — and pretending it does is the
+ * approximation this module makes and declares: it walks a GRID of side `unit`, in eight directions. The alternative
+ * would be answering nothing in a platform game, which is exactly the issue's genre. Whoever reads a `free` route is
+ * reading a sampling, not a trajectory — which is why `steps` is a count of cells and not a physical measure.
  */
-function vizinhos(topo, passo) {
-    if (topo.kind === 'hotspots')
+function neighbours(shape, stride) {
+    if (shape.kind === 'hotspots')
         return [];
-    const dims = topo.size.length;
-    const ortogonal = topo.move === 'orthogonal';
-    const fora = [];
-    const eixos = [-1, 0, 1];
-    for (const dx of eixos)
-        for (const dy of eixos) {
-            for (const dz of dims > 2 ? eixos : [0]) {
+    const dims = shape.size.length;
+    const orthogonal = shape.move === 'orthogonal';
+    const out = [];
+    const axes = [-1, 0, 1];
+    for (const dx of axes)
+        for (const dy of axes) {
+            for (const dz of dims > 2 ? axes : [0]) {
                 const n = Math.abs(dx) + Math.abs(dy) + Math.abs(dz);
                 if (n === 0)
                     continue;
-                if (ortogonal && n > 1)
-                    continue; // L¹: a diagonal não existe
-                fora.push({ x: dx * passo, y: dy * passo, z: dz * passo });
+                if (orthogonal && n > 1)
+                    continue; // L¹: there is no diagonal
+                out.push({ x: dx * stride, y: dy * stride, z: dz * stride });
             }
         }
-    return fora;
+    return out;
 }
-/** O ponto cabe na extensão declarada? Grade conta células 0..n−1; contínuo conta unidades 0..n. */
-function dentro(topo, s) {
-    if (topo.kind === 'hotspots')
+/** Does the spot fit the declared extent? A grid counts cells 0..n−1; continuous space counts units 0..n. */
+function isInside(shape, s) {
+    if (shape.kind === 'hotspots')
         return false;
-    const eixo = [s.x, s.y, s.z ?? 0];
-    for (let i = 0; i < topo.size.length; i++) {
-        const lim = topo.size[i];
-        if (eixo[i] < 0)
+    const axis = [s.x, s.y, s.z ?? 0];
+    for (let i = 0; i < shape.size.length; i++) {
+        const lim = shape.size[i];
+        if (axis[i] < 0)
             return false;
-        if (topo.kind === 'grid' ? eixo[i] > lim - 1 : eixo[i] > lim)
+        if (shape.kind === 'grid' ? axis[i] > lim - 1 : axis[i] > lim)
             return false;
     }
     return true;
 }
 /**
- * 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 function rotaAte(ctx, de, alvos) {
-    const topo = ctx.topology;
-    if (topo.kind === 'hotspots' || alvos.length === 0)
+export function routeTo(ctx, de, targets) {
+    const shape = ctx.topology;
+    if (shape.kind === 'hotspots' || targets.length === 0)
         return null;
-    const passo = topo.kind === 'continuous' ? topo.unit : 1;
-    if (!(passo > 0))
-        return null; // uma unidade de zero faria a fila andar sem sair do sítio
-    const casas = topo.kind === 'continuous' ? 4 : 0;
-    // Chegou? Na grade é a mesma célula; no contínuo é meio passo, porque a grelha não cai em cima do alvo.
-    const tolerancia = topo.kind === 'continuous' ? 0.5 : 0;
-    const chegou = (s) => alvos.find((a) => distance(topo, s, a) <= tolerancia) ?? null;
-    const alvoAqui = chegou(de);
-    if (alvoAqui)
-        return { proximo: de, ate: alvoAqui, passos: 0 };
-    const saltos = vizinhos(topo, passo);
-    const teto = ctx.orcamento ?? ORCAMENTO_PADRAO;
-    const vistos = new Set([chave(de, casas)]);
-    // Cada item leva o PRIMEIRO passo que o originou — é só isso que a pista precisa de saber no fim.
-    let fila = [{ at: de, primeiro: de, passos: 0 }];
-    while (fila.length) {
-        const proxima = [];
-        for (const item of fila) {
-            for (const d of saltos) {
-                const vizinho = { x: item.at.x + d.x, y: item.at.y + d.y, z: (item.at.z ?? 0) + (d.z ?? 0) };
-                if (!dentro(topo, vizinho))
-                    continue;
-                const k = chave(vizinho, casas);
-                if (vistos.has(k))
-                    continue;
-                vistos.add(k);
-                if (vistos.size > teto)
-                    return null; // «não sei», e é uma resposta
-                const primeiro = item.passos === 0 ? vizinho : item.primeiro;
-                // O ÚLTIMO PASSO É SEMPRE PERMITIDO: um alvo pode estar declarado numa célula que não se atravessa.
-                const alvo = chegou(vizinho);
-                if (alvo)
-                    return { proximo: primeiro, ate: alvo, passos: item.passos + 1 };
-                if (!atravessavel(ctx.roleAt(vizinho)))
-                    continue;
-                proxima.push({ at: vizinho, primeiro, passos: item.passos + 1 });
-            }
-        }
-        fila = proxima;
+    const walk = walkOf(shape);
+    // a unit of zero would make the queue go nowhere, and a negative one would walk exactly like a positive one
+    if (!(walk.step > 0))
+        return null;
+    const arrived = (s) => targets.find((a) => distance(shape, s, a) <= walk.tolerance) ?? null;
+    const targetHere = arrived(de);
+    if (targetHere)
+        return { next: de, reached: targetHere, steps: 0 };
+    const search = {
+        ctx, space: shape, arrived, keyDecimals: walk.keyDecimals, jumps: neighbours(shape, walk.step),
+        budget: ctx.budget ?? DEFAULT_BUDGET, seen: new Set([key(de, walk.keyDecimals)]),
+    };
+    let level = [{ at: de, first: de, steps: 0 }];
+    while (level.length) {
+        const next = nextLevel(search, level);
+        if (!Array.isArray(next))
+            return next;
+        level = next;
     }
     return null;
 }
+/** How a space is walked: the step, the decimals a point's key keeps, and how close counts as arrived. On a grid it is the
+ *  same cell; in a continuous space half a step, because the sampling grid does not fall on the target. */
+function walkOf(space) {
+    return space.kind === 'continuous' ? { step: space.unit, keyDecimals: 4, tolerance: 0.5 } : { step: 1, keyDecimals: 0, tolerance: 0 };
+}
+/** Where one jump from a point lands, on every axis the space has. */
+const stepFrom = (at, d) => ({ x: at.x + d.x, y: at.y + d.y, z: (at.z ?? 0) + (d.z ?? 0) });
+/** One ring further out. A route when a target is reached, `null` when the budget ran out («I cannot say», which is an
+ *  answer), or the next ring. */
+function nextLevel(s, level) {
+    const next = [];
+    for (const item of level) {
+        for (const d of s.jumps) {
+            const neighbour = stepFrom(item.at, d);
+            if (!isInside(s.space, neighbour))
+                continue;
+            const k = key(neighbour, s.keyDecimals);
+            if (s.seen.has(k))
+                continue;
+            s.seen.add(k);
+            if (s.seen.size > s.budget)
+                return null;
+            const first = item.steps === 0 ? neighbour : item.first;
+            // THE LAST STEP IS ALWAYS ALLOWED: a target may be declared on a cell that cannot be crossed.
+            const target = s.arrived(neighbour);
+            if (target)
+                return { next: first, reached: target, steps: item.steps + 1 };
+            if (isWalkable(s.ctx.roleAt(neighbour)))
+                next.push({ at: neighbour, first, steps: item.steps + 1 });
+        }
+    }
+    return next;
+}

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

@@ -1,68 +1,65 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 /**
- * Uma cena. Todos os ganchos são OPCIONAIS de propósito: uma tela de título que só desenha não deveria
- * precisar declarar um `update` vazio, e um diálogo que só ouve não deveria precisar declarar um `draw`.
+ * A scene. Every hook is OPTIONAL on purpose: a title screen that only draws should not have to declare an empty
+ * `update`, and a dialog that only listens should not have to declare a `draw`.
  */
 export interface Scene {
-    /** Nome legível — para depuração e para os testes afirmarem a pilha por nome, não por identidade. */
-    readonly nome: string;
-    /** Chamado ao ENTRAR (push, ou ao reaparecer no topo por um pop). */
+    /** A readable name — for debugging, and so tests assert the stack by name, not identity. */
+    readonly name: string;
+    /** Called on ENTERING (push, or reappearing on top after a pop). */
     enter?(): void;
-    /** Chamado ao SAIR (pop, ou ao ser coberto por um push). */
+    /** Called on LEAVING (pop, or being covered by a push). */
     exit?(): void;
-    /** Tempo. Só o topo recebe. */
+    /** Time. Only the top gets it. */
     update?(dt: number): void;
-    /** Desenho. Todas recebem, de baixo para cima. */
+    /** Drawing. All get it, bottom up. */
     draw?(): void;
-    /** Entrada. Só o topo recebe. Devolva `true` se consumiu — `false`/nada deixa a tecla seguir. */
+    /** Input. Only the top gets it. Return `true` if consumed — `false`/nothing lets the key go on. */
     input?(intent: string): boolean | void;
 }
 export interface SceneStack {
-    /** Empilha `s` no topo. A anterior recebe `exit()` mas CONTINUA na pilha (e continua sendo desenhada). */
+    /** Pushes `s` on top. The previous one gets `exit()` but STAYS on the stack (and is still drawn). */
     push(s: Scene): void;
-    /** Desempilha o topo e devolve-o (ou `null` se vazia). Quem reaparecer recebe `enter()`. */
+    /** Pops the top and returns it (or `null` if empty). Whoever reappears gets `enter()`. */
     pop(): Scene | null;
-    /** Troca o topo — `pop` seguido de `push`, numa chamada, porque é o que "ir para outra tela" quer dizer. */
+    /** Swaps the top — `pop` then `push` in one call, because that is what "go to another screen" means. */
     replace(s: Scene): void;
-    /** A cena do topo, ou `null`. */
+    /** The top scene, or `null`. */
     top(): Scene | null;
-    /** Os nomes, da base para o topo. Cópia: quem lê não muta a pilha por acidente. */
-    nomes(): string[];
+    /** The names, bottom to top. A copy: whoever reads cannot mutate the stack by accident. */
+    names(): string[];
     update(dt: number): void;
     draw(): void;
-    /** Devolve `true` se a cena do topo consumiu a intenção. */
+    /** Returns `true` if the top scene consumed the intent. */
     input(intent: string): boolean;
 }
 /**
- * Cria uma pilha vazia.
+ * Creates an empty stack.
  *
- * ⚠️ `enter`/`exit` são chamados em TRY/CATCH? NÃO — e é decisão, não esquecimento. Um erro dentro de
- * `enter()` significa que a cena não montou; engolir isso deixaria a pilha num estado que ninguém declarou, e
- * o sintoma apareceria três quadros depois, longe da causa. As chamadas de `update`/`draw`/`input` também
- * propagam: a engine não é o lugar de decidir que o erro de um jogo não importa.
+ * ⚠️ Are `enter`/`exit` called inside TRY/CATCH? NO — and it is a decision, not an oversight. An error inside `enter()`
+ * means the scene did not mount; swallowing it would leave the stack in a state nobody declared, and the symptom would
+ * show three frames later, far from the cause. `update`/`draw`/`input` propagate too: the engine is not the place to
+ * decide that a game's error does not matter.
  */
-export declare function criarPilha(): SceneStack;
+export declare function createSceneStack(): SceneStack;
 /**
- * O QUE A CASCA PRECISA SABER DA CENA — três booleanos, e nenhum nome de fase.
+ * WHAT THE SHELL NEEDS TO KNOW ABOUT THE SCENE — three booleans, and no phase name.
  *
- * Era `Phase = 'title' | 'playing' | 'paused'`, importado de `core/state`. O ADR-0030 registra ALARGAR essa
- * união como NÃO-OPÇÃO, e a razão é curta: um segundo jogo continuaria amarrado ao NOSSO vocabulário — um
- * jogo com mapa de fases ou tela de resultados teria de pedir uma constante nova à engine para existir.
+ * It was a `Phase` union. Widening it is a NON-OPTION (ADR-0030): a second game would stay tied to OUR vocabulary.
  *
- * E o repositório já aprendeu isto uma vez, por evidência e não por gosto: o `consumer-quiz` precisou se
- * declarar "pausado" para navegar os próprios menus, porque o `menu-nav` importava a fase. A correção de lá
- * foi trocar `getPhase()` por `isNavigable()`, um BOOLEANO — e está registrada em `core/constants` como o
- * erro a não repetir. Isto aqui é a mesma correção, aplicada à casca inteira.
+ * And the repository already learned this once, by evidence and not taste: the demo quiz had to declare itself
+ * "paused" to walk its own menus, because the menu navigation imported the phase. The fix there was a BOOLEAN,
+ * `isNavigable()`. This is the same fix, applied to the whole shell.
  *
- * Quem NOMEIA as cenas é a raiz de composição, que é este jogo. Ela monta a pilha (`core/scenes`) e traduz o
- * topo nestes três fatos. Uma quarta cena que a casca não conheça responde `false` nos três, e a projeção
- * abaixo continua fazendo sentido: sem splash, sem menu de pausa, som mudo, foco no título.
+ * Whoever NAMES the scenes is the composition root. It builds the stack and translates the top into these three facts.
+ * A fourth scene the shell does not know answers `false` to all three, and the projection still makes sense: no splash,
+ * no pause menu, sound muted, focus on the title.
  */
-export interface FatosDaCena {
-    /** O topo é a tela de título (o splash cobre o mundo). */
-    telaDeTitulo: boolean;
-    /** O topo é o JOGO — o mundo recebe tempo, o som toca, o controle de toque pode aparecer. */
-    mundoRodando: boolean;
-    /** O topo é o menu de pausa. O jogo continua na pilha por baixo, e continua desenhado. */
-    menuDePausa: boolean;
+export interface SceneFacts {
+    /** The top is the title screen (the splash covers the world). */
+    titleScreen: boolean;
+    /** The top is the GAME — the world gets time, sound plays, the touch pad may appear. */
+    worldRunning: boolean;
+    /** The top is the pause menu. The game stays on the stack below, still drawn. */
+    pauseMenu: boolean;
 }

package/dist-pkg/core/scenes.js

@@ -1,64 +1,62 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// core/scenes — A PILHA DE CENAS (item 22, opção C3 do ADR-0030). Módulo-FOLHA: zero dependências, zero I/O.
+// core/scenes — THE SCENE STACK (item 22, option C3 of ADR-0030). A LEAF module: no dependencies, no I/O.
 //
-// ========================= O QUE ELA SUBSTITUI, E POR QUE NÃO É UM ENUM MAIOR =========================
-// Hoje o jogo tem `phase: 'title' | 'playing' | 'paused'` em `core/state`, lido por doze módulos. O ADR-0030
-// registra C1 — alargar essa união — como NÃO-OPÇÃO, e a razão é curta: um segundo jogo continuaria amarrado
-// ao NOSSO enum. Um jogo com tela de mapa, um com tela de resultados, um com senha entre sessões (item 23)
-// precisariam pedir uma constante nova na engine para existir.
+// ========================= WHAT IT REPLACES, AND WHY IT IS NOT A BIGGER ENUM =========================
+// A `phase: 'title' | 'playing' | 'paused'` union is a vocabulary, and ADR-0030 records widening it (C1) as a
+// NON-OPTION for a short reason: a second game would stay tied to OUR enum. A game with a map screen, one with a
+// results screen, one with a password between sessions would each have to ask the engine for a new constant to exist.
 //
-// Uma PILHA não tem esse problema porque não tem vocabulário: ela sabe que há cenas empilhadas e nada sobre o
-// que cada uma significa. `title/playing/paused` vira `[titulo]`, `[jogo]`, `[jogo, pausa]` — e um mapa de
-// fases vira `[mapa]` sem que este arquivo mude uma linha.
+// A STACK does not have that problem because it has no vocabulary: it knows scenes are stacked and nothing about what
+// each means. `title/playing/paused` becomes `[title]`, `[game]`, `[game, pause]` — and a level map becomes `[map]`
+// without this file changing a line.
 //
-// ========================= AS TRÊS REGRAS, E O QUE CADA UMA PRESERVA =========================
-// Elas não são convenção de biblioteca: cada uma reproduz um comportamento que o jogo já tem.
+// ========================= THE THREE RULES, AND WHAT EACH PRESERVES =========================
+// They are not library convention: each reproduces a behaviour the game already has.
 //
-//   · `update` SÓ NO TOPO. É o congelamento da pausa. Hoje ele é `if (phase !== 'playing') return` espalhado;
-//     aqui é estrutural — uma cena que não está no topo não recebe tempo, ponto.
-//   · `draw` DE BAIXO PARA CIMA. É o menu de pausa desenhado SOBRE o mundo, com o mundo ainda visível. Se
-//     desenhasse só o topo, pausar apagaria o jogo da tela.
-//   · `input` SÓ NO TOPO, e ele DIZ se consumiu. É a mesma forma que o ADR-0033 deu à entrada modal: quem
-//     está por cima decide, e o que ele não quer volta a descer. Sem o retorno, a pilha teria de adivinhar.
+//   · `update` ONLY AT THE TOP. It is the pause freeze — structural here: a scene that is not on top gets no time.
+//   · `draw` FROM THE BOTTOM UP. It is the pause menu drawn OVER the world, with the world still visible. Drawing only
+//     the top would make pausing erase the game from the screen.
+//   · `input` ONLY AT THE TOP, and it SAYS whether it consumed. The shape ADR-0033 gave modal input: whoever is on
+//     top decides, and what they do not want goes back down. Without the return value the stack would have to guess.
 //
-// ========================= O QUE ELA NÃO FAZ =========================
-// Não desenha, não escuta evento, não conhece PIXI nem DOM. Recebe `dt` e devolve nada; recebe uma intenção e
-// devolve um booleano. É o que a torna testável sem navegador e importável dos dois lados da fronteira.
+// ========================= WHAT IT DOES NOT DO =========================
+// It does not draw, listen for events, or know PIXI or the DOM. It takes `dt` and returns nothing; it takes an intent
+// and returns a boolean. That is what makes it testable without a browser and importable from both sides of the boundary.
 /**
- * Cria uma pilha vazia.
+ * Creates an empty stack.
  *
- * ⚠️ `enter`/`exit` são chamados em TRY/CATCH? NÃO — e é decisão, não esquecimento. Um erro dentro de
- * `enter()` significa que a cena não montou; engolir isso deixaria a pilha num estado que ninguém declarou, e
- * o sintoma apareceria três quadros depois, longe da causa. As chamadas de `update`/`draw`/`input` também
- * propagam: a engine não é o lugar de decidir que o erro de um jogo não importa.
+ * ⚠️ Are `enter`/`exit` called inside TRY/CATCH? NO — and it is a decision, not an oversight. An error inside `enter()`
+ * means the scene did not mount; swallowing it would leave the stack in a state nobody declared, and the symptom would
+ * show three frames later, far from the cause. `update`/`draw`/`input` propagate too: the engine is not the place to
+ * decide that a game's error does not matter.
  */
-export function criarPilha() {
-    const pilha = [];
+export function createSceneStack() {
+    const stack = [];
     return {
         push(s) {
-            pilha[pilha.length - 1]?.exit?.();
-            pilha.push(s);
+            stack[stack.length - 1]?.exit?.();
+            stack.push(s);
             s.enter?.();
         },
         pop() {
-            const fora = pilha.pop() ?? null;
-            fora?.exit?.();
-            pilha[pilha.length - 1]?.enter?.();
-            return fora;
+            const out = stack.pop() ?? null;
+            out?.exit?.();
+            stack[stack.length - 1]?.enter?.();
+            return out;
         },
         replace(s) {
-            // NÃO é `this.pop()` seguido de `this.push(s)`: isso daria `enter()` à cena de baixo por um instante,
-            // e ela reapareceria no topo entre as duas chamadas. Trocar é UMA transição, não duas.
-            const fora = pilha.pop() ?? null;
-            fora?.exit?.();
-            pilha.push(s);
+            // NOT `this.pop()` then `this.push(s)`: that would give the scene below an `enter()` for an instant, and it
+            // would reappear on top between the two calls. Swapping is ONE transition, not two.
+            const out = stack.pop() ?? null;
+            out?.exit?.();
+            stack.push(s);
             s.enter?.();
         },
-        top() { return pilha[pilha.length - 1] ?? null; },
-        nomes() { return pilha.map((s) => s.nome); },
-        update(dt) { pilha[pilha.length - 1]?.update?.(dt); },
-        draw() { for (const s of pilha)
+        top() { return stack[stack.length - 1] ?? null; },
+        names() { return stack.map((s) => s.name); },
+        update(dt) { stack[stack.length - 1]?.update?.(dt); },
+        draw() { for (const s of stack)
             s.draw?.(); },
-        input(intent) { return pilha[pilha.length - 1]?.input?.(intent) === true; },
+        input(intent) { return stack[stack.length - 1]?.input?.(intent) === true; },
     };
 }

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

@@ -1,15 +1,15 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** Colunas e linhas da grade para `n` telas. */
+/** Columns and rows of the grid for `n` screens. */
 export interface ScreenGrid {
     cols: number;
     rows: number;
 }
 /**
- * A grade para `n` jogadores: 1 -> 1x1 · 2 -> 2x1 · 3 e 4 -> 2x2.
- * `n` menor que 1 devolve a grade de uma tela, e não zero colunas.
+ * The grid for `n` players: 1 -> 1x1 · 2 -> 2x1 · 3 and 4 -> 2x2.
+ * `n` below 1 gives the grid of one screen, not zero columns.
  */
 export declare function screenGrid(n: number): ScreenGrid;
-/** Dimensões em pixels de arte da grade de `n` telas (320x180 por tela — o pixel canônico do ADR-0010). */
+/** Size in art pixels of the grid of `n` screens (320x180 per screen — the canonical pixel of ADR-0010). */
 export declare function screenBaseSize(n: number): {
     w: number;
     h: number;