@the-inclusionist/engine 7.0.0 → 8.0.0-rc.1

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

@@ -1,23 +1,5 @@
 // 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;
@@ -53,18 +35,8 @@ export type TileType = {
 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;

package/dist-pkg/core/constants.js

@@ -3,13 +3,22 @@
 // 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)
+// ⚠️ `COIN_TARGET` e `TUNE` MUDARAM DE CASA EM 2026-09-07 — foram para `game/tuning.ts` do `game-platformer`
+// (issue #63, etapa B, decisão do Dev). Tinham ZERO importadores dentro desta árvore e TODOS do outro lado
+// da fronteira do pacote: não eram código morto, eram a superfície pública que o cartucho consumia.
+//
+// Uma engine que exporta a GRAVIDADE e a META DE MOEDAS está a decidir que todo jogo é uma plataforma de
+// coletar coisas. `TUNE` é gravidade, velocidade de nado e curso do trampolim — a física DAQUELE jogo; um
+// quiz não tem gravidade. `COIN_TARGET` é o objetivo, que é conteúdo.
+//
+// A etapa C (o segundo consumidor) é o que autorizou o corte: catorze achados, e nenhum reclama estes dois
+// para a engine. O `ui/debug-panel` continua a afinar o `TUNE` ao vivo — ele sempre o recebeu por INJEÇÃO
+// (`TUNE: Tune` no ctx), nunca por importação, e é por isso que a mudança não lhe custou nada.
+// ⚠️ `JUMP_BASE` SAIU EM 2026-09-07 (issue #63, etapa B, decisão do Dev). Não tinha um único consumidor:
+// nem na engine, nem no `game-platformer`, nem nos testes — fora UM, que verificava que
+// `JUMP_BASE === jumpVel * sqrt(8/5)`, ou seja **reafirmava a própria definição**. Um teste que não pode
+// falhar por motivo que importe, a manter viva uma constante que ninguém usa. A própria issue #63 já o
+// nomeava no seu «achado solto».
 // 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.
@@ -46,18 +55,26 @@ export const TILE_TYPES = {
 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');
+// ⚠️ `ehAgua`, `ehEscada`, `ehPortao` e `ehSecreto` MUDARAM DE CASA EM 2026-09-07 — foram para
+// `game/tile-flags.ts` do `game-platformer` (issue #63, etapa B). Tinham zero importadores aqui dentro.
+//
+// E as duas que ficaram — `ehPerigo` e `ehTrampolim` — ficaram por um motivo MEDIDO, não por simetria: a
+// engine lê-as, e não por geometria. O `isSolidType` de `core/collision` torna perigo e trampolim SÓLIDOS
+// no modo cadeira de rodas, e perigo sólido no modo cego. É uma regra de ACESSIBILIDADE — a criança em
+// cadeira de rodas não cai no fosso — e essa é da engine.
+//
+//     A engine precisa de saber que um tile é PERIGO; não precisa de saber que ele é ESCADA.
+//
+// ⚠️ O QUE FICA POR DECIDIR, e está registado na #63: a `TILE_TYPES` acima continua a carregar as bandeiras
+// `water`, `ladder`, `gate`, `key` e `secreto`, que **nenhum módulo desta árvore lê**. Enquanto elas aqui
+// estiverem, o jogo faz perguntas sobre uma tabela que a engine publica. O fim honesto é a tabela mudar de
+// casa e o jogo declarar os papéis pelo `core/contract` (`roleOf`) — que é o mecanismo que já existe para
+// isso. Não é execução: é a fronteira seguinte, e ela é decisão do Dev.
+// ⚠️ `ehChave` SAIU EM 2026-09-07, pelo mesmo motivo e no mesmo passo que a `JUMP_BASE`: zero consumidores
+// em lado nenhum — engine, testes e cartucho. Os outros predicados de tile ficam por enquanto porque o
+// `game-platformer` os importa; estes dois não eram fronteira mal cortada, eram peso morto.
 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',

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

@@ -174,6 +174,45 @@ export interface GameDeclaration {
      * o esquecimento passar como se fosse escolha.
      */
     world(): WorldScope;
+    /**
+     * QUANTAS POSIÇÕES ESTE JOGO PRECISA DE SEGURAR AO MESMO TEMPO. Correr + andar + pular são TRÊS; um quiz é
+     * UM. (ADR-0104 §A.)
+     *
+     * ⚠️ É UM EIXO DIFERENTE DE «QUANTAS AÇÕES», e é por não serem o mesmo que existia um ponto cego onde o
+     * aviso nunca disparava. Medido: a plataforma declara NOVE ações e o controle de tela tem NOVE lugares,
+     * então o `alcance().ok` era verdadeiro e o cartão da #112 nunca aparecia — mas correr, andar e pular ao
+     * mesmo tempo são três dedos, e num telemóvel de dois a criança simplesmente não consegue, sem nada em
+     * lado nenhum a dizer porquê. Alcançar uma ação e segurá-la junto com outra são perguntas distintas.
+     *
+     * ⚠️ OBRIGATÓRIO, e a obrigatoriedade É a decisão, na frase do Dev: «os 300 jogos precisam declarar sim!
+     * Não declarar é ter a acessibilidade programada no controle pro sorte». Um campo opcional é respondido
+     * por SILÊNCIO, e aqui o silêncio decide pela criança — decide-o quem não pensou no assunto. Trezentos
+     * jogos a responder deliberadamente é o custo; acessibilidade por sorte é a alternativa.
+     *
+     * FUNÇÃO e não valor, pela mesma razão que a `topology`: um jogo com fases troca de exigência entre elas —
+     * uma fase a pé pede três, a mesma fase num veículo pode pedir uma. Um valor memorizado ficaria defasado
+     * em silêncio, que é o defeito que o ADR-0084 nomeou.
+     */
+    holdsAtOnce(): number;
+    /**
+     * ESTE JOGO PRECISA DE UM PONTEIRO — posição contínua? (ADR-0112.)
+     *
+     * Um jogo de desenho precisa; um quiz não. Declarar faz um aparelho sem ponteiro RECUSAR-SE antes de a
+     * criança começar, em vez de ela descobrir a meio do primeiro traço.
+     *
+     * ⚠️ OPCIONAL, E A DIFERENÇA PARA O `holdsAtOnce` LOGO ACIMA É DELIBERADA — copiar a obrigatoriedade dele
+     * seria aplicar uma regra cuja premissa não se sustenta aqui. O `holdsAtOnce` é obrigatório porque não tem
+     * padrão seguro E porque falha INVISIVELMENTE a quem escreve o jogo: ele tem teclado completo, o jogo corre,
+     * e quem descobre o defeito é a criança no telemóvel de dois dedos. Este tem padrão seguro (`false`) e falha
+     * VISIVELMENTE — um jogo de desenho que se esqueça de o declarar é inoperável no próprio aparelho de quem o
+     * escreve, porque ele também precisaria do ponteiro para o experimentar.
+     *
+     * Obrigar trezentos jogos a escrever `needsPointer: () => false` cobraria o preço do `holdsAtOnce` sem o
+     * motivo dele.
+     *
+     * FUNÇÃO e não valor, pela mesma razão das outras: uma actividade pode desenhar numa fase e não noutra.
+     */
+    needsPointer?(): boolean;
     readonly tick: TickOwner;
     /** O papel do que está em `at`. É o campo 2, e é o que substitui `roleOf`. */
     roleAt(at: Spot): Role;

package/dist-pkg/core/contract.js

@@ -108,6 +108,42 @@ export function conformanceProblems(d) {
         else if (w.kind !== 'none')
             p.push('world: unknown kind');
     }
+    // ⚠️ A MENSAGEM NOMEIA A SAÍDA, como as outras quatro fazem. Um jogo que não declara isto não recebe um
+    // padrão — recebe uma frase que diz o que perguntar a si próprio, porque a resposta é do jogo e de mais
+    // ninguém. (ADR-0104 §A.)
+    if (typeof d.holdsAtOnce !== 'function') {
+        // ⚠️ A MENSAGEM NÃO NOMEIA GÊNERO, e o gate de fronteira cobrou-o: a primeira escrita dizia «run+walk+jump
+        // is 3, a quiz is 1» e o `engine-boundary` reprovou a palavra «quiz» em linha de CÓDIGO da engine. Ele
+        // tinha razão, e a frase ficou melhor: descreve a FORMA da pergunta, que serve aos 300 jogos, em vez de
+        // dois exemplos que servem a dois.
+        p.push('holdsAtOnce: missing - declare how many positions are held AT ONCE (three if three fingers must press together, one if commands arrive one at a time)');
+    }
+    else {
+        const n = d.holdsAtOnce();
+        if (!Number.isInteger(n) || n < 1) {
+            // Zero não é «não usa controle»: um jogo que não segura posição nenhuma não é jogável, e devolver zero
+            // faria a aritmética do alcance passar por vacuidade — o mesmo defeito que o `reachable` recusa.
+            p.push('holdsAtOnce: must be an integer >= 1 - a game that holds nothing cannot be played');
+        }
+    }
+    // ⚠️ OPCIONAL, MAS NÃO IMPUNE. Ausente é a resposta `false` e não é problema — ver a nota no campo. O que
+    // se recusa é declará-lo MAL: um `needsPointer: true` (valor em vez de função) seria sempre verdadeiro por
+    // ser um objecto, e um que devolvesse `'sim'` também. Nos dois casos o jogo julgaria ter declarado, o
+    // alcance leria uma coisa diferente do que ele quis dizer, e ninguém saberia — que é o defeito silencioso
+    // que esta função inteira existe para não deixar acontecer.
+    if (d.needsPointer !== undefined) {
+        if (typeof d.needsPointer !== 'function') {
+            // ⚠️ MENSAGENS SEM A PALAVRA `as`, e o motivo merece uma linha porque volta a morder: o detector de prosa
+            // pt-BR do `engine-i18n` casa palavras funcionais isoladas, e `as` é artigo plural em português. Uma
+            // mensagem INGLESA que diga «declare it as …» é contada como texto cru e faz o tecto do módulo subir.
+            // O cabeçalho daquele gate já admite a aproximação («senão 'mode' casa 'de'»); reescrever a frase custa
+            // nada e afrouxar o detector custaria a razão de ele existir.
+            p.push('needsPointer: must be a function - write `needsPointer: () => true`, because a game may draw in one phase and not in another');
+        }
+        else if (typeof d.needsPointer() !== 'boolean') {
+            p.push('needsPointer: must return a boolean - a non-boolean would be truthy and refuse devices this game can actually use');
+        }
+    }
     if (d.tick !== 'player' && d.tick !== 'clock')
         p.push('tick: must be "player" or "clock"');
     for (const f of ['roleAt', 'nameAt', 'focusOf', 'objectiveOf', 'targetsOf']) {

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

@@ -1,6 +1,23 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** Ação → lista de códigos físicos (`KeyA`, `ArrowLeft`…). Fonte única: estava triplicado em input/. */
-export type KeyScheme = Record<string, string[]>;
+import type { Action } from './actions.js';
+import type { VisualState } from '../render/viz-axes.js';
+/**
+ * Ação → lista de códigos físicos (`KeyA`, `ArrowLeft`…). Fonte única: estava triplicado em input/.
+ *
+ * ⚠️ FECHADO EM `Action` DESDE 2026-09-07 (issue #118, decisão do Dev), e era `Record<string, string[]>`.
+ * Enquanto foi aberto, **faltar uma posição não dava erro de compilação** — e foi assim que o esquema de
+ * dupla ficou com oito das quatorze, e que a `Space` do jogador 1 desapareceu sem que nada apitasse. O
+ * defeito não era de digitação: era de o tipo aceitar um esquema incompleto como se fosse completo.
+ *
+ * ⚠️ E `null` NÃO É BURACO — é AUSÊNCIA DECLARADA, e é a metade que dá sentido a fechar o tipo. Um teclado
+ * partido por quatro pode não ter lugar físico para ombros e gatilhos; dizer `null` afirma isso, e é o que o
+ * aviso de alcance (`ui/reach-notice`, issue #112) lê para dizer à criança, ANTES de ela começar, quais das
+ * ações do jogo o controlo dela não alcança. Inventar teclas para preencher seria mentir-lhe em silêncio.
+ *
+ * Quem consome tem de tratar o `null`: `input/keyboard-runtime`, `input/touch-bindings` e
+ * `ui/settings-controls` fazem-no, e é isso que impede um `null` de virar um `undefined.includes`.
+ */
+export type KeyScheme = Record<Action, readonly string[] | null>;
 /** Lados da ventosa-aranha: direita, esquerda, teto, chão. */
 export type ClingSide = 'R' | 'L' | 'U' | 'D';
 /**
@@ -76,6 +93,26 @@ export interface Player {
     ctrl: KeyScheme | null;
     /** Índice do gamepad, ou -1 quando o jogador não tem controle físico. */
     pad: number;
+    /**
+     * O ESTADO VISUAL desta criança, em DOIS EIXOS mais a simulação (ADR-0076, issue #104).
+     *
+     * ⚠️ `import type`, e a seta aponta para cima. `core/` não deveria importar de `render/`, e o tipo do
+     * ESTADO discutivelmente devia morar aqui em vez de lá. Fica assim de propósito e declarado: é só tipo,
+     * apagado em execução, sem aresta em runtime — e mover o módulo a meio da migração seria churn no ficheiro
+     * mais partilhado do repositório. Se `viz-axes` se dividir um dia, o `VisualState` vem para `core/` e as
+     * funções de renderização ficam lá.
+     */
+    visual: VisualState;
+    /**
+     * @deprecated ⚠️ O ESPELHO LEGADO, e ele morre nesta migração. Enquanto os dois existirem, `setPlayerViz`
+     * escreve os DOIS e um gate exige que nunca discordem — é o que deixa cada leitor migrar sozinho, com a
+     * árvore verde entre cada passo, em vez de uma passagem única onde não há onde parar.
+     *
+     * ⚠️ E ELE NÃO CONSEGUE EXPRIMIR O QUE A #104 EXISTE PARA PERMITIR: uma criança com `hc7` E `fix-deuter` ao
+     * mesmo tempo não tem chave única que a descreva. Por isso o espelho só sobrevive enquanto os controles
+     * ainda escrevem um valor de cada vez; assim que eles passam a escrever por eixo, ele deixa de poder
+     * acompanhar e sai.
+     */
     viz: string;
     easy: boolean;
     toggleMove: boolean;
@@ -124,9 +161,15 @@ export interface Player {
     alfWins?: number;
     /** ui/settings-audio, ui/pause-icons: saída de áudio própria; `null`/ausente = compartilhada. */
     audioSink?: string | null;
-    /** platform/audio-nav: temporizadores do sonar de parede e do guia. */
+    /**
+     * platform/audio-nav: temporizador do sonar de parede.
+     *
+     * ⚠️ `guideT` SAIU em 2026-09-07 (#84 item 2), e a ausência é a notícia: ele contava os 48 quadros entre
+     * dois bipes do guia, e não há mais bipe nenhum para temporizar. O que o substituiu — o grafo de áudio vivo
+     * — não é da entidade da engine e por isso não nasce aqui: mora em `PlayerAudioOut`, ao lado do `_ac`, pela
+     * mesma regra que o parágrafo acima explica.
+     */
     wnT?: number;
-    guideT?: number;
 }
 /**
  * Um jogador DEPOIS de `assignControls` — o `ctrl` deixou de ser `null`.

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

@@ -32,6 +32,24 @@ export declare const Z: {
     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

package/dist-pkg/core/layers.js

@@ -49,6 +49,24 @@ export const Z = {
     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

package/dist-pkg/core/rng.js

@@ -42,10 +42,20 @@ export const createRng = (semente = SEMENTE_PADRAO) => {
     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)`.
+// ⚠️ ESTE BLOCO TINHA DATA DE MORTE ESCRITA, E ELA NÃO CHEGOU — A PREMISSA É QUE MORREU.
+// Dizia: «Existe porque `game/` ainda vive aqui dentro (issue #111). Quando `game/` sair, isto sai com ele.»
+// O `game/` saiu em 2026-09-07 — e saiu para OUTRO REPOSITÓRIO, onde continua a consumir estes quatro pelo
+// pacote. Medido no dia: `@the-inclusionist/game-platformer` importa `rnd`, `randInt` e `shuffle` em OITO
+// módulos (`quiz`, `physics`, `life`, `traffic`, `fractions`, `coins`, `coin-spawning`,
+// `literacy-distractors`) mais o `main.ts`.
+//
+// Ou seja, o que se previu como «sai junto» virou o oposto: saindo, o cartucho tornou-os SUPERFÍCIE
+// PÚBLICA de um pacote publicado. Removê-los agora é quebra de contrato maior, não limpeza.
+//
+// ⚠️ E A ADVERTÊNCIA CONTINUA VERDADEIRA, o que é o incómodo: são estado partilhado de módulo, que é
+// exatamente o defeito que a fábrica acima conserta. Um segundo jogo na mesma página divide esta corrente
+// com o primeiro. O caminho de saída é o consumidor passar a `createRng(suaSemente)` — e isso é migração
+// dele, com aviso e um major, não uma remoção unilateral daqui.
 const _padrao = createRng(SEMENTE_PADRAO);
 export const reseed = _padrao.reseed;
 export const rnd = _padrao.rnd;

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

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Role, Spot, Topology } from './contract.js';
+/**
+ * Os papéis que uma rota atravessa. Leitura do `core/contract`, com o `hazard` de fora por decisão declarada
+ * no cabeçalho — e `goal` de fora porque ele entra pela regra do último passo, não pela do meio.
+ */
+export declare const PAPEIS_ATRAVESSAVEIS: ReadonlySet<Role>;
+/** Este papel deixa passar? */
+export declare function atravessavel(papel: Role): boolean;
+export interface RouteCtx {
+    /** Campo 1 do contrato. A métrica decide QUANTOS vizinhos um ponto tem. */
+    readonly topology: Topology;
+    /** Campo 2 do contrato: o que há neste ponto. Obrigatório na `GameDeclaration`, logo sempre disponível. */
+    readonly roleAt: (at: Spot) => Role;
+    /**
+     * Teto de pontos visitados. Estourou → `null`, que é «não sei».
+     *
+     * 4096 é ~64×64 numa grade e cobre com folga os tabuleiros que existem hoje; num mapa de plataforma grande
+     * ele corta antes de a busca custar um quadro. O número é PARÂMETRO porque o custo aceitável é de quem
+     * chama: uma pista por quadro tolera muito menos do que um cálculo ao carregar a fase.
+     */
+    readonly orcamento?: number;
+}
+export interface Rota {
+    /** O PRÓXIMO ponto a pisar — a um passo de onde se está. É isto que uma pista aponta. */
+    readonly proximo: Spot;
+    /** Qual dos alvos a rota alcançou. Pode não ser o mais próximo em linha reta, e é esse o ponto. */
+    readonly ate: Spot;
+    /** Quantos passos ao longo do caminho. ⚠️ NÃO é `distance()`, que mede a reta que atravessa parede. */
+    readonly passos: number;
+}
+/**
+ * A rota de `de` até o mais próximo ALCANÇÁVEL dos `alvos` — largura primeiro, sobre o que se atravessa.
+ *
+ * `null` quando não há alvo, quando nenhum é alcançável, quando a topologia não tem espaço (`hotspots`), ou
+ * quando o orçamento estourou. Os quatro casos são o mesmo para quem chama: **não sei dizer por onde**.
+ *
+ * ⚠️ «MAIS PRÓXIMO» AQUI É AO LONGO DO CAMINHO, e é a diferença inteira. Um alvo a três células em linha reta
+ * do outro lado de uma parede está mais LONGE do que um a oito células por um corredor aberto — e é o segundo
+ * que a criança consegue alcançar.
+ */
+export declare function rotaAte(ctx: RouteCtx, de: Spot, alvos: readonly Spot[]): Rota | null;

package/dist-pkg/core/route.js

@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// core/route — POR ONDE SE VAI ATÉ LÁ, e não só onde é lá (#84, item 1).
+//
+// ========================= O DEFEITO QUE ISTO EXISTE PARA CONSERTAR =========================
+// A issue #84 escreve-o em duas linhas, e elas são o módulo inteiro:
+//
+//     «Sem isso, qualquer pista aponta em LINHA RETA para o alvo, e a linha reta atravessa parede: hoje
+//      `alvoMaisProximo()` mede distância pela métrica declarada e `panFor()` só compara `x`, então o guia
+//      manda a criança andar para dentro de um bloco sólido e ela não tem como saber por quê.»
+//
+// ⚠️ E ELA NÃO TEM MESMO COMO SABER. Uma criança que vê ignora uma seta que aponta para uma parede sem sequer
+// reparar que a ignorou. Quem depende da pista faz o que ela diz — e depois faz outra vez, porque a pista
+// continua a dizer o mesmo. A pista errada é pior do que pista nenhuma: pista nenhuma deixa-a explorar.
+//
+// ========================= O QUE É «ATRAVESSÁVEL», E POR QUE NÃO É INVENÇÃO MINHA =========================
+// A #84 pede «as direções por onde há AR OU ÁGUA». Essas duas palavras já estão no contrato, e cada `Role`
+// diz de si mesmo se se atravessa — o conjunto abaixo é uma LEITURA do `core/contract`, não uma decisão nova:
+//
+//   free       «atravessável e sem significado próprio»          → o ar
+//   water      «atravessa-se nadando»                            → a água
+//   climb      «muda-se de altura interagindo com isto»          → a escada: é POR ELA que se sobe
+//   key        «satisfaz um gate»                                → um objeto pousado, não uma barreira
+//   structure  «cenário: chão, parede, o que sustenta»           → NÃO
+//   gate       «barra até uma condição»                          → NÃO: barrar é o que ele faz
+//   hazard     «machuca ao encostar»                             → NÃO, e é a única onde eu escolhi
+//   goal       «o que a rodada pede»                             → caso à parte, ver `alvo` abaixo
+//
+// ⚠️ O `hazard` É A ESCOLHA, e declaro-a: a métrica dele não diz se se atravessa, diz o que custa. Rota que
+// passa por espinho é rota que manda a criança levar dano — e no modo cego e no modo cadeirante o próprio
+// `core/collision.isSolidType` já o trata como sólido, por decisão de acessibilidade. Encaminhar por cima
+// dele contradiria a camada que existe para a proteger. Um jogo em que o espinho seja passagem obrigatória
+// terá de dizê-lo por outro meio; hoje nenhum diz.
+//
+// ========================= O ALVO É SEMPRE PISÁVEL, E O CAMINHO NÃO =========================
+// Um `goal` pode estar declarado numa célula que não se atravessa (uma bandeira dentro de um portão). Recusar
+// entrar nela faria a rota nunca chegar a lado nenhum. A regra é assimétrica de propósito: **o último passo é
+// sempre permitido; os do meio obedecem ao conjunto.** É a diferença entre «entrar no portão» e «atravessar o
+// portão para continuar do outro lado».
+//
+// ========================= O ORÇAMENTO, QUE O PRÓPRIO CONTRATO PEDIU =========================
+// ⚠️ `core/contract` avisa, na sua secção 5: «num espaço CONTÍNUO não há como enumerar os pontos, e num mapa
+// grande enumerar seria caro por quadro». Este módulo não pode ignorar esse aviso só porque é conveniente.
+// Por isso tem TETO de células visitadas e devolve `null` ao estourá-lo. `null` quer dizer **«não sei»**, e
+// não «não há caminho» — quem chamar tem de tratar os dois iguais, que é o que uma pista honesta faz: cala-se.
+//
+// E não importa nada além do contrato: é lógica pura, aferida no project `node`.
+import { distance } from './contract.js';
+/**
+ * Os papéis que uma rota atravessa. Leitura do `core/contract`, com o `hazard` de fora por decisão declarada
+ * no cabeçalho — e `goal` de fora porque ele entra pela regra do último passo, não pela do meio.
+ */
+export const PAPEIS_ATRAVESSAVEIS = new Set(['free', 'water', 'climb', 'key']);
+/** Este papel deixa passar? */
+export function atravessavel(papel) {
+    return PAPEIS_ATRAVESSAVEIS.has(papel);
+}
+const ORCAMENTO_PADRAO = 4096;
+/** Chave de um ponto na fila. Arredondada, porque no contínuo os pontos nascem de somas de `passo`. */
+const chave = (s, casas) => s.x.toFixed(casas) + '|' + s.y.toFixed(casas) + '|' + (s.z ?? 0).toFixed(casas);
+/**
+ * Os deslocamentos de UM passo, na métrica declarada.
+ *
+ * ⚠️ `free` (L², espaço contínuo sem passo discreto) NÃO TEM VIZINHOS — e fingir que tem é a aproximação que
+ * este módulo faz e declara: ele anda numa GRELHA de lado `unit`, nas oito direções. A alternativa seria não
+ * responder nada num jogo de plataforma, que é justamente o gênero da issue. Quem ler uma rota `free` está a
+ * ler uma amostragem, não uma trajetória — e é por isso que `passos` é uma contagem de células e não uma
+ * medida física.
+ */
+function vizinhos(topo, passo) {
+    if (topo.kind === 'hotspots')
+        return [];
+    const dims = topo.size.length;
+    const ortogonal = topo.move === 'orthogonal';
+    const fora = [];
+    const eixos = [-1, 0, 1];
+    for (const dx of eixos)
+        for (const dy of eixos) {
+            for (const dz of dims > 2 ? eixos : [0]) {
+                const n = Math.abs(dx) + Math.abs(dy) + Math.abs(dz);
+                if (n === 0)
+                    continue;
+                if (ortogonal && n > 1)
+                    continue; // L¹: a diagonal não existe
+                fora.push({ x: dx * passo, y: dy * passo, z: dz * passo });
+            }
+        }
+    return fora;
+}
+/** O ponto cabe na extensão declarada? Grade conta células 0..n−1; contínuo conta unidades 0..n. */
+function dentro(topo, s) {
+    if (topo.kind === 'hotspots')
+        return false;
+    const eixo = [s.x, s.y, s.z ?? 0];
+    for (let i = 0; i < topo.size.length; i++) {
+        const lim = topo.size[i];
+        if (eixo[i] < 0)
+            return false;
+        if (topo.kind === 'grid' ? eixo[i] > lim - 1 : eixo[i] > lim)
+            return false;
+    }
+    return true;
+}
+/**
+ * A rota de `de` até o mais próximo ALCANÇÁVEL dos `alvos` — largura primeiro, sobre o que se atravessa.
+ *
+ * `null` quando não há alvo, quando nenhum é alcançável, quando a topologia não tem espaço (`hotspots`), ou
+ * quando o orçamento estourou. Os quatro casos são o mesmo para quem chama: **não sei dizer por onde**.
+ *
+ * ⚠️ «MAIS PRÓXIMO» AQUI É AO LONGO DO CAMINHO, e é a diferença inteira. Um alvo a três células em linha reta
+ * do outro lado de uma parede está mais LONGE do que um a oito células por um corredor aberto — e é o segundo
+ * que a criança consegue alcançar.
+ */
+export function rotaAte(ctx, de, alvos) {
+    const topo = ctx.topology;
+    if (topo.kind === 'hotspots' || alvos.length === 0)
+        return null;
+    const passo = topo.kind === 'continuous' ? topo.unit : 1;
+    if (!(passo > 0))
+        return null; // uma unidade de zero faria a fila andar sem sair do sítio
+    const casas = topo.kind === 'continuous' ? 4 : 0;
+    // Chegou? Na grade é a mesma célula; no contínuo é meio passo, porque a grelha não cai em cima do alvo.
+    const tolerancia = topo.kind === 'continuous' ? 0.5 : 0;
+    const chegou = (s) => alvos.find((a) => distance(topo, s, a) <= tolerancia) ?? null;
+    const alvoAqui = chegou(de);
+    if (alvoAqui)
+        return { proximo: de, ate: alvoAqui, passos: 0 };
+    const saltos = vizinhos(topo, passo);
+    const teto = ctx.orcamento ?? ORCAMENTO_PADRAO;
+    const vistos = new Set([chave(de, casas)]);
+    // Cada item leva o PRIMEIRO passo que o originou — é só isso que a pista precisa de saber no fim.
+    let fila = [{ at: de, primeiro: de, passos: 0 }];
+    while (fila.length) {
+        const proxima = [];
+        for (const item of fila) {
+            for (const d of saltos) {
+                const vizinho = { x: item.at.x + d.x, y: item.at.y + d.y, z: (item.at.z ?? 0) + (d.z ?? 0) };
+                if (!dentro(topo, vizinho))
+                    continue;
+                const k = chave(vizinho, casas);
+                if (vistos.has(k))
+                    continue;
+                vistos.add(k);
+                if (vistos.size > teto)
+                    return null; // «não sei», e é uma resposta
+                const primeiro = item.passos === 0 ? vizinho : item.primeiro;
+                // O ÚLTIMO PASSO É SEMPRE PERMITIDO: um alvo pode estar declarado numa célula que não se atravessa.
+                const alvo = chegou(vizinho);
+                if (alvo)
+                    return { proximo: primeiro, ate: alvo, passos: item.passos + 1 };
+                if (!atravessavel(ctx.roleAt(vizinho)))
+                    continue;
+                proxima.push({ at: vizinho, primeiro, passos: item.passos + 1 });
+            }
+        }
+        fila = proxima;
+    }
+    return null;
+}

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

@@ -13,7 +13,14 @@
  * Agora `EventoDoJogo` é um mapa nome → carga, e `emit`/`on` são genéricos sobre ele. Nome inexistente não
  * compila; carga errada não compila.
  *
- * ⚠️ POR QUE ISTO EXISTE ANTES DE TER ASSINANTE. Hoje o barramento tem ZERO `on()` em produção (só o teste
+ * ✅ ERRATA 2026-09-08: O BARRAMENTO TEM ASSINANTES EM PRODUÇÃO. O parágrafo abaixo dizia «ZERO `on()` em
+ * produção (só o teste assina)», e isso deixou de ser verdade no dia em que a engine passou a montar a barra
+ * de acessibilidade: o `ui/settings-audio` assina `modoCego` para o botão `#opt-modocego` não mentir o
+ * estado, e o `boot/create-game` assina o mesmo evento para a barra montada não mentir o dela. Os dois
+ * chegaram pela razão que o parágrafo previa — «painéis que se redesenham quando a criança muda um ajuste» —
+ * e chegaram com o contrato já tipado, que era o ponto de ele nascer assim.
+ *
+ * ⚠️ POR QUE ISTO EXISTIU ANTES DE TER ASSINANTE. Hoje o barramento tem ZERO `on()` em produção (só o teste
  * assina). Um mecanismo sem uso normalmente é dívida — mas este precisa nascer tipado, não ser retipado
  * depois: o ADR-0031 já exige que painéis e atividades se redesenhem quando a criança muda idioma ou fonte,
  * e a casca do `demos` vai reagir a ajuste durante a partida. O primeiro assinante chega com o contrato
@@ -93,6 +100,8 @@ export declare const DEFAULTS: Readonly<{
     readonly hcOutlineFg: 1;
     readonly hcOutlineBg: 1;
     readonly letterCase: "upper";
+    readonly calmMode: 0;
+    readonly viz: "normal";
 }>;
 export declare let modoCego: boolean;
 export declare function setModoCegoValue(on: boolean): void;

package/dist-pkg/core/state.js

@@ -152,6 +152,19 @@ export const DEFAULTS = Object.freeze({
     hcOutlineBg: 1,
     // comunicação (hoje só a caixa da letra; o menu de CAA do ADR-0028 amplia isto)
     letterCase: 'upper',
+    // ⚠️ AS DUAS ÚLTIMAS ENTRARAM EM 2026-09-07 (issue #61), e não por simetria: elas faltavam, e a falta
+    // tinha consequência. A marca do ADR-0029 lê `DEFAULTS` e mais nada — regra que continua certa —, e por
+    // isso um valor sem padrão nomeado aqui é um valor que a marca NÃO PODE marcar. Cinco dos sete ícones da
+    // barra rápida caíam nisso.
+    //
+    //   · `calmMode` — o nível TEA (0 normal · 1 calmo · 2 silencioso). Além de não ter padrão, ele não
+    //     PERSISTIA: ver a nota de `KEYS.tea` em platform/storage.
+    //   · `viz` — o modo de visão. `core/entity` declara `viz: string` sem dizer qual é o padrão, e o snapshot
+    //     da barra fazia `p.viz || ''`. Funcionava por acidente: a cadeia vazia não casa `hc-direto` nem
+    //     `fix-*`, então os dois ícones ficavam apagados. `'normal'` é o modo que `render/viz-modes` declara
+    //     com `kind:'normal'` — o que não faz nada —, e passa a ser dito em vez de deduzido.
+    calmMode: 0,
+    viz: 'normal',
 });
 // --- modoCego: MODO CEGO (A12e auditiva). Só as ajudas de áudio — bengala, sonar, guarda de beirada,
 //     narração —, sem tela preta; a simulação de cegueira do Modo Empatia é outra coisa e liga esta por cima.