@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/core/collision.js

@@ -1,62 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-// core/collision.ts — consultas de colisão da GRADE do mundo (determinístico). Extraído do game.js (Estágio 4).
-// Design testável: o módulo NÃO guarda cópias do estado mutável — recebe CLOSURES em initCollision() que leem o
-// estado VIVO do game.js (wheelchair/modoCego/caneBlockDiv/wcSolid/gateTiles/gateOpen). Assim a colisão sempre
-// enxerga o valor atual (sem risco de dessincronização) e os testes passam um ctx falso → funções 100% puras.
-// TILE/TILE_TYPES são constantes (import direto). Consumido pela física (resolveX/resolveY/stepPlayer) no game.js.
-import { TILE, TILE_TYPES, ehPerigo, ehTrampolim } from './constants.js';
-// (`TileType` era declarado AQUI, privado, e era por isso que a tabela semântica não era usável de fora.
-//  Mudou de casa para `core/constants`, junto da tabela que ele descreve.)
-const TYPES = TILE_TYPES;
-// closures no-op até initCollision() (evita null-check no caminho quente da física).
-let _world = [], _W = 0, _H = 0;
-let _isWheelchair = () => false;
-let _isModoCego = () => false;
-let _caneDiv = () => 1;
-let _wcSolid = () => new Set();
-let _gateTiles = () => new Set();
-let _gateOpen = () => true;
-// Liga a colisão ao mundo + estado vivo. Chamado UMA vez no boot do game.js (após WORLD pronto). Idempotente.
-export function initCollision(ctx) {
-    _world = ctx.world;
-    _W = ctx.W;
-    _H = ctx.H;
-    _isWheelchair = ctx.isWheelchair;
-    _isModoCego = ctx.isModoCego;
-    _caneDiv = ctx.caneDiv;
-    _wcSolid = ctx.wcSolid;
-    _gateTiles = ctx.gateTiles;
-    _gateOpen = ctx.gateOpen;
-}
-// distância (px) entre batidas de bengala = TILE / divisor.
-export const caneBlockPx = () => TILE / _caneDiv();
-// Um TIPO de tile é sólido? Cadeirante: PERIGO e TRAMPOLIM viram chão. Modo cego: o PERIGO vira chão.
-// Pelas perguntas e não pelos números 9 e 5: a regra é sobre o que o tile É, e assim ela continua verdadeira
-// num mapa com outra numeração — que é exatamente o que um segundo jogo tem.
-export const isSolidType = (t) => ((_isWheelchair() && (ehPerigo(t) || ehTrampolim(t))) || (_isModoCego() && ehPerigo(t))) ? true : !!TYPES[t]?.solid;
-// Tile na posição (fora do mundo = pedra(2), parede natural). Coordenadas em TILES.
-export const tileAt = (tx, ty) => (tx < 0 || tx >= _W || ty < 0 || ty >= _H) ? 2 : _world[ty][tx];
-// Sólido "de pisar" (inclui sólidos só-cadeirante). isSolidType já cobre lava/trampolim no modo cadeira.
-export const solidTile = (x, y) => {
-    const t = tileAt(x, y);
-    return (_isWheelchair() && _wcSolid().has(x + ',' + y)) || isSolidType(t);
-};
-// Sólido "de barrar" (inclui portão fechado + sólidos só-cadeirante). Usado pela física.
-export const solidAt = (tx, ty) => (!_gateOpen() && _gateTiles().has(tx + ',' + ty)) || (_isWheelchair() && _wcSolid().has(tx + ',' + ty)) || isSolidType(tileAt(tx, ty));
-// Topo caminhável: sólido com ar logo acima (é uma superfície onde se anda).
-export const surfTop = (x, y) => solidTile(x, y) && !solidTile(x, y - 1);
-// Cadeirante: (col,row) é o "degrau" que uma rampa de 1 tile cobre? (superfície com vizinho-diagonal 1 acima)
-export const isWcRampRiser = (col, row) => surfTop(col, row) && (surfTop(col - 1, row + 1) || surfTop(col + 1, row + 1));
-// Altura (px) da diagonal 45° de uma rampa de 1 tile no x=cx do mundo; null se não há rampa por perto de py.
-export function rampSurfaceY(cx, py) {
-    const tcx = Math.floor(cx / TILE), fx = cx - tcx * TILE, ty = Math.floor(py / TILE);
-    for (let y = ty - 1; y <= ty + 1; y++) {
-        if (y < 1 || !surfTop(tcx, y))
-            continue;
-        if (surfTop(tcx + 1, y - 1))
-            return y * TILE - fx; // degrau sobe p/ direita: y*TILE → (y-1)*TILE
-        if (surfTop(tcx - 1, y - 1))
-            return (y - 1) * TILE + fx; // degrau sobe p/ esquerda: (y-1)*TILE → y*TILE
-    }
-    return null;
-}

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

@@ -1,63 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-export declare const Z: {
-    readonly SKY: 1000;
-    readonly SKY_ANIM: 2000;
-    readonly PARALLAX_4: 3000;
-    readonly PARALLAX_3: 4000;
-    readonly PARALLAX_2: 5000;
-    readonly PARALLAX_1: 6000;
-    readonly BG_DECOR: 7000;
-    readonly TILES: 8000;
-    readonly SCENERY_INTERACT: 9000;
-    readonly VFX_BACK: 10000;
-    readonly FLORA_BACK: 11000;
-    readonly FAUNA_BACK: 12000;
-    readonly NPC: 13000;
-    readonly ITEMS: 14000;
-    readonly PLAYER: 15000;
-    readonly VFX_FRONT: 16000;
-    readonly VEHICLES: 17000;
-    readonly FLORA_FRONT: 18000;
-    readonly FAUNA_FRONT: 19000;
-    readonly FOREGROUND: 20000;
-    readonly WEATHER: 21000;
-    readonly DARK_WORLD: 22000;
-    readonly WORLD_A11Y: 23000;
-    readonly HUD: 24000;
-    readonly TOUCH_CONTROLS: 25000;
-    readonly CAPTIONS: 26000;
-    readonly DIALOGUE: 27000;
-    readonly GAME_MSG: 28000;
-    readonly MODAL_SCRIM: 29000;
-    readonly MENU: 30000;
-    readonly MENU_MAX: 39999;
-    readonly TRANSITION: 40000;
-    /**
-     * ⚠️ A SAÍDA DE EMERGÊNCIA, E ELA FICA ACIMA DA TRANSIÇÃO (decisão do Dev, 2026-09-07).
-     *
-     * Este comentário dizia que o *skip-link* mora em `CAPTIONS` (26000) — e isso deixava-o ABAIXO de
-     * `MENU` (30000). Um «pular para o conteúdo» que um modal cobre não é alcançável, o que é a WCAG 2.4.1 ao
-     * contrário: o mecanismo que existe para atravessar blocos repetidos passa a ser mais um bloco.
-     * O gate do `z-order-css` já registava o defeito com todas as letras — «o `Z` ERRA, não o CSS» —, e ficou
-     * assim durante semanas porque nada o obrigava a mudar.
-     *
-     * ⚠️ E É ACIMA DA `TRANSITION`, não entre o menu e ela. O Dev pediu 41000 e o motivo é o que sobra depois
-     * de tudo o resto falhar: a saída não pode ficar atrás de nada que a pessoa não controla, e um fade de
-     * troca de fase é precisamente isso. O custo — o link aparecer por cima de uma animação — é nulo na
-     * prática, porque ele só é visível AO FOCO (`top:-60px` até `:focus`), e porque durante a transição já não
-     * se tabula: o foco sai da tela antiga e só reaparece na seguinte (ver a regra de foco no ADR).
-     *
-     * Só o aviso de laço morto (ADR-0054) e o painel de desenvolvimento ficam acima dela.
-     */
-    readonly SKIP_LINK: 41000;
-    /**
-     * O LAÇO MORREU (ADR-0054). Acima do `TRANSITION` de propósito: quando o quadro lança, o que estiver na
-     * tela — menu aberto, fade a meio, mensagem de fase — está congelado e deixou de importar. O aviso tem de
-     * ser visto por cima de tudo isso, e só o painel de desenvolvimento fica acima dele.
-     */
-    readonly LOOP_CRASH: 45000;
-    readonly DEBUG: 90000;
-};
-export type LayerName = keyof typeof Z;
-export declare const POST_FX_ORDER: readonly ["CRT_VIGNETTE", "EMPATHY_SIM", "A11Y_CORRECTION", "FLASH_LIMIT"];
-export type PostFx = typeof POST_FX_ORDER[number];

package/dist-pkg/core/layers.js

@@ -1,95 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-// core/layers — ORDEM-Z CANÔNICA (fonte única de verdade). Cada camada tem um Z NOMEADO; ninguém mais faz
-// addChildAt(getChildIndex(...)) nem "re-adiciona ao topo" — a inserção passa a ser pelo Z (fim do acoplamento).
-// Duas escalas: MUNDO (por viewport — PIXI zIndex dentro da câmera, com sortableChildren) e OVERLAY (global, tela —
-// vira CSS z-index no DOM, pois menu/HUD/legenda são DOM). **Passo 1000** = folga generosa: 999 slots livres entre
-// camadas nomeadas (e sub-slots dentro de cada uma) p/ inserir futuras SEM renumerar. Elementos concretos entram por
-// `Z.BANDA + offset` pequeno (ex.: cane/cadeira = PLAYER+10/+20) — ver docs/5-Refactoring/plano-religacao-z-camadas.md.
-//
-// NATUREZA (fauna/flora) STRADDLE o jogador: há um par BACK (atrás) e FRONT (à frente) p/ cada, deixando bichos/plantas
-// aparecerem dos dois lados do player (imersão — pedido do José). PIXI sortableChildren é tudo-ou-nada por container →
-// o mundo inteiro migra numa rodada só (todos os filhos ganham zIndex de uma vez, reproduzindo a ordem atual = no-op).
-//
-// PÓS-PROCESSO ≠ camada Z: CRT/vinheta e os filtros de a11y (alto-contraste, correção de daltonismo, simulação de
-// deficiência) são uma CADEIA de passes sobre o frame JÁ COMPOSTO (POST_FX_ORDER), não itens da display-list — e cobrem
-// TUDO, inclusive o menu. A11Y_CORRECTION é SEMPRE o último passe; modos de a11y SUPRIMEM o CRT/efeitos decorativos; o
-// overlay é palette-aware (troca p/ CB-safe). Ver ADR-0020 + ADR-0011.
-export const Z = {
-    // ===== MUNDO (por viewport; PIXI zIndex dentro da câmera) =====
-    SKY: 1000, // gradiente de céu (base)
-    SKY_ANIM: 2000, // animações do céu atrás do parallax (estrelas)
-    PARALLAX_4: 3000, // paralaxe mais distante. Nuvens de céu podem entrar em PARALLAX_*+offset (profundidades)
-    PARALLAX_3: 4000,
-    PARALLAX_2: 5000,
-    PARALLAX_1: 6000, // fundo próximo do jogo
-    BG_DECOR: 7000, // deco ATRÁS dos tiles: árvores, água/corais/algas, ruínas, deco de cidade, nuvens de tela
-    TILES: 8000, // tileset / plataforma (o nível)
-    SCENERY_INTERACT: 9000, // cenário interativo: porta, alavanca, interruptor, manivela, corda, portão, rampa, elevador
-    VFX_BACK: 10000, // efeitos ATRÁS dos atores: poeira de pé, god-rays, tracinhos de lava, sombras
-    FLORA_BACK: 11000, // plantas ATRÁS do player (grama, flores, arbustos de fundo)
-    FAUNA_BACK: 12000, // criaturas ATRÁS do player (bichos da cidade, animais de fundo)
-    NPC: 13000, // personagens interativos (não-jogador)
-    ITEMS: 14000, // coletáveis (moedas, poderes, chave) — ATRÁS do player (barril DK / Yoshi / chave SMW)
-    PLAYER: 15000, // jogador(es). Aparatos presos (bengala/cadeira) = PLAYER+offset
-    VFX_FRONT: 16000, // efeitos NA FRENTE do player: partículas/juice, explosão, faísca, fogos, confete
-    VEHICLES: 17000, // veículos na frente (carros/trânsito da cidade)
-    FLORA_FRONT: 18000, // plantas NA FRENTE do player (folhagem que tampa o ator — imersão)
-    FAUNA_FRONT: 19000, // criaturas NA FRENTE do player (borboletas/vagalumes/minhocas v3 passando à frente)
-    FOREGROUND: 20000, // primeiro-plano oclusivo genérico (props que tampam o ator)
-    WEATHER: 21000, // clima na frente de tudo do mundo (névoa, chuva, clarão)
-    DARK_WORLD: 22000, // escurecimento do mundo (modo cego / empatia baixa-visão)
-    WORLD_A11Y: 23000, // pistas visuais de a11y no mundo (sonar, guarda de beirada, hitbox fácil, realce)
-    // ===== OVERLAY (global, tela; = CSS z-index no DOM / topo da stage PIXI) =====
-    HUD: 24000, // placar/moedas/poder/objetivo/minimapa (persistente durante o jogo)
-    TOUCH_CONTROLS: 25000, // gamepad virtual / botões de toque (mobile)
-    CAPTIONS: 26000, // legendas de som (a11y surdez) + skip-link de navegação
-    DIALOGUE: 27000, // fala/diálogo/atividade (quiz)
-    GAME_MSG: 28000, // vitória / game over / pause / faixa de fase
-    MODAL_SCRIM: 29000, // escurecimento do fundo quando abre um modal
-    MENU: 30000, // menus — RANGE reservado 30000–39999 (níveis aninhados: +1000 por nível)
-    MENU_MAX: 39999,
-    TRANSITION: 40000, // fade/wipe de troca de fase (cobre tudo)
-    /**
-     * ⚠️ A SAÍDA DE EMERGÊNCIA, E ELA FICA ACIMA DA TRANSIÇÃO (decisão do Dev, 2026-09-07).
-     *
-     * Este comentário dizia que o *skip-link* mora em `CAPTIONS` (26000) — e isso deixava-o ABAIXO de
-     * `MENU` (30000). Um «pular para o conteúdo» que um modal cobre não é alcançável, o que é a WCAG 2.4.1 ao
-     * contrário: o mecanismo que existe para atravessar blocos repetidos passa a ser mais um bloco.
-     * O gate do `z-order-css` já registava o defeito com todas as letras — «o `Z` ERRA, não o CSS» —, e ficou
-     * assim durante semanas porque nada o obrigava a mudar.
-     *
-     * ⚠️ E É ACIMA DA `TRANSITION`, não entre o menu e ela. O Dev pediu 41000 e o motivo é o que sobra depois
-     * de tudo o resto falhar: a saída não pode ficar atrás de nada que a pessoa não controla, e um fade de
-     * troca de fase é precisamente isso. O custo — o link aparecer por cima de uma animação — é nulo na
-     * prática, porque ele só é visível AO FOCO (`top:-60px` até `:focus`), e porque durante a transição já não
-     * se tabula: o foco sai da tela antiga e só reaparece na seguinte (ver a regra de foco no ADR).
-     *
-     * Só o aviso de laço morto (ADR-0054) e o painel de desenvolvimento ficam acima dela.
-     */
-    SKIP_LINK: 41000,
-    /**
-     * O LAÇO MORREU (ADR-0054). Acima do `TRANSITION` de propósito: quando o quadro lança, o que estiver na
-     * tela — menu aberto, fade a meio, mensagem de fase — está congelado e deixou de importar. O aviso tem de
-     * ser visto por cima de tudo isso, e só o painel de desenvolvimento fica acima dele.
-     */
-    LOOP_CRASH: 45000,
-    DEBUG: 90000, // painel ?debug / FPS / hitboxes (dev; topo absoluto)
-};
-// Cadeia de PÓS-PROCESSO — passes sobre o frame COMPOSTO, do interno p/ o externo. NÃO são camadas Z.
-// Modos de a11y suprimem CRT_VIGNETTE e flashes decorativos (precedência a11y > estética). Ver ADR-0020.
-//
-// DUAS COISAS DIFERENTES NO FIM DA FILA, e confundi-las é o que este comentário existe para impedir:
-//
-//  · A11Y_CORRECTION é o último passe de CORREÇÃO. Ele decide como a imagem SE PARECE, e por isso precisa ver o
-//    composto final, menus inclusive — é essa a razão de ele vir depois do CRT, que senão re-tinge e desfaz a
-//    correção de daltonismo.
-//  · FLASH_LIMIT é o último passe, ponto. Ele decide se a imagem pode FAZER MAL. A WCAG 2.3.1 limita a variação de
-//    luminância no tempo, e o único quadro cuja luminância importa é o que chega ao olho. Um limitador colocado
-//    ANTES da correção limita uma imagem que já não existe, e a correção fica livre para reabrir a oscilação que
-//    ele acabou de fechar — uma matriz de daltonismo redistribui luminância por definição. Segurança é o passe mais
-//    externo porque é a última coisa verdadeira sobre o quadro.
-//
-// O ADR-0020 dizia "A11Y_CORRECTION sempre por último" sem essa distinção; foi emendado em 2026-08-24. FLASH_LIMIT
-// ainda NÃO está implementado — está declarado aqui, e aferido por teste, para que quem o implementar encontre o
-// lugar certo já ocupado em vez de deduzir a ordem errada a partir da redação antiga.
-export const POST_FX_ORDER = ['CRT_VIGNETTE', 'EMPATHY_SIM', 'A11Y_CORRECTION', 'FLASH_LIMIT'];

package/dist-pkg/core/letter-grid.d.ts

@@ -1,55 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-/** As quatro direções que um direcional produz. Nomes em português porque são vocabulário do jogo, não da web. */
-export type Direcao = 'esquerda' | 'direita' | 'cima' | 'baixo';
-/** Onde o cursor está, em coordenadas de grade — o que a tela desenha e o leitor de tela anuncia. */
-export interface Posicao {
-    readonly linha: number;
-    readonly coluna: number;
-}
-export interface GradeDeLetras {
-    /** A grade, como dado: quem desenha lê daqui em vez de recontar. */
-    readonly simbolos: readonly string[];
-    readonly colunas: number;
-    readonly linhas: number;
-    /** Quantas casas o valor aceita. `0` = sem limite (jogos de palavra). */
-    readonly capacidade: number;
-    /** Índice linear do cursor, `0..simbolos.length-1`. */
-    indice(): number;
-    /** A posição do cursor em linha/coluna, base ZERO — quem anuncia soma 1 se quiser falar "linha 1". */
-    posicao(): Posicao;
-    /** O símbolo sob o cursor. */
-    sob(): string;
-    /** Move o cursor uma casa, enrolando em toroide. */
-    mover(dir: Direcao): void;
-    /** Leva o cursor ao símbolo dado. Devolve `false` — e não move — quando ele não está na grade. */
-    irPara(simbolo: string): boolean;
-    /** Acrescenta o símbolo sob o cursor ao valor. Não faz nada quando o valor já está cheio. */
-    digitar(): void;
-    /** Apaga a última casa. Não faz nada quando o valor está vazio. */
-    apagar(): void;
-    /** Esvazia o valor. O cursor NÃO se mexe: quem apagou continua olhando para onde estava. */
-    limpar(): void;
-    /** O que foi digitado até agora. */
-    valor(): string;
-    /** Quantas casas ainda faltam. `null` quando não há capacidade declarada. */
-    faltam(): number | null;
-    /** `true` quando o valor atingiu a capacidade. Sempre `false` sem capacidade declarada. */
-    completo(): boolean;
-}
-export interface OpcoesDaGrade {
-    /** Os símbolos, em ordem de leitura (esquerda→direita, cima→baixo). */
-    simbolos: string;
-    /** Largura da grade. As linhas saem da divisão, e a última pode ficar incompleta. */
-    colunas: number;
-    /** Quantas casas o valor aceita; omitir ou `0` deixa sem limite. */
-    capacidade?: number;
-}
-/**
- * A grade, como instância.
- *
- * `colunas` precisa ser inteiro ≥ 1 e `simbolos` não pode ser vazio: uma grade sem casas não tem cursor, e
- * um cursor sem casa é a origem de todo `undefined` que aparece três telas adiante. As mensagens são
- * SELETORES e não prosa — o gate de i18n de engine proíbe frase em qualquer idioma aqui, e o nome do campo
- * que falhou é mais útil que uma frase de qualquer forma.
- */
-export declare function criarGrade(opcoes: OpcoesDaGrade): GradeDeLetras;

package/dist-pkg/core/letter-grid.js

@@ -1,116 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-// core/letter-grid — ENTRADA DE TEXTO SEM TECLADO, e é essa a coisa que este arquivo é.
-//
-// ========================= POR QUE ISTO EXISTE =========================
-// O ADR-0027 diz o que falta ao motor em uma linha: *"the engine needs a LETTER GRID SELECTOR, not a
-// keyboard"*. Um console não tem teclado, e o alvo desta engine é uma máquina de escola operada por
-// direcional — quando não por UM botão só. Digitar, aqui, é mover um cursor por uma grade e confirmar.
-//
-// O consumidor é o CÓDIGO DA SALA DA PROFESSORA. Não é a senha de progressão da criança: o ADR-0037 a
-// enterrou junto com a ideia de salvar jogo — não existe save, e o Inclusionist não guarda nada sobre uma
-// criança. O que o ADR-0037 diz que sobrevive é o `core/password`, e por outro motivo: *"the teacher's room
-// code is the same engineering problem… it stays because the room screen will need it"*. O modo de falha
-// mudou de forma junto: um código errado que seja ACEITO não carrega o progresso de outra criança — larga
-// esta criança na sala de outra turma, fazendo a atividade de outra professora.
-//
-// O segundo consumidor já está previsto e é o que impede este módulo de nascer como componente de senha: os
-// jogos de palavras do catálogo do `inclusionist-demos` precisam da mesma coisa.
-//
-// ========================= O CORTE (ADR-0041) =========================
-// MECÂNICA aqui, TELA no `ui/`. É a mesma divisão que o `core/password` acabou de usar, e ela existe para
-// preservar a propriedade mais cara que o `core/` tem: ser testável sem navegador. O `core/scenes` foi
-// escrito de propósito sem PIXI e sem DOM por esse motivo, e um módulo que DESENHE dentro do `core/` abre
-// uma porta que a próxima tela atravessa sem discussão.
-//
-// O que NÃO está aqui, e é honesto dizer: a repetição de tecla. Ela é temporização de entrada e mora com o
-// `input/`, junto das bordas de tecla — o ADR-0041 a listou como conteúdo desta metade e ela não é.
-//
-// ========================= A ESCOLHA DE ENROLAMENTO, E O MOTIVO =========================
-// Nas bordas o cursor enrola em TOROIDE: andar para a direita mantém a LINHA, andar para baixo mantém a
-// COLUNA. A alternativa — a da direita na última coluna cair na linha seguinte, como texto — é comum em
-// teclados de console e está errada aqui, e o motivo é o leitor de tela: a leitura anuncia "linha 2,
-// coluna 1", e um movimento horizontal que mude a linha faz o anúncio contradizer a direção que a criança
-// apertou. Movimento previsível vale mais que economia de apertos.
-//
-// SEM I/O NO IMPORT, e sem estado de módulo: `criarGrade()` devolve a instância e quem compõe a possui. É a
-// D13 do `inclusionist-demos`, e é o que permite duas grades na mesma página sem uma pisar na outra.
-/**
- * A grade, como instância.
- *
- * `colunas` precisa ser inteiro ≥ 1 e `simbolos` não pode ser vazio: uma grade sem casas não tem cursor, e
- * um cursor sem casa é a origem de todo `undefined` que aparece três telas adiante. As mensagens são
- * SELETORES e não prosa — o gate de i18n de engine proíbe frase em qualquer idioma aqui, e o nome do campo
- * que falhou é mais útil que uma frase de qualquer forma.
- */
-export function criarGrade(opcoes) {
-    const simbolos = [...opcoes.simbolos];
-    const colunas = opcoes.colunas;
-    if (simbolos.length === 0)
-        throw new Error('simbolos');
-    if (!Number.isInteger(colunas) || colunas < 1)
-        throw new Error('colunas');
-    const linhas = Math.ceil(simbolos.length / colunas);
-    const capacidade = opcoes.capacidade ?? 0;
-    if (!Number.isInteger(capacidade) || capacidade < 0)
-        throw new Error('capacidade');
-    let cursor = 0;
-    let digitado = '';
-    /** Enrolamento de um eixo, escrito uma vez: `((v % n) + n) % n` sobrevive a negativo, que `v % n` não. */
-    const enrolar = (v, n) => ((v % n) + n) % n;
-    /**
-     * A ÚLTIMA LINHA PODE SER INCOMPLETA — 32 símbolos em 8 colunas dão 4 linhas cheias, mas 30 dariam uma
-     * linha com 6. Descer numa coluna que não existe na linha de destino cairia num buraco, e este é o ponto
-     * que decide o que fazer: o cursor pula a linha incompleta naquela coluna e segue descendo. Assim toda
-     * tecla move, sempre, para uma casa que existe — e o leitor de tela nunca anuncia vazio.
-     */
-    function indiceDe(linha, coluna) {
-        for (let i = 0; i < linhas; i++) {
-            const l = enrolar(linha + i, linhas);
-            const idx = l * colunas + coluna;
-            if (idx < simbolos.length)
-                return idx;
-        }
-        return cursor; // inalcançável com colunas ≥ 1: a linha 0 sempre tem a coluna 0
-    }
-    function posicao() {
-        return { linha: Math.floor(cursor / colunas), coluna: cursor % colunas };
-    }
-    function mover(dir) {
-        const { linha, coluna } = posicao();
-        if (dir === 'esquerda' || dir === 'direita') {
-            // Enrola DENTRO da linha, e a linha incompleta enrola no tamanho dela, não no da grade.
-            const inicio = linha * colunas;
-            const largura = Math.min(colunas, simbolos.length - inicio);
-            cursor = inicio + enrolar(coluna + (dir === 'direita' ? 1 : -1), largura);
-            return;
-        }
-        cursor = indiceDe(linha + (dir === 'baixo' ? 1 : -1), coluna);
-    }
-    return {
-        simbolos,
-        colunas,
-        linhas,
-        capacidade,
-        indice: () => cursor,
-        posicao,
-        sob: () => simbolos[cursor],
-        mover,
-        irPara(simbolo) {
-            const i = simbolos.indexOf(simbolo);
-            if (i < 0)
-                return false;
-            cursor = i;
-            return true;
-        },
-        digitar() {
-            if (capacidade > 0 && digitado.length >= capacidade)
-                return;
-            digitado += simbolos[cursor];
-        },
-        apagar() { digitado = digitado.slice(0, -1); },
-        limpar() { digitado = ''; },
-        valor: () => digitado,
-        faltam: () => (capacidade > 0 ? capacidade - digitado.length : null),
-        completo: () => capacidade > 0 && digitado.length >= capacidade,
-    };
-}

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

@@ -1,34 +0,0 @@
-// 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

@@ -1,205 +0,0 @@
-// 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);
-}