@the-inclusionist/engine 6.36.1

package/dist-pkg/core/a11y-sr.js

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// core/a11y-sr.ts — anúncios para LEITOR DE TELA (Estágio 4, Tier 1). srSay = região aria-live "polite" (status);
+// srAlert = região "assertive" (alertas). O padrão limpar→requestAnimationFrame→escrever força o leitor a
+// reanunciar mesmo texto repetido. Também espelha a fala em LIBRAS: como ui/vlibras ainda não foi extraído, o
+// vlibrasSay entra por INJEÇÃO (setVlibrasSay) — no-op até o game.js registrá-lo no boot (evita inverter a ordem
+// do Tier 1). Depende só de ui/dom ($). As regiões #sr-status/#sr-alert vivem no index.html.
+import { $ } from '../ui/dom.js';
+let _vlibrasSay = () => { };
+// Registra a fala em Libras (chamado no boot do game.js, quando vlibrasSay existe). Ver ui/vlibras (futuro).
+export function setVlibrasSay(fn) { _vlibrasSay = fn; }
+// Anúncio "polite" (status): não interrompe o que o leitor está falando.
+export const srSay = (t) => { const el = $('#sr-status'); if (el) {
+    el.textContent = '';
+    requestAnimationFrame(() => { el.textContent = t; });
+} _vlibrasSay(t); };
+// Anúncio "assertive" (alerta): interrompe e fala já (erros/avisos importantes).
+export const srAlert = (t) => { const el = $('#sr-alert'); if (el) {
+    el.textContent = '';
+    requestAnimationFrame(() => { el.textContent = t; });
+} _vlibrasSay(t); };

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

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** As quatorze posições que a engine conhece. Nenhuma delas é uma palavra que uma criança leia. */
+export declare const ACTIONS: readonly ["up", "down", "left", "right", "action1", "action2", "action3", "action4", "leftShoulder", "leftTrigger", "rightShoulder", "rightTrigger", "start", "select"];
+export type Action = (typeof ACTIONS)[number];
+/** As quatro direções, que todo transporte tem de alcançar. */
+export declare const DIRECTIONS: readonly ["up", "down", "left", "right"];
+/**
+ * Os oito verbos, em DUAS metades que se nomeiam por critérios diferentes, e isso é decisão e não descuido:
+ *
+ * · `action1`..`action4` — o losango. NUMERADOS, porque quatro posições em cruz não têm nomes que
+ *   atravessem gêneros: o que uma plataforma chama de pulo, um quiz chama de confirmar.
+ * · `leftShoulder`, `leftTrigger`, `rightShoulder`, `rightTrigger` — NOMEADOS pela anatomia da mão: dois
+ *   dedos por mão, um por cima do outro. ADR-0086.
+ *
+ * ⚠️ NÃO HÁ HIERARQUIA ENTRE ELES no contrato. A ordem é a de apresentação — no assistente do gamepad, na
+ * tela de remapeamento — e não uma escala de importância: um jogo pode usar `rightShoulder` e nenhuma outra.
+ */
+export declare const VERBS: readonly ["action1", "action2", "action3", "action4", "leftShoulder", "leftTrigger", "rightShoulder", "rightTrigger"];
+/**
+ * As duas de SISTEMA. Não pertencem ao mundo do jogo: `start` pausa e retoma, `select` abre o que é da sessão.
+ *
+ * ⚠️ E É POR ISSO QUE A ENGINE PODE NOMEÁ-LAS e não pode nomear as outras. O ADR-0074 proíbe um nome abstrato
+ * chegar a uma pessoa porque `action1` não diz nada a ninguém — mas «start» e «select» são o que está escrito
+ * no próprio controle desde 1983, e a criança lê a legenda antes de ler a nossa.
+ */
+export declare const SYSTEM: readonly ["start", "select"];
+/** O que a criança lê e ouve para uma posição: o nome, e a frase que o explica quando ela pergunta. */
+export interface ActionWord {
+    /** «Pular», «Confirmar», «Colocar peça». NUNCA `action2` — nome abstrato que chega a uma pessoa é defeito. */
+    readonly label: string;
+    /**
+     * A versão CURTA, para onde não cabe a longa. Cai em `label` quando ausente.
+     *
+     * ⚠️ NÃO É PREFERÊNCIA DE ESTILO: É LARGURA MEDIDA. A legenda do título põe a palavra debaixo de um glifo,
+     * numa fileira de quatro, e `ui/shell` já trazia a nota de que ali não cabe o «Correr / interagir» que a
+     * lista de remapeamento usa — por isso o dicionário tinha DUAS famílias de chaves para as mesmas quatro
+     * ações, `act.*` e `legend.*`. A distinção é do jogo, não da engine, então atravessa com as palavras.
+     *
+     * ⚠️ E O RECUO PARA `label` DEGRADA VISUALMENTE, não funcionalmente: um jogo que não declare `short` vê a
+     * palavra longa espremida, e não uma legenda vazia. Escolhido assim porque uma legenda muda é pior do que
+     * uma legenda apertada — a primeira some para quem usa leitor de tela, a segunda não.
+     */
+    readonly short?: string;
+    /** Opcional, para a tela de remapeamento: o que este botão faz, numa frase. */
+    readonly hint?: string;
+}
+/**
+ * O vocabulário de UM jogo: para cada posição que ele usa, a palavra dele.
+ *
+ * ⚠️ PARCIAL DE PROPÓSITO. Um jogo declara SÓ as posições que usa. Exigir as quatorze obrigaria um quiz a
+ * inventar nome para um gatilho que ele não tem, e um nome inventado acaba numa tela de remapeamento à
+ * frente de uma criança.
+ */
+export type ActionPreset = Partial<Readonly<Record<Action, ActionWord>>>;
+/** As posições que este preset nomeia, na ordem canônica de `ACTIONS`. */
+export declare function presetActions(p: ActionPreset): Action[];
+/**
+ * A pergunta que a engine faz ao jogo quando precisa MOSTRAR uma ação: «como é que isto se chama?».
+ *
+ * É a fronteira do corte em forma de função. A engine sabe que existe uma posição; só o jogo sabe a palavra,
+ * e é esta função que atravessa.
+ */
+export type ActionLabeller = (a: Action) => string;
+/**
+ * Constrói o tradutor a partir de um preset.
+ *
+ * ⚠️ E O QUE ELE FAZ COM UMA AÇÃO SEM NOME É A DECISÃO INTEIRA. Devolver `action7` seria pôr um nome abstrato
+ * à frente de uma criança, que o ADR-0074 chama de defeito em tantas palavras. Devolver vazio calaria o leitor
+ * de tela, que é o defeito silencioso que `speakableProblems` já persegue noutro sítio.
+ *
+ * Devolve `null`, e quem chama decide: o assistente de controle NÃO PERGUNTA por uma ação que o jogo não
+ * nomeia — se o jogo não a usa, não há o que mapear. Uma ausência vira menos um passo, nunca um passo mudo.
+ */
+export declare function labellerFrom(p: ActionPreset): (a: Action) => string | null;
+/**
+ * O mesmo, na versão CURTA — para a legenda do título, onde a palavra vive debaixo de um glifo.
+ *
+ * ⚠️ RECUA PARA `label`, e o recuo é a decisão: uma legenda apertada é pior que uma bonita e melhor que uma
+ * vazia. Vazia sumiria também para quem usa leitor de tela, que é o custo que não se aceita aqui.
+ */
+export declare function shortLabellerFrom(p: ActionPreset): (a: Action) => string | null;
+/**
+ * Um preset é bem-formado? Devolve os problemas — VAZIA quer dizer conforme.
+ *
+ * ⚠️ O QUE ELE APANHA É O RÓTULO VAZIO, e é o mesmo defeito silencioso de `speakableProblems` em
+ * `core/contract`: um `label` em branco não quebra nada, não avisa ninguém, e deixa a tela de remapeamento
+ * com uma linha muda — que para quem usa leitor de tela é um botão que existe e não tem nome.
+ */
+export declare function presetProblems(p: ActionPreset | null | undefined): string[];
+/** É uma ação conhecida? Guarda de fronteira para dado que veio de fora (mapa salvo, remapeamento). */
+export declare function isAction(x: unknown): x is Action;
+/**
+ * Uma declaração de ações usadas por um jogo é bem-formada? Devolve os problemas — VAZIA quer dizer conforme.
+ *
+ * ⚠️ EXIGIR AS QUATRO DIREÇÕES SERIA ERRADO, e a tentação é grande: um quiz navega por `up`/`down` e não usa
+ * `left`/`right`; um jogo de um botão não usa nenhuma. Quem decide o conjunto é o jogo. O que esta função
+ * confere é que o conjunto é NOMEÁVEL e não está vazio — um jogo sem ação nenhuma não tem como ser jogado, e
+ * hoje isso falharia em silêncio no primeiro transporte que tentasse ligar-se a nada.
+ */
+export declare function actionSetProblems(used: readonly string[] | null | undefined): string[];

package/dist-pkg/core/actions.js

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// core/actions — AS QUATORZE AÇÕES ABSTRATAS. A fonte única do vocabulário de entrada da engine.
+//
+// ========================= O QUE ISTO É =========================
+// O ADR-0074 decidiu que a engine conhece POSIÇÕES, não verbos, e que o JOGO fornece as palavras. Este módulo
+// é a lista dessas posições e nada mais: zero dependências, zero I/O, importável dos dois lados da fronteira.
+//
+// ⚠️ ATÉ AQUI A LISTA SÓ EXISTIA NUM REGISTRO. O código continua com os oito nomes de plataforma
+// (`jump`, `run`, `swap`, `especial`) espalhados por `input/gamepad`, `input/edges`, `input/devices` e
+// `input/keydown` — a migração é a issue #103 e não aconteceu. Este módulo é o alvo dela: um sítio para onde
+// os transportes passam a apontar, escrito antes para que a migração tenha destino em vez de o inventar.
+//
+// ========================= POR QUE QUATORZE E NÃO NOVE =========================
+// O ADR-0074 registrou nove e escreveu, entre as suas próprias desvantagens, que «nove é um TETO que um gênero
+// pode querer exceder, e o registro tem de dizer o que acontece». O Dev excedeu-o em 2026-09-06, pedindo mais
+// cinco para jogos mais elaborados. O ADR-0085 é o que acontece.
+//
+// ⚠️ E OS QUATRO NOVOS CHAMAM-SE `leftShoulder`, `leftTrigger`, `rightShoulder`, `rightTrigger` — NÃO
+// `action5`..`action8`. Eu argumentei pelos números e o Dev decidiu contra, em 2026-09-06, com uma razão que
+// o ADR-0086 registra: `action7` é ilegível no ponto onde alguém programa, e um vocabulário que ninguém
+// consegue ler em voz alta não é abstração, é cifra. O ADR-0085 dizia o contrário; foi supersedido, não
+// emendado.
+//
+// ⚠️ E A OBJEÇÃO CONTINUA ESCRITA, porque ela não some por a decisão ter sido outra: ombro e gatilho são
+// FORMA DE GAMEPAD. Num teclado, `leftTrigger` é a tecla Y; num toque, um slot; num reconhecedor de fala, uma
+// palavra. O ADR-0086 responde que a forma é ANATÔMICA antes de ser de gamepad — dois dedos por mão, um por
+// cima do outro — e que isso atravessa transportes melhor do que um número atravessa. Quem discordar leia os
+// dois registros, que é para isso que eles existem.
+//
+// `start` e `select` mantêm nome pelo critério que já valia para `start`: são FUNÇÃO, não posição — o que é
+// do sistema e não do mundo do jogo.
+/** As quatorze posições que a engine conhece. Nenhuma delas é uma palavra que uma criança leia. */
+export const ACTIONS = [
+    'up', 'down', 'left', 'right',
+    'action1', 'action2', 'action3', 'action4',
+    'leftShoulder', 'leftTrigger', 'rightShoulder', 'rightTrigger',
+    'start', 'select',
+];
+/** As quatro direções, que todo transporte tem de alcançar. */
+export const DIRECTIONS = ['up', 'down', 'left', 'right'];
+/**
+ * Os oito verbos, em DUAS metades que se nomeiam por critérios diferentes, e isso é decisão e não descuido:
+ *
+ * · `action1`..`action4` — o losango. NUMERADOS, porque quatro posições em cruz não têm nomes que
+ *   atravessem gêneros: o que uma plataforma chama de pulo, um quiz chama de confirmar.
+ * · `leftShoulder`, `leftTrigger`, `rightShoulder`, `rightTrigger` — NOMEADOS pela anatomia da mão: dois
+ *   dedos por mão, um por cima do outro. ADR-0086.
+ *
+ * ⚠️ NÃO HÁ HIERARQUIA ENTRE ELES no contrato. A ordem é a de apresentação — no assistente do gamepad, na
+ * tela de remapeamento — e não uma escala de importância: um jogo pode usar `rightShoulder` e nenhuma outra.
+ */
+export const VERBS = [
+    'action1', 'action2', 'action3', 'action4',
+    'leftShoulder', 'leftTrigger', 'rightShoulder', 'rightTrigger',
+];
+/**
+ * As duas de SISTEMA. Não pertencem ao mundo do jogo: `start` pausa e retoma, `select` abre o que é da sessão.
+ *
+ * ⚠️ E É POR ISSO QUE A ENGINE PODE NOMEÁ-LAS e não pode nomear as outras. O ADR-0074 proíbe um nome abstrato
+ * chegar a uma pessoa porque `action1` não diz nada a ninguém — mas «start» e «select» são o que está escrito
+ * no próprio controle desde 1983, e a criança lê a legenda antes de ler a nossa.
+ */
+export const SYSTEM = ['start', 'select'];
+/** As posições que este preset nomeia, na ordem canônica de `ACTIONS`. */
+export function presetActions(p) {
+    return ACTIONS.filter((a) => p[a] !== undefined);
+}
+/**
+ * Constrói o tradutor a partir de um preset.
+ *
+ * ⚠️ E O QUE ELE FAZ COM UMA AÇÃO SEM NOME É A DECISÃO INTEIRA. Devolver `action7` seria pôr um nome abstrato
+ * à frente de uma criança, que o ADR-0074 chama de defeito em tantas palavras. Devolver vazio calaria o leitor
+ * de tela, que é o defeito silencioso que `speakableProblems` já persegue noutro sítio.
+ *
+ * Devolve `null`, e quem chama decide: o assistente de controle NÃO PERGUNTA por uma ação que o jogo não
+ * nomeia — se o jogo não a usa, não há o que mapear. Uma ausência vira menos um passo, nunca um passo mudo.
+ */
+export function labellerFrom(p) {
+    return (a) => {
+        const w = p[a];
+        return w && w.label.trim() ? w.label : null;
+    };
+}
+/**
+ * O mesmo, na versão CURTA — para a legenda do título, onde a palavra vive debaixo de um glifo.
+ *
+ * ⚠️ RECUA PARA `label`, e o recuo é a decisão: uma legenda apertada é pior que uma bonita e melhor que uma
+ * vazia. Vazia sumiria também para quem usa leitor de tela, que é o custo que não se aceita aqui.
+ */
+export function shortLabellerFrom(p) {
+    return (a) => {
+        const w = p[a];
+        if (!w)
+            return null;
+        const curto = w.short && w.short.trim() ? w.short : w.label;
+        return curto && curto.trim() ? curto : null;
+    };
+}
+/**
+ * Um preset é bem-formado? Devolve os problemas — VAZIA quer dizer conforme.
+ *
+ * ⚠️ O QUE ELE APANHA É O RÓTULO VAZIO, e é o mesmo defeito silencioso de `speakableProblems` em
+ * `core/contract`: um `label` em branco não quebra nada, não avisa ninguém, e deixa a tela de remapeamento
+ * com uma linha muda — que para quem usa leitor de tela é um botão que existe e não tem nome.
+ */
+export function presetProblems(p) {
+    if (!p)
+        return ['preset: missing'];
+    const problemas = [];
+    const nomeadas = presetActions(p);
+    if (nomeadas.length === 0)
+        problemas.push('preset: names no action - the child would see an unlabelled control');
+    for (const chave of Object.keys(p)) {
+        if (!isAction(chave))
+            problemas.push(`preset: ${chave} is not an action`);
+    }
+    for (const a of nomeadas) {
+        const w = p[a];
+        if (!w || !w.label || !w.label.trim()) {
+            problemas.push(`preset: ${a} has an empty label - the remap screen would show a nameless button`);
+        }
+    }
+    return problemas;
+}
+/** É uma ação conhecida? Guarda de fronteira para dado que veio de fora (mapa salvo, remapeamento). */
+export function isAction(x) {
+    return typeof x === 'string' && ACTIONS.includes(x);
+}
+/**
+ * Uma declaração de ações usadas por um jogo é bem-formada? Devolve os problemas — VAZIA quer dizer conforme.
+ *
+ * ⚠️ EXIGIR AS QUATRO DIREÇÕES SERIA ERRADO, e a tentação é grande: um quiz navega por `up`/`down` e não usa
+ * `left`/`right`; um jogo de um botão não usa nenhuma. Quem decide o conjunto é o jogo. O que esta função
+ * confere é que o conjunto é NOMEÁVEL e não está vazio — um jogo sem ação nenhuma não tem como ser jogado, e
+ * hoje isso falharia em silêncio no primeiro transporte que tentasse ligar-se a nada.
+ */
+export function actionSetProblems(used) {
+    const p = [];
+    if (!used)
+        return ['action set: missing'];
+    if (used.length === 0)
+        return ['action set: empty - a game with no action cannot be played'];
+    const desconhecidas = used.filter((a) => !isAction(a));
+    if (desconhecidas.length)
+        p.push(`action set: unknown action(s) ${desconhecidas.join(', ')}`);
+    if (new Set(used).size !== used.length)
+        p.push('action set: has a repeated action');
+    return p;
+}

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

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * ANDA UM PASSO NUM ANEL — passar do último volta ao primeiro, e antes do primeiro está o último.
+ *
+ * Era `clampIndex`, que prendia nas pontas "porque o original nunca faz wrap em lista de itens". O ADR-0044
+ * derrubou isso, e o motivo é de uso, não de gosto: com UM MENU POR TELA, toda lista pode ser um anel, e o
+ * item mais indesejado (`quit`) fica a UMA tecla do mais urgente (`resume`) sem estar perto dele. Quem não
+ * enxerga não varre a lista à procura do fim — ela pergunta "e antes do primeiro?" e recebe uma resposta.
+ *
+ * A XAG 106 permite o anel exatamente para menu LINEAR, e o proíbe para grade 2-D de blocos: ali "voltar ao
+ * primeiro" não tem significado espacial.
+ *
+ * ⚠️ NAVEGAR LISTA É ANEL; AJUSTAR VALOR É LIMITE. `selectStep` e `rangeStep` (em ui/menu-nav) continuam
+ * presos nas pontas, e a diferença é real: passar do volume máximo para o mínimo com uma tecla é um susto,
+ * não uma conveniência — e num jogo com pistas de áudio para cegueira, um susto de volume é dano.
+ */
+export declare function passoNoAnel(len: number, idx: number, delta: number): number;

package/dist-pkg/core/anel.js

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// core/anel — A CONTA DO ANEL, e nada mais.
+//
+// Ela morava em `ui/menu-nav`, e saiu de lá quando o item 7 do ADR-0044 fez `ui/pause-icons` precisar dela
+// também: `menu-nav` já importava `pause-icons` (por `mostrarSubmenuDaPausa` e `PM_ITENS_VISIVEIS`), e a volta
+// fecharia um CICLO de importação. Ciclo em ESM não estoura na hora — estoura no boot, em TDZ, quando um dos
+// dois lê o outro durante a avaliação. É o tipo de defeito que aparece uma vez, em produção, e some ao ser
+// investigado.
+//
+// Módulo-folha de propósito: zero dependências, uma função, nenhuma I/O. `ui/menu-nav` continua a
+// reexportando, porque é de lá que os testes e os outros menus já a importavam — o nome público não muda.
+/**
+ * ANDA UM PASSO NUM ANEL — passar do último volta ao primeiro, e antes do primeiro está o último.
+ *
+ * Era `clampIndex`, que prendia nas pontas "porque o original nunca faz wrap em lista de itens". O ADR-0044
+ * derrubou isso, e o motivo é de uso, não de gosto: com UM MENU POR TELA, toda lista pode ser um anel, e o
+ * item mais indesejado (`quit`) fica a UMA tecla do mais urgente (`resume`) sem estar perto dele. Quem não
+ * enxerga não varre a lista à procura do fim — ela pergunta "e antes do primeiro?" e recebe uma resposta.
+ *
+ * A XAG 106 permite o anel exatamente para menu LINEAR, e o proíbe para grade 2-D de blocos: ali "voltar ao
+ * primeiro" não tem significado espacial.
+ *
+ * ⚠️ NAVEGAR LISTA É ANEL; AJUSTAR VALOR É LIMITE. `selectStep` e `rangeStep` (em ui/menu-nav) continuam
+ * presos nas pontas, e a diferença é real: passar do volume máximo para o mínimo com uma tecla é um susto,
+ * não uma conveniência — e num jogo com pistas de áudio para cegueira, um susto de volume é dano.
+ */
+export function passoNoAnel(len, idx, delta) {
+    if (len <= 0)
+        return 0;
+    return ((idx + delta) % len + len) % len; // o `+ len` extra: `%` de negativo em JS devolve negativo
+}

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

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+export type CollisionCtx = {
+    world: number[][];
+    W: number;
+    H: number;
+    isWheelchair: () => boolean;
+    isModoCego: () => boolean;
+    caneDiv: () => number;
+    wcSolid: () => ReadonlySet<string>;
+    gateTiles: () => ReadonlySet<string>;
+    gateOpen: () => boolean;
+};
+export declare function initCollision(ctx: CollisionCtx): void;
+export declare const caneBlockPx: () => number;
+export declare const isSolidType: (t: number) => boolean;
+export declare const tileAt: (tx: number, ty: number) => number;
+export declare const solidTile: (x: number, y: number) => boolean;
+export declare const solidAt: (tx: number, ty: number) => boolean;
+export declare const surfTop: (x: number, y: number) => boolean;
+export declare const isWcRampRiser: (col: number, row: number) => boolean;
+export declare function rampSurfaceY(cx: number, py: number): number | null;

package/dist-pkg/core/collision.js

@@ -0,0 +1,62 @@
+// 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/constants.d.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+export declare const LOGICAL_W = 320, LOGICAL_H = 180, TILE = 16;
+export declare const COIN_TARGET = 10;
+export declare const TUNE: {
+    jumpVel: number;
+    waterJump: number;
+    waterJumpRun: number;
+    waterStrokeFrames: number;
+    trampBase: number;
+    trampMax: number;
+    gravity: number;
+    hWalk: number;
+    hRun: number;
+    climbSpeed: number;
+    maxFall: number;
+    waterMaxFall: number;
+    hTurbo: number;
+    ultraJumpVel: number;
+};
+export declare const JUMP_BASE: number;
+export declare const ANIM: {
+    walkHold: number;
+    runHold: number;
+    idleHold: number;
+    swimHold: number;
+    clingHold: number;
+    climbHold: number;
+    flavorDelay: number;
+};
+export declare const EASY: {
+    grav: number;
+    jump: number;
+    speed: number;
+    pad: number;
+    slowFall: number;
+    tramp: number;
+};
+/** O que um tipo de tile é. Estava privado em `core/collision`; público aqui, que é onde a tabela mora. */
+export type TileType = {
+    solid?: boolean;
+    bounce?: number;
+    water?: boolean;
+    jump?: boolean;
+    ladder?: boolean;
+    tramp?: boolean;
+    hazard?: boolean;
+    gate?: boolean;
+    key?: boolean;
+    /** Ar de REGIÃO SECRETA (o tile 0). A propriedade é nova; o significado não — `TILE_NAME[0]` já dizia
+     *  "ar escuro/secreto". Estava só na tabela de NOMES, que ninguém consulta para decidir nada. */
+    secreto?: boolean;
+};
+export declare const TILE_TYPES: Record<number, TileType>;
+/** Machuca ao encostar (lava). */
+export declare const ehPerigo: (t: number) => boolean;
+/** Água: nada-se dentro, e o pulo funciona lá. */
+export declare const ehAgua: (t: number) => boolean;
+/** Escada: sobe e desce. */
+export declare const ehEscada: (t: number) => boolean;
+/** Trampolim: arremessa para cima. */
+export declare const ehTrampolim: (t: number) => boolean;
+/** Portão: barra até a chave abrir. */
+export declare const ehPortao: (t: number) => boolean;
+/** A chave que abre o portão. */
+export declare const ehChave: (t: number) => boolean;
+/** Ar de região secreta: o que a escuridão cobre até alguém entrar. */
+export declare const ehSecreto: (t: number) => boolean;
+export declare const TILE_COLOR: {
+    0: string;
+    1: string;
+    2: string;
+    3: string;
+    4: string;
+    5: string;
+    6: string;
+    7: string;
+    8: string;
+    9: string;
+    10: string;
+    11: string;
+    12: string;
+    13: string;
+    14: string;
+};

package/dist-pkg/core/constants.js

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Constantes puras (imutáveis) do jogo — módulo-folha, ZERO deps. TypeScript (Estágio 3): tipos inferidos dos literais.
+// TUNE é objeto mutável (o painel de debug ajusta propriedades), mas NUNCA reatribuído → o import const
+// funciona (mutar propriedade é ok; reatribuir é que quebraria). Ver docs/plano-modularizacao.md.
+export const LOGICAL_W = 320, LOGICAL_H = 180, TILE = 16;
+export const COIN_TARGET = 10;
+export const TUNE = {
+    jumpVel: 3.5, waterJump: 3.5, waterJumpRun: 4, waterStrokeFrames: 30,
+    trampBase: 5, trampMax: 8, gravity: 0.15, hWalk: 2, hRun: 3, climbSpeed: 1.5,
+    maxFall: 7, waterMaxFall: 3, hTurbo: 4.5, ultraJumpVel: 10, // E12: power-ups (valores do José)
+};
+export const JUMP_BASE = TUNE.jumpVel * Math.sqrt(8 / 5); // ~4.43 (altura confortável)
+// E15: cadência de animação (ticks por quadro) — regulável ao vivo no painel ?debug=true. Como TUNE, é objeto
+// mutável (o debug ajusta propriedades) mas NUNCA reatribuído → import const funciona. andar 6; correr 8 (~8fps,
+// pedido do José); idle 20; swim 24; cling 10; escada 8; flavor ~6s.
+export const ANIM = { walkHold: 6, runHold: 8, idleHold: 20, swimHold: 24, clingHold: 10, climbHold: 8, flavorDelay: 360 };
+// Modo FÁCIL (acessibilidade motora): multiplicadores que suavizam a física. grav ×2/3, pulo ×8/7, velocidade
+// ×0,7, zona-morta do pad ×4, queda lenta ×1,4, trampolim ×3,4. Lido pela física (game.js) e por jumpVel (player).
+export const EASY = { grav: 2 / 3, jump: 8 / 7, speed: 0.7, pad: 4, slowFall: 1.4, tramp: 3.4 };
+export const TILE_TYPES = {
+    0: { solid: false, secreto: true }, 1: { solid: false }, 2: { solid: true, bounce: 0.28 }, 3: { solid: false, water: true, jump: true },
+    4: { solid: false, ladder: true }, 5: { solid: true, bounce: 1.1, tramp: true }, 6: { solid: true, bounce: 0 },
+    7: { solid: false }, 8: { solid: false }, 9: { solid: false, hazard: true }, 10: { solid: true, gate: true },
+    11: { solid: false, key: true }, 12: { solid: false }, 13: { solid: false }, 14: { solid: false },
+};
+/* ===================== QUEM PODE IMPORTAR ESTAS PERGUNTAS =====================
+ *
+ * Nem todo módulo que lê tile pode ler a TABELA. Quatro de engine — `render/scene-sky`, `render/scene-city`,
+ * `platform/audio-ambient` e `platform/audio-nav` — recebem `tileAt` por INJEÇÃO, de propósito: é o que os
+ * deixa rodar no project `node` com um mundo de mentira, e é o que os faz não conhecer a numeração DESTE mapa.
+ * Importar a tabela neles trocaria um número mágico por uma dependência nova, o que é pior.
+ *
+ * Eles ficam com as comparações que têm até a decisão do eixo (#64): sob contrato declarado, quem recebe
+ * `tileAt` por injeção deve receber TAMBÉM a semântica, e a forma dessa entrega ainda não tem evidência que a
+ * escolha. Acrescentar campos de ctx agora seria chutar a forma da pergunta — o erro que o `menu-nav` ensinou
+ * a não cometer (`getPhase()` contra `isNavigable()`).
+ *
+ * Regra prática: importe daqui se o módulo já importa `core/collision`; se ele recebe `tileAt` por ctx, não.
+ */
+/* ===================== as perguntas, com nome =====================
+ * Uma função por propriedade, e não `TILE_TYPES[t]?.hazard` espalhado: o nome é o que torna a intenção legível
+ * no ponto de uso (`ehPerigo(t)` contra `t === 9`) e é o que dá UM lugar para mudar no dia em que a resposta
+ * deixar de vir de uma tabela global. Todas devolvem `false` para tipo desconhecido — um tile que ninguém
+ * declarou não machuca, não é água e não se escala; inventar semântica para o desconhecido é pior que negá-la.
+ */
+const prop = (t, k) => !!TILE_TYPES[t]?.[k];
+/** Machuca ao encostar (lava). */
+export const ehPerigo = (t) => prop(t, 'hazard');
+/** Água: nada-se dentro, e o pulo funciona lá. */
+export const ehAgua = (t) => prop(t, 'water');
+/** Escada: sobe e desce. */
+export const ehEscada = (t) => prop(t, 'ladder');
+/** Trampolim: arremessa para cima. */
+export const ehTrampolim = (t) => prop(t, 'tramp');
+/** Portão: barra até a chave abrir. */
+export const ehPortao = (t) => prop(t, 'gate');
+/** A chave que abre o portão. */
+export const ehChave = (t) => prop(t, 'key');
+/** Ar de região secreta: o que a escuridão cobre até alguém entrar. */
+export const ehSecreto = (t) => prop(t, 'secreto');
+export const TILE_COLOR = {
+    0: '#0a0a14', 1: '#241f38', 2: '#6b6480', 3: '#2f6fae', 4: '#8a5a2b', 5: '#34e29b', 6: '#3a3a46',
+    7: '#7fdcff', 8: '#ffd23f', 9: '#ff5b3a', 10: '#9a8a6f', 11: '#ffe06a', 12: '#3a86ff', 13: '#8a5cff', 14: '#ff6fae',
+};