@the-inclusionist/engine 6.36.1

package/dist-pkg/core/loop.js

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// core/loop.ts — driver do loop de jogo. Registra a função de frame num "ticker" (o app.ticker do PixiJS, ou
+// qualquer objeto com .add(fn) e .deltaTime) e passa o dt CLAMPADO (evita saltos gigantes após a aba ficar em
+// segundo plano). Módulo-folha. Mantém a cadência ATUAL (não muda o timing) — o fixed-timestep determinístico
+// fica para depois, pois mudaria a física.
+//
+// ========================= O BOUNDARY DE ERRO (D16), E POR QUE ELE FALHA ALTO =========================
+// Sem ele, um quadro que lança lança OUTRA VEZ no quadro seguinte, para sempre: tela congelada, console cheio, e
+// nada na tela dizendo o que houve. A spec do `demos` pede isto por escala — "across 383 games, one bad game has
+// to be distinguishable from a broken engine". A razão daqui é mais urgente: **criança cega não vê tela
+// congelada.** Sem anúncio, o modo cego não distingue "travou" de "está pensando".
+//
+// ⚠️ E A TENTAÇÃO É O CONTRÁRIO DO CONSERTO. `try { frame() } catch { /* segue */ }` é pior que o defeito: vira
+// jogo silenciosamente errado, rodando para sempre computando lixo. A regra aqui é a mesma que o ADR-0047 aplicou
+// ao CRT — pega UMA vez, PARA, e ANUNCIA.
+export function startLoop(ticker, frame, maxDt = 2, opcoes = {}) {
+    let parado = false;
+    const passo = () => {
+        if (parado)
+            return; // ticker sem `remove` não desregistra — a trava é o que faz o laço parar mesmo assim
+        try {
+            frame(Math.min(ticker.deltaTime, maxDt));
+        }
+        catch (erro) {
+            parado = true;
+            ticker.remove?.(passo); // some do ticker quando dá: callback que roda 60×/s para nada custa em hardware fraco
+            // O anúncio não pode ressuscitar o problema. Se o próprio aviso quebrar — sem leitor de tela, sem DOM —,
+            // uma exceção aqui voltaria a ser invisível dentro do ticker, que é exatamente o defeito que isto fecha.
+            try {
+                opcoes.aoFalhar?.(erro);
+            }
+            catch { /* noop: o aviso falhou; o laço já parou, que é o essencial */ }
+        }
+    };
+    ticker.add(passo);
+}

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

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Um campo do esquema: um nome e quantos BITS ele ocupa (⇒ valores de 0 a 2^bits − 1). */
+export interface CampoSenha {
+    readonly nome: string;
+    readonly bits: number;
+}
+export interface CodecSenha {
+    /** Quantos caracteres a senha tem, sem separadores. Constante: toda senha deste esquema tem este tamanho. */
+    readonly comprimento: number;
+    /** Os campos, na ordem em que foram declarados (cópia — quem lê não altera o esquema). */
+    readonly campos: readonly CampoSenha[];
+    /** Empacota os valores. Lança se algum campo faltar ou não couber — ver a nota em `codificar`. */
+    codificar(valores: Readonly<Record<string, number>>): string;
+    /** Desempacota. `null` = senha inválida (comprimento, símbolo, soma ou enchimento). */
+    decodificar(senha: string): Record<string, number> | null;
+}
+/** Crockford base32: sem I, L, O e U. Índice = valor de 5 bits. */
+export declare const ALFABETO = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/**
+ * Cria um codec para o esquema `campos`.
+ *
+ * ⚠️ LANÇA em esquema malformado, e isso é decisão: um esquema errado é erro de PROGRAMA, e um erro de
+ * programa que só aparece como senha estranha três meses depois custa mais caro que um boot que não sobe.
+ * É a mesma escolha de `boot/create-game` para a declaração malformada.
+ */
+export declare function criarCodec(campos: readonly CampoSenha[]): CodecSenha;
+/**
+ * Insere um separador a cada `grupo` caracteres — `'A1B2C3D4'` vira `'A1B2-C3D4'`.
+ *
+ * É acessibilidade, não enfeite: uma sequência sem grupos é lida caractere a caractere pelo leitor de tela e
+ * copiada perdendo o lugar por quem lê da tela para o caderno. `decodificar` ignora o separador, então a
+ * senha agrupada e a senha corrida são a MESMA senha — quem digitar sem o traço não é punido por isso.
+ */
+export declare function formatar(senha: string, grupo?: number, sep?: string): string;

package/dist-pkg/core/password.js

@@ -0,0 +1,205 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// core/password — O CODEC DE CÓDIGOS CURTOS copiados à mão. Módulo-FOLHA: zero dependências, zero I/O, zero DOM.
+//
+// ========================= PARA QUE ESTE CODEC EXISTE — E PARA QUE ELE NÃO EXISTE MAIS =========================
+// Ele nasceu para outra coisa, e a honestidade do arquivo depende de dizer isso.
+//
+// A primeira versão era uma SENHA DE PROGRESSÃO: a criança anotava quatro letras no caderno e recuperava o
+// nível de alfabetização numa máquina de escola restaurada de madrugada. O ADR-0034 registrou o desenho
+// inteiro; o ADR-0037 o enterrou, e a razão veio do Dev, não de um defeito: **não existe salvar jogo, e não
+// deve existir**. Os jogos têm cinco fases e terminam em quinze minutos. Uma senha para recuperar progresso
+// de uma partida que acaba antes do recreio é máquina sem carga.
+//
+// O QUE SOBROU, e é o motivo de o arquivo continuar aqui: a única senha que o desenho tem é a que o PROFESSOR
+// cria para a turma entrar na mesma sala. Enquanto não houver servidor, essa sala é o computador do professor
+// na rede local. E um código de sala é o mesmo problema de engenharia que uma senha de progressão — poucos
+// bits, copiados do quadro por uma criança de sete anos, onde um erro de cópia ACEITO é pior que um recusado.
+// Por isso o codec permaneceu inteiro e o registro do lado do jogo (`game/progress`) foi apagado: o que morreu
+// foi o significado dos campos, não a aritmética.
+//
+// ⚠️ NENHUM CHAMADOR HOJE. Este módulo está sem consumidor desde que `game/progress` saiu, e isso está dito
+// aqui em vez de descoberto por alguém daqui a três meses. Ele fica porque a tela de sala vai precisar dele e
+// porque apagá-lo custaria reescrever a verificação exaustiva que já está testada — não porque esteja em uso.
+//
+// ========================= O QUE ESTE MÓDULO SABE, E O QUE ELE NUNCA SABERÁ =========================
+// A regra do ADR-0033 vale aqui inteira: "a entidade da engine pode declarar o que a ENGINE possui; não pode
+// declarar o que o JOGO possui". Uma senha com os campos `nivel`, `pontos` e `fases` seria exatamente a
+// violação que o ADR proíbe — seriam os campos DESTE jogo, congelados na engine, e o segundo consumidor
+// (`quiz.html`) teria de fingir ter um "nivel" para caber.
+//
+// Então este módulo não conhece campo nenhum: ele recebe um ESQUEMA — uma lista de `{nome, bits}` que o jogo
+// declara — e sabe empacotar inteiros pequenos em símbolos legíveis, com sobra de detecção de erro. O que a
+// engine possui é a CODIFICAÇÃO; o que o jogo possui é o significado de cada campo.
+//
+// ========================= AS TRÊS DECISÕES QUE FAZEM O CÓDIGO SERVIR A UMA CRIANÇA =========================
+//
+// 1. O ALFABETO É DE 32 SÍMBOLOS, SEM I, L, O E U (o de Crockford). Os três primeiros saem por ambiguidade
+//    visual — I/1, L/1, O/0 são o erro clássico de quem copia de um caderno a lápis; o U sai porque sem ele
+//    o alfabeto não forma palavrão por acidente, e uma senha que sorteia uma ofensa na tela de uma sala de
+//    aula é um problema real, não hipotético. O que sobra são 32 símbolos = 5 bits exatos por caractere.
+//    A leniência de Crockford entra na LEITURA: quem digitar I, L ou O recebe 1, 1 e 0. Escrever nunca os
+//    produz; ler perdoa quem os escreveu. E o ADR-0027 diz que a entrada não é teclado, é GRADE DE LETRAS —
+//    32 símbolos cabem numa grade 8x4 legível a 320x180, que é o que a grade precisa desenhar.
+//
+// 2. A VERIFICAÇÃO É EXATA PARA OS DOIS ERROS QUE A CRIANÇA COMETE, e não "provável". Um dígito de soma
+//    simples de 5 bits deixaria 1 código errado em 32 passar — e um código errado que PASSA é pior que um
+//    rejeitado: ele leva a criança para OUTRA SALA, com a atividade de outra turma, e ninguém na sala entende
+//    por quê. Aqui a soma é PONDERADA PELA POSIÇÃO, módulo 1021, em 2 símbolos:
+//      · trocar UM símbolo por outro, em qualquer posição → SEMPRE detectado (a diferença que ele causa na
+//        soma é (i+1)·d, e |(i+1)·d| < 1021, logo nunca cai em zero por acaso do módulo);
+//      · TROCAR DOIS símbolos DO CORPO de lugar           → SEMPRE detectado ((i−j)·(vj−vi), idem).
+//    Não é probabilidade: é aritmética, e é por isso que `criarCodec` limita o corpo a 32 símbolos — acima
+//    disso o produto passaria de 1021 e a garantia cairia em silêncio. O que fica de fora da garantia é a
+//    troca de um símbolo do corpo com um dos dois da soma; para essa, e para uma senha forjada ao acaso, a
+//    chance de colar é ~1/1021.
+//    ⚠️ O QUE DÁ A GARANTIA É O TAMANHO DO MÓDULO, NÃO A PRIMALIDADE — e eu conferi em vez de supor: trocar
+//    1021 por 1024 (potência de dois) NÃO faz nenhum dos 26 casos deste módulo falhar. É informação sobre o
+//    alcance do teste, e fica registrada aqui em vez de virar uma crença. 1021 continua sendo a escolha por
+//    ser o maior primo abaixo do teto de dois símbolos: para as duas classes provadas os dois módulos
+//    empatam, mas um módulo com fator 2^k é cego a erros MÚLTIPLOS cuja diferença total seja múltipla dele,
+//    e um primo não tem esse buraco de graça.
+//
+// 3. `decodificar` DEVOLVE `null`, e não uma exceção nem um objeto "meio válido". Senha errada é o caso
+//    NORMAL desta função — é o que acontece quando a criança erra uma letra —, e caso normal não se sinaliza
+//    com exceção. Quem chama sabe o comprimento esperado (`codec.comprimento`) e pode distinguir "faltam
+//    letras" de "senha errada" sem que este módulo invente vocabulário de interface para isso.
+/** Crockford base32: sem I, L, O e U. Índice = valor de 5 bits. */
+export const ALFABETO = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/** O módulo da soma ponderada. Ver a decisão 2 no topo: é o TAMANHO dele que dá a garantia, e o limite de 32. */
+const MODULO = 1021;
+/** Símbolos do corpo, no máximo. Acima disso a garantia da soma cairia sem nenhum sintoma visível. */
+const MAX_SIMBOLOS = 32;
+const VALOR_DE = new Map();
+for (let i = 0; i < ALFABETO.length; i++)
+    VALOR_DE.set(ALFABETO[i], i);
+// A leniência de Crockford, só na LEITURA. Escrever jamais produz estes três.
+VALOR_DE.set('I', 1);
+VALOR_DE.set('L', 1);
+VALOR_DE.set('O', 0);
+/**
+ * A soma ponderada pela posição, módulo `MODULO`, como DOIS símbolos.
+ *
+ * O peso `i+1` (e não `i`) é o que faz o primeiro símbolo contar: com peso 0, trocar o primeiro caractere
+ * por qualquer outro passaria despercebido — e o primeiro caractere é justamente o que mais se digita errado.
+ */
+function soma(simbolos) {
+    let c = 0;
+    for (let i = 0; i < simbolos.length; i++)
+        c = (c + (i + 1) * simbolos[i]) % MODULO;
+    return [(c >> 5) & 31, c & 31];
+}
+/**
+ * Cria um codec para o esquema `campos`.
+ *
+ * ⚠️ LANÇA em esquema malformado, e isso é decisão: um esquema errado é erro de PROGRAMA, e um erro de
+ * programa que só aparece como senha estranha três meses depois custa mais caro que um boot que não sobe.
+ * É a mesma escolha de `boot/create-game` para a declaração malformada.
+ */
+// ⚠️ AS MENSAGENS DE ERRO ABAIXO ESTÃO EM INGLÊS, e os comentários deste arquivo não. Não é descuido: o gate
+// `tests/engine-i18n.node.test.js` reprovou este módulo quando elas nasceram em português, e a gaveta que ele
+// oferece — "mensagens de programador", onde já moram `core/contract`, `boot/create-game` e `render/sprites` —
+// só me aceitaria subindo o teto global de 76 para 82 no mesmo commit que cria a dívida. Afrouxar o gate para
+// caber nele é o defeito que o gate existe para impedir. Comentário não vai para tela nenhuma e segue em
+// pt-BR, como no resto do repositório; STRING vai, mesmo que só até o console de quem programa.
+export function criarCodec(campos) {
+    if (campos.length === 0) {
+        throw new Error('core/password: empty schema — a password with zero fields carries only its own checksum. Declare at least one field, or skip the codec.');
+    }
+    const vistos = new Set();
+    let bitsTotal = 0;
+    for (const c of campos) {
+        if (!c.nome)
+            throw new Error('core/password: field without a name — the name is the key it gets in the object `decodificar` returns.');
+        if (vistos.has(c.nome))
+            throw new Error(`core/password: field "${c.nome}" declared twice — the second one would shadow the first when reading.`);
+        vistos.add(c.nome);
+        if (!Number.isInteger(c.bits) || c.bits < 1 || c.bits > 30) {
+            throw new Error(`core/password: field "${c.nome}" asks for ${c.bits} bits — use an integer from 1 to 30 (a 0-bit field stores nothing; above 30 the bitwise arithmetic in JS stops being exact).`);
+        }
+        bitsTotal += c.bits;
+    }
+    const simbolosCorpo = Math.ceil(bitsTotal / 5);
+    if (simbolosCorpo > MAX_SIMBOLOS) {
+        throw new Error(`core/password: ${bitsTotal} bits would take ${simbolosCorpo} symbols, and above ${MAX_SIMBOLOS} the weighted checksum stops detecting EVERY transposition (see decision 2 at the top). Store less, or split it into two passwords.`);
+    }
+    const listaCampos = campos.map((c) => Object.freeze({ nome: c.nome, bits: c.bits }));
+    return {
+        comprimento: simbolosCorpo + 2,
+        campos: Object.freeze(listaCampos),
+        codificar(valores) {
+            // Bit a bit, do mais significativo ao menos, na ordem declarada. Escrito assim — e não com `<<` sobre
+            // um acumulador — porque um esquema de 40 bits estouraria os 32 bits dos operadores do JS, e o sintoma
+            // seria uma senha que decodifica errado só nos campos do fim.
+            const bits = [];
+            for (const c of listaCampos) {
+                const v = valores[c.nome];
+                const teto = 2 ** c.bits - 1;
+                if (typeof v !== 'number' || !Number.isInteger(v) || v < 0 || v > teto) {
+                    throw new Error(`core/password: field "${c.nome}" got ${String(v)} — expected an integer from 0 to ${teto}. Fix the value BEFORE encoding (clamping here silently would write a password that restores different progress).`);
+                }
+                for (let b = c.bits - 1; b >= 0; b--)
+                    bits.push((v >> b) & 1);
+            }
+            while (bits.length % 5 !== 0)
+                bits.push(0); // enchimento: zeros à direita, conferidos na leitura
+            const simbolos = [];
+            for (let i = 0; i < bits.length; i += 5) {
+                simbolos.push((bits[i] << 4) | (bits[i + 1] << 3) | (bits[i + 2] << 2) | (bits[i + 3] << 1) | bits[i + 4]);
+            }
+            const [s1, s2] = soma(simbolos);
+            return [...simbolos, s1, s2].map((v) => ALFABETO[v]).join('');
+        },
+        decodificar(senha) {
+            if (typeof senha !== 'string')
+                return null;
+            const cru = [];
+            for (const ch of senha.toUpperCase()) {
+                if (ch === ' ' || ch === '-' || ch === '·')
+                    continue; // separadores de leitura (ver `formatar`)
+                const v = VALOR_DE.get(ch);
+                if (v === undefined)
+                    return null; // símbolo fora do alfabeto: não vale adivinhar o que ela quis dizer
+                cru.push(v);
+            }
+            if (cru.length !== simbolosCorpo + 2)
+                return null;
+            const simbolos = cru.slice(0, simbolosCorpo);
+            const [s1, s2] = soma(simbolos);
+            if (s1 !== cru[simbolosCorpo] || s2 !== cru[simbolosCorpo + 1])
+                return null;
+            const bits = [];
+            for (const v of simbolos)
+                for (let b = 4; b >= 0; b--)
+                    bits.push((v >> b) & 1);
+            // O enchimento tem de ser zero: `codificar` só produz zeros ali. Uma senha com lixo no fim não saiu
+            // daqui, e aceitá-la seria aceitar uma senha que este módulo é incapaz de gerar.
+            for (let i = bitsTotal; i < bits.length; i++)
+                if (bits[i] !== 0)
+                    return null;
+            const fora = {};
+            let p = 0;
+            for (const c of listaCampos) {
+                let v = 0;
+                for (let b = 0; b < c.bits; b++)
+                    v = v * 2 + bits[p++];
+                fora[c.nome] = v;
+            }
+            return fora;
+        },
+    };
+}
+/**
+ * Insere um separador a cada `grupo` caracteres — `'A1B2C3D4'` vira `'A1B2-C3D4'`.
+ *
+ * É acessibilidade, não enfeite: uma sequência sem grupos é lida caractere a caractere pelo leitor de tela e
+ * copiada perdendo o lugar por quem lê da tela para o caderno. `decodificar` ignora o separador, então a
+ * senha agrupada e a senha corrida são a MESMA senha — quem digitar sem o traço não é punido por isso.
+ */
+export function formatar(senha, grupo = 4, sep = '-') {
+    if (grupo < 1)
+        return senha;
+    const partes = [];
+    for (let i = 0; i < senha.length; i += grupo)
+        partes.push(senha.slice(i, i + grupo));
+    return partes.join(sep);
+}

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

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Uma corrente de números pseudoaleatórios independente de qualquer outra. */
+export interface Rng {
+    /** [0, 1). */
+    readonly rnd: () => number;
+    /** Inteiro em [lo, hi], ambos inclusive. */
+    readonly randInt: (lo: number, hi: number) => number;
+    /** Cópia baralhada (Fisher-Yates); não toca no original. */
+    readonly shuffle: <T>(arr: readonly T[]) => T[];
+    /** Reposiciona ESTA corrente. Não alcança nenhuma outra. */
+    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;

package/dist-pkg/core/rng.js

@@ -0,0 +1,61 @@
+// 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.
+//
+// ⚠️ DUAS COISAS MUDARAM AQUI NA MESMA MIGRAÇÃO, E ISSO É DE PROPÓSITO (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.
+//
+// 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.
+//
+// ⚠️ 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.
+    const rnd = () => (_seed = (Math.imul(_seed, 1103515245) + 12345) & 0x7fffffff) / 0x7fffffff;
+    const randInt = (lo, hi) => lo + Math.floor(rnd() * (hi - lo + 1));
+    const shuffle = (arr) => {
+        const a = [...arr];
+        for (let i = a.length - 1; i > 0; i--) {
+            const j = (rnd() * (i + 1)) | 0;
+            [a[i], a[j]] = [a[j], a[i]];
+        }
+        return a;
+    };
+    const reseed = (s) => { _seed = s >>> 0; };
+    return { rnd, randInt, shuffle, reseed };
+};
+// ⚠️ A CORRENTE DO JOGO PRÓPRIO DA ENGINE, e SÓ dela. Existe porque `game/` ainda vive aqui dentro
+// (issue #111: o cartucho que ainda não saiu, ADR-0036/ADR-0083). Quando `game/` sair, isto sai com ele.
+// UM CONSUMIDOR EXTERNO NÃO DEVE IMPORTAR ESTES QUATRO — são estado partilhado, que é o defeito que a
+// fábrica acima conserta. Faça `createRng(suaSemente)`.
+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/rotulo-acessivel.d.ts

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** A fatia mínima de `Element` que este módulo lê. Estrutural para o teste de node não precisar de DOM real. */
+export interface ElementoComRotulo {
+    getAttribute(nome: string): string | null;
+    textContent: string | null;
+}
+/**
+ * O nome do controle: `aria-label` quando existe, o texto visível quando não.
+ *
+ * A ORDEM É A DECISÃO, e ela não é arbitrária: `aria-label` é o que a plataforma de acessibilidade JÁ vai
+ * anunciar. Narrar outra coisa não acrescenta informação — cria uma segunda versão do mesmo item, e quem
+ * escuta as duas não tem como saber qual é a verdadeira.
+ *
+ * O texto visível entra quando não há rótulo declarado, que é o caso da maioria dos botões: ali as duas
+ * fontes já coincidem por construção.
+ */
+export declare function rotuloAcessivel(el: ElementoComRotulo | null | undefined): string;

package/dist-pkg/core/rotulo-acessivel.js

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// core/rotulo-acessivel — COMO SE CHAMA UM CONTROLE, e uma resposta só para quem vê e para quem escuta.
+//
+// ========================= O DEFEITO QUE ISTO FECHA =========================
+// MEDIDO no jogo construído, pousando o cursor no botão de número de jogadores do menu inicial:
+//
+//     o jogo narrou:         "◀ Number of players: 1 ▶, 1 of 4"
+//     o leitor de tela diz:  "Number of players: 1. Click on the left for fewer, on the right for more."
+//
+// Duas frases diferentes para o MESMO item, no mesmo instante. Uma criança que usa leitor de tela E a
+// narração do jogo ouve o item duas vezes, de dois jeitos — e a versão do jogo lê os glifos `◀` e `▶`, que é
+// exatamente o ruído que o item 4 do ADR-0044 tirou da legenda da pausa.
+//
+// A REGRA JÁ EXISTIA, escrita uma vez: `legendaDoIcone` (ui/pause-icons) lê o `aria-label` do ícone justamente
+// para que "passar o mouse ou focar diga a MESMA verdade que um leitor de tela anunciaria". Ela valia para os
+// dez ícones e não para o resto dos menus. Aqui ela vira uma função, e as três chamadas passam a ser a mesma.
+//
+// ========================= POR QUE UM MÓDULO-FOLHA =========================
+// Três consumidores em camadas diferentes (`ui/activities-menu`, `ui/menu-nav`, `ui/pause-icons`), e
+// `ui/menu-nav` já importa `ui/pause-icons` — pôr a regra num deles fecharia ciclo ou obrigaria alguém a
+// importar de quem não devia. Mesma lição de `core/anel`, e ela é recente: ciclo em ESM não estoura na hora,
+// estoura no boot em TDZ, uma vez, em produção.
+//
+// Zero dependências, zero I/O, nenhum `document` global: recebe o elemento e devolve texto.
+/** Espaço em branco de markup vira UM espaço; pontas somem. */
+const enxuto = (s) => (s || '').replace(/\s+/g, ' ').trim();
+/**
+ * O nome do controle: `aria-label` quando existe, o texto visível quando não.
+ *
+ * A ORDEM É A DECISÃO, e ela não é arbitrária: `aria-label` é o que a plataforma de acessibilidade JÁ vai
+ * anunciar. Narrar outra coisa não acrescenta informação — cria uma segunda versão do mesmo item, e quem
+ * escuta as duas não tem como saber qual é a verdadeira.
+ *
+ * O texto visível entra quando não há rótulo declarado, que é o caso da maioria dos botões: ali as duas
+ * fontes já coincidem por construção.
+ */
+export function rotuloAcessivel(el) {
+    if (!el)
+        return '';
+    return enxuto(el.getAttribute('aria-label')) || enxuto(el.textContent);
+}

package/dist-pkg/core/run-state.d.ts

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { GateTile } from './state.js';
+import type { Player } from './entity.js';
+/**
+ * OS EXTRAS DO NÍVEL — o que o mapa monta a cada rodada e ninguém persiste.
+ *
+ * `P` é o tipo do power-up, e ele vem de quem cria a instância. Ver a nota do genérico no cabeçalho.
+ */
+export interface ExtrasDoNivel<P> {
+    /** Os power-ups espalhados pelo nível. `readonly`: quem lê não reordena. */
+    powerups: readonly P[];
+    /** Os tiles do portão, como chaves `"tx,ty"` — `core/collision` só pergunta `.has()`. */
+    gateTiles: ReadonlySet<string>;
+    /** A lista de tiles do portão, ou `null` quando o nível não tem portão. */
+    gate: readonly GateTile[] | null;
+    /** Portão aberto? FECHADO significa que os tiles acima são sólidos. */
+    gateOpen: boolean;
+}
+/**
+ * O estado de RODADA. Hoje são os extras do nível mais o `wcSolid`; os outros campos chegam nos próximos
+ * passos da Fase B.
+ *
+ * O `wcSolid` fica FORA do `ExtrasDoNivel` porque ele não nasce com os outros quatro: a geometria de
+ * cadeirante é recalculada por conta própria quando o modo liga ou desliga, e tem setter só dela. Juntá-los
+ * num objeto só faria a assinatura mentir sobre quando cada um muda.
+ */
+export interface RunState<P> extends ExtrasDoNivel<P> {
+    /** Sólidos que só existem no modo cadeirante — rampas e plataformas, como chaves `"x,y"`. */
+    wcSolid: ReadonlySet<string>;
+    /**
+     * OS JOGADORES (1..4). Sem setter, e isso é declaração, não esquecimento: o array NUNCA é reatribuído —
+     * ele é mutado no lugar (`push`, `splice`, `length`, `players[i]`), e quem faz isso é `game/session`, que
+     * é o dono da entrada e da saída de jogador. Um setter aqui daria a impressão de que trocar a lista
+     * inteira é uma operação prevista, e ela não é: as referências que os módulos guardam sobreviveriam à
+     * troca apontando para a lista velha.
+     *
+     * `Player[]` é a visão da ENGINE. Cada jogo acrescenta campos (o `GamePlayer` daqui tem `quiz`), e os
+     * consumidores que precisam deles estreitam por conta própria — a dívida de conversões que isso gera é
+     * anterior a este arquivo e não muda com a mudança de endereço.
+     */
+    players: Player[];
+    /**
+     * QUANTOS jogadores/telas (1..4). Não persistido — a partida seguinte começa com um de novo, que é o
+     * comportamento que uma sala de aula quer.
+     */
+    numPlayers: number;
+    /** A rodada acabou (vitória). Trava a entrada e deixa o cenário simulando por trás do aviso. */
+    ended: boolean;
+    /** Semente da decoração do cenário. Sorteada a cada fase DE PROPÓSITO — é o que faz duas partidas da
+     *  mesma fase não terem a mesma grama. */
+    decorSeed: number;
+    /** Fração das superfícies com grama: 1 = todas, 0.6 = 60% (a base das estações que virão). */
+    grassDensity: number;
+    /** QUAL jogador os painéis de acessibilidade visual estão editando. Não é preferência — é qual aba está
+     *  aberta —, e por isso não se persiste: guardá-la faria a criança reabrir o jogo já editando o jogador 2. */
+    selVizPlayer: number;
+    /**
+     * QUEM abriu o menu de pausa, e portanto o ESCOPO de tudo o que se faz dentro dele.
+     *
+     * Importa mais do que parece: em telas separadas, este índice é o que faz o menu do jogador 2 editar as
+     * configurações DELE. Errar aqui não dá erro — dá a criança certa mexendo nos ajustes da criança errada,
+     * em silêncio.
+     */
+    pauseActor: number;
+    /**
+     * Grava os quatro extras JUNTOS, que é como eles nascem.
+     *
+     * Um setter só, e não quatro, porque eles são um resultado só: `game/level-geometry.computeExtras()`
+     * devolve os quatro de uma vez, e gravá-los separadamente abriria uma janela em que o portão de um nível
+     * convive com os tiles de outro.
+     */
+    setLevelExtras(x: ExtrasDoNivel<P>): void;
+    /** Abre ou fecha o portão. É o único dos cinco que muda DURANTE a rodada. */
+    setGateOpen(v: boolean): void;
+    /** Troca os sólidos de cadeirante (recalculados quando a geometria do nível muda). */
+    setWcSolid(s: ReadonlySet<string>): void;
+    setEnded(v: boolean): void;
+    setDecorSeed(s: number): void;
+    /**
+     * ⚠️ O CLAMP MORA AQUI, e é a razão de este setter existir.
+     *
+     * `grassDensity` é uma FRAÇÃO, e antes de `core/state` a proteção vivia no `window.__incl` — ou seja, só
+     * quem entrasse por ali era protegido. Qualquer outro caminho podia escrever 5 ou -1 e o cenário nascia
+     * errado sem nada reclamar. Um valor com faixa válida que depende de quem escreve é um valor sem faixa.
+     */
+    setGrassDensity(v: number): void;
+    setSelVizPlayer(i: number): void;
+    setPauseActor(i: number): void;
+    /** Troca o número de jogadores e AVISA (ver `OpcoesDaRodada.aoTrocarJogadores`). */
+    setNumPlayers(n: number): void;
+}
+/**
+ * O que a rodada precisa saber do mundo lá fora. Hoje é uma coisa só, e ela existe por um motivo concreto.
+ *
+ * `core/state.setNumPlayersValue` emitia `numPlayers` no barramento. Mover o campo para cá e simplesmente
+ * PARAR de emitir removeria em silêncio uma capacidade que a Fase C acabou de formalizar — e removê-la sem
+ * ninguém notar (o barramento ainda não tem assinante) é exatamente o tipo de perda que este repositório
+ * escreve ADR para não repetir.
+ *
+ * Então o aviso entra por INJEÇÃO, como o cabeçalho deste arquivo prometeu, e é OPCIONAL: uma rodada sem
+ * barramento funciona igual. Avisos são para painéis, e um painel ausente não é erro.
+ */
+export interface OpcoesDaRodada {
+    /** Chamado depois de `setNumPlayers`. Na raiz de composição é `(n) => emit('numPlayers', n)`. */
+    aoTrocarJogadores?: (n: number) => void;
+}
+/**
+ * Cria uma rodada. Sem I/O, sem estado de módulo, sem `emit` — quem quiser avisar alguém avisa por fora.
+ *
+ * ⚠️ OS EVENTOS FICARAM DE FORA DE PROPÓSITO. `core/state` emitia `gateOpen` e `wcSolid`, e o barramento
+ * tinha ZERO assinantes (medido: 25 nomes de evento, 26 `emit()`, nenhum `on()`). Emitir para ninguém é
+ * cerimônia, e mantê-la aqui obrigaria a fábrica a depender do barramento — justo o que a Fase C vai
+ * refazer. Quando existir o primeiro assinante, ele entra por injeção, com o barramento já tipado.
+ */
+export declare function createRunState<P>(opcoes?: OpcoesDaRodada): RunState<P>;

package/dist-pkg/core/run-state.js

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Cria uma rodada. Sem I/O, sem estado de módulo, sem `emit` — quem quiser avisar alguém avisa por fora.
+ *
+ * ⚠️ OS EVENTOS FICARAM DE FORA DE PROPÓSITO. `core/state` emitia `gateOpen` e `wcSolid`, e o barramento
+ * tinha ZERO assinantes (medido: 25 nomes de evento, 26 `emit()`, nenhum `on()`). Emitir para ninguém é
+ * cerimônia, e mantê-la aqui obrigaria a fábrica a depender do barramento — justo o que a Fase C vai
+ * refazer. Quando existir o primeiro assinante, ele entra por injeção, com o barramento já tipado.
+ */
+export function createRunState(opcoes = {}) {
+    const r = {
+        powerups: [],
+        gateTiles: new Set(),
+        gate: null,
+        gateOpen: true,
+        wcSolid: new Set(),
+        players: [],
+        numPlayers: 1,
+        setLevelExtras(x) {
+            r.powerups = x.powerups;
+            r.gateTiles = x.gateTiles;
+            r.gate = x.gate;
+            r.gateOpen = x.gateOpen;
+        },
+        setGateOpen(v) { r.gateOpen = v; },
+        setWcSolid(s) { r.wcSolid = s; },
+        ended: false,
+        decorSeed: 0,
+        grassDensity: 1,
+        selVizPlayer: 0,
+        pauseActor: 0,
+        setEnded(v) { r.ended = !!v; },
+        setDecorSeed(s) { r.decorSeed = s >>> 0; },
+        setGrassDensity(v) { r.grassDensity = Math.max(0, Math.min(1, +v || 0)); },
+        setSelVizPlayer(i) { r.selVizPlayer = i; },
+        setPauseActor(i) { r.pauseActor = i; },
+        setNumPlayers(n) { r.numPlayers = n; opcoes.aoTrocarJogadores?.(n); },
+    };
+    return r;
+}

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

@@ -0,0 +1,68 @@
+// 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`.
+ */
+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). */
+    enter?(): void;
+    /** Chamado ao SAIR (pop, ou ao ser coberto por um push). */
+    exit?(): void;
+    /** Tempo. Só o topo recebe. */
+    update?(dt: number): void;
+    /** Desenho. Todas recebem, de baixo para cima. */
+    draw?(): void;
+    /** Entrada. Só o topo recebe. Devolva `true` se consumiu — `false`/nada deixa a tecla seguir. */
+    input?(intent: string): boolean | void;
+}
+export interface SceneStack {
+    /** Empilha `s` no topo. A anterior recebe `exit()` mas CONTINUA na pilha (e continua sendo desenhada). */
+    push(s: Scene): void;
+    /** Desempilha o topo e devolve-o (ou `null` se vazia). Quem reaparecer recebe `enter()`. */
+    pop(): Scene | null;
+    /** Troca o topo — `pop` seguido de `push`, numa chamada, porque é o que "ir para outra tela" quer dizer. */
+    replace(s: Scene): void;
+    /** A cena do topo, ou `null`. */
+    top(): Scene | null;
+    /** Os nomes, da base para o topo. Cópia: quem lê não muta a pilha por acidente. */
+    nomes(): string[];
+    update(dt: number): void;
+    draw(): void;
+    /** Devolve `true` se a cena do topo consumiu a intenção. */
+    input(intent: string): boolean;
+}
+/**
+ * Cria uma pilha vazia.
+ *
+ * ⚠️ `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.
+ */
+export declare function criarPilha(): SceneStack;
+/**
+ * O QUE A CASCA PRECISA SABER DA CENA — três booleanos, e nenhum nome de fase.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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;
+}