@the-inclusionist/engine 8.0.0-rc.2 → 9.0.0

package/dist-pkg/boot/create-game.d.ts

@@ -6,6 +6,7 @@ import { type GameDeclaration } from '../core/contract.js';
 import { type SceneStack } from '../core/scenes.js';
 import { createTts, type CarregarVozNeural } from '../platform/tts.js';
 import { type AudioSonar, type SonarPlayer } from '../platform/audio-sonar.js';
+import { type Tema, type Correcao } from '../render/viz-axes.js';
 import type { AlcanceDoFiltro } from '../render/port.js';
 import { type SettingsPanelApi } from '../ui/settings-panel.js';
 import { type MenuNavApi } from '../ui/menu-nav.js';
@@ -180,6 +181,49 @@ export interface CreateGameOptions {
      * teste que não as possa responder não consegue exercitar a tela que depende delas.
      */
     readonly disponibilidade?: Disponibilidade;
+    /**
+     * O QUE CADA ITEM DO CARTÃO DE PAUSA FAZ NESTE JOGO — «continuar», «sair», «ajuda», o que o jogo ligar.
+     *
+     * 🔴 ESTE CAMPO FALTAVA, E A FALTA ALCANÇAVA TODOS OS CONSUMIDORES DE UMA VEZ. O `initPauseIcons`
+     * aceita `getPauseActs` desde que existe; esta raiz não o passava e não tinha campo para ele, logo
+     * **nenhum jogo montado por `createGame`** conseguia ligar um item. O `refrescarItensDaPausa` esconde o
+     * que não acciona — o §5 do ADR-0106, que proíbe botão morto — e o resultado era um cartão com os TRÊS
+     * itens que a engine acciona sozinha (`ITENS_DA_ENGINE`) e nada mais, em todo o catálogo.
+     *
+     * ⚠️ E O CUSTO MAIOR NÃO ERA O CARTÃO, ERA A BARRA. O `entrarNaBarra` chama `acts.resume?.()` para sair
+     * do cartão antes de entregar as direcções à barra de acessibilidade; com a tabela vazia esse `resume` era
+     * `undefined`, o cartão ficava por cima do jogo, e o item 7 do ADR-0044 — o direccional a conduzir a barra
+     * — era **inalcançável a partir de qualquer jogo**.
+     *
+     * 📌 FUNÇÃO e não valor, pela razão que o próprio `ui/pause-icons` regista: a tabela de um jogo muda
+     * durante a partida (um «sair» que só liga depois da primeira fase), e congelá-la no arranque já partiu
+     * um caso lá dentro. Ausente = tabela vazia, que é o comportamento de sempre.
+     */
+    readonly getPauseActs?: () => Record<string, (() => void) | undefined>;
+    /**
+     * QUEM ABRIU A PAUSA, quando há mais de um assento — o painel de controle edita o assento DESTE índice.
+     *
+     * ⚠️ A RAIZ JÁ SE DENUNCIAVA POR NÃO TER ISTO: o bloco 4d empurra uma linha de `problems` quando um jogo
+     * declara mais de um jogador, porque sem ator da pausa a criança do SEGUNDO assento não tem como remapear.
+     * O que faltava para a linha ser accionável era este campo — até agora ela dizia «conserte» sem haver por
+     * onde, e a única saída era declarar `semAtorDePausa`, que é aceitar a perda em vez de a corrigir.
+     */
+    readonly setPauseActor?: (i: number, ...resto: unknown[]) => void;
+    /**
+     * COMO ESTE JOGO REPINTA PARA ALTO CONTRASTE, e como corrige daltonismo — os dois eixos do ADR-0104.
+     *
+     * 🔴 SEM ELES OS ÍCONES ⚫ E 🚥 NÃO SÃO MONTÁVEIS POR NENHUM JOGO. O `iconesQueAccionam` só os monta
+     * para quem entrega quem os escreve, e essa regra está certa — um ícone que não acciona é pior que um
+     * ícone a menos. O que estava errado era não haver PORTA: o consumidor externo que mediu isto leu a
+     * ausência como «este jogo tem os seus próprios controles», o que é verdade sobre o resultado e falso
+     * sobre a causa. Uma lacuna que o consumidor lê como escolha é a pior forma de lacuna.
+     *
+     * ⚠️ SÃO DOIS CAMPOS E NÃO UM, porque são duas perguntas: um jogo pode saber repintar texturas e não ter
+     * como corrigir cor, ou o contrário. O `game-pinball` é o segundo caso — a imagem dele é um framebuffer
+     * de 320x180 sem textura para repintar, e o filtro de cor ele aplica há semanas.
+     */
+    readonly setTemaDoJogador?: (i: number, tema: Tema) => void;
+    readonly setCorrecaoDoJogador?: (i: number, correcao: Correcao) => void;
 }
 export interface Engine {
     readonly declaration: GameDeclaration;
@@ -265,7 +309,28 @@ export interface Engine {
      * tem de poder ser auditado em vez de ficar só numa tela que já fechou.
      */
     readonly alcance: Alcance;
+    /**
+     * TORNA ESTE CARTUCHO O CORRENTE (ADR-0142). Uma raiz de composição, vários jogos.
+     *
+     * ⚠️ **LANÇA** numa declaração malformada, e não a põe em `problems`: o contrato é PRÉ-CONDIÇÃO e não
+     * diagnóstico, tal como no arranque. Um cartucho mau não chega a ser montado.
+     *
+     * 📌 O que ele refaz é só o que não se conserta lendo de novo: os dois registos de mapeamento, que são
+     * efeito global, e o alcance com o seu aviso, que escreve DOM. `problems` e `alcance` passam a descrever
+     * o cartucho montado porque são derivados, não porque `mount` os copie.
+     */
+    mount(declaration: GameDeclaration, ganchos?: GanchosDoCartucho): void;
+    /**
+     * SOLTA O CORRENTE: mapeamentos a `null`, aviso de alcance retirado, pilha de cenas esvaziada.
+     *
+     * ⚠️ A pilha esvazia-se com `pop()` e não com um `clear()`, e a diferença é a decisão: 📏 medido nos seis
+     * jogos, os quatro `exit()` que existem são LIMPEZA DE DOM, logo dispará-los é o teardown que se quer.
+     * Um `clear()` que os saltasse seria o conserto errado.
+     */
+    unmount(): void;
 }
+/** A metade do jogo SEM a declaração — o que `mount` recebe ao lado dela. */
+export type GanchosDoCartucho = Omit<MetadeDoJogo, 'declaration'>;
 /**
  * Liga a engine para um jogo declarado.
  *
@@ -274,4 +339,15 @@ export interface Engine {
  * um id ausente é lacuna do HOSPEDEIRO, e o quiz provou que ligar só a parte que serve é legítimo — foi
  * assim que ele recusou o pad e o sonar sem mentir. Por isso um vira exceção e o outro vira `problems`.
  */
+/**
+ * A METADE DO JOGO de `CreateGameOptions` — os quinze campos que o ADR-0139 §1 diz que um cartucho
+ * FORNECE, separados dos cinco que descrevem a página e o aparelho.
+ *
+ * ⚠️ São quinze e não dez: a primeira versão daquele registo contou quinze campos num total de vinte e
+ * deixou `declines`, `getPauseActs`, `setPauseActor`, `setTemaDoJogador` e `setCorrecaoDoJogador` de fora.
+ * O teste que ele próprio dá — «uma PÁGINA conseguiria responder isto sem saber que jogo corre?» — põe os
+ * cinco deste lado, e a errata de 2026-09-11 corrigiu a lista.
+ */
+type MetadeDoJogo = Pick<CreateGameOptions, 'declaration' | 'isNavigable' | 'comIndice' | 'naBarraDe' | 'navBar' | 'players' | 'setPhase' | 'sonarPlayers' | 'isBlindMode' | 'preset' | 'declines' | 'getPauseActs' | 'setPauseActor' | 'setTemaDoJogador' | 'setCorrecaoDoJogador'>;
 export declare function createGame(o: CreateGameOptions): Engine;
+export {};

package/dist-pkg/boot/create-game.js

@@ -50,7 +50,7 @@ import { initI18n, idiomaPronto } from '../core/i18n.js';
 import { entradaDe } from '../input/state.js';
 import { criarAvisoDeQueda } from '../ui/loop-crash.js';
 import { initFocusTrap, focaveisNoDom } from '../ui/focus-trap.js';
-import { mostrarAvisoDeAlcance } from '../ui/reach-notice.js';
+import { mostrarAvisoDeAlcance, REACH_NOTICE_ID } from '../ui/reach-notice.js';
 import { alcance, transportesPadrao } from '../input/transports.js';
 import { presetActions, ACTIONS } from '../core/actions.js';
 import { t } from '../core/i18n.js';
@@ -76,6 +76,17 @@ import { kb, initKB, registrarMapeamentoDoTeclado } from '../input/keyboard.js';
 import { registrarMapeamentoDoPad } from '../input/pad-defaults.js';
 import { baixarPesados } from '../platform/pesados.js';
 import { installCvdFilters } from '../render/cvd-matrices.js';
+/*
+ * UMA FRASE SÓ PARA AS DUAS RECUSAS, e o gate do pilar 3 é que a pediu.
+ *
+ * ⚠️ O arranque e o `mount()` recusam uma declaração malformada pela MESMA razão e com a mesma frase, e
+ * escrevê-la duas vezes fez o teto de texto cru deste módulo subir de 15 para 16 — o crivo de i18n reprovou,
+ * e reprovou com razão. Duas cópias de uma frase são dois sítios para ela divergir, e é também a segunda
+ * tradução a fazer quando o pilar 3 chegar aqui.
+ */
+function recusarDeclaracao(quem, problemas) {
+    throw new Error(`${quem}: declaração malformada — ${problemas.join('; ')}`);
+}
 /** Os ids que os painéis emprestados exigem do documento. Achado 6: sem eles o painel abre VAZIO, sem erro. */
 const MARCACAO_EXIGIDA = ['#game-region', '#sr-status', '#sr-alert'];
 /**
@@ -87,27 +98,38 @@ const MARCACAO_EXIGIDA = ['#game-region', '#sr-status', '#sr-alert'];
  * frase própria pode explicar O QUE se perde, e é isso que a torna útil a quem a lê pela primeira vez.
  */
 const SELETOR_BARRA_A11Y = '#title-icons';
-/**
- * Liga a engine para um jogo declarado.
- *
- * ⚠️ LANÇA se a declaração for malformada, e NÃO lança se faltar marcação. A diferença não é gosto: uma
- * declaração errada é defeito de PROGRAMA, e um jogo que roda meio declarado é pior do que um que não abre;
- * um id ausente é lacuna do HOSPEDEIRO, e o quiz provou que ligar só a parte que serve é legítimo — foi
- * assim que ele recusou o pad e o sonar sem mentir. Por isso um vira exceção e o outro vira `problems`.
- */
 export function createGame(o) {
-    const problemasDoContrato = conformanceProblems(o.declaration);
+    /*
+     * O CARTUCHO CORRENTE, e por enquanto ele É as opções que chegaram.
+     *
+     * ⚠️ Este passo não muda comportamento nenhum: `cartucho` começa como o próprio `o`, então toda leitura
+     * abaixo devolve exatamente o que devolvia. O que ele compra é o LUGAR onde `mount()` vai escrever
+     * (ADR-0142) — sem ele, as trinta e seis leituras da metade do jogo estão presas ao argumento, e uma raiz
+     * de composição a servir vários cartuchos ficaria com o primeiro deles para sempre.
+     */
+    let cartucho = o;
+    const problemasDoContrato = conformanceProblems(cartucho.declaration);
     if (problemasDoContrato.length) {
-        throw new Error('createGame: declaração malformada — ' + problemasDoContrato.join('; '));
+        recusarDeclaracao('createGame', problemasDoContrato);
     }
     const { doc, win } = o.host;
-    const declines = o.declines ?? {};
-    const problems = [];
+    /*
+     * ⚠️ LEITOR E NÃO INSTANTÂNEO — terceira vez que este ficheiro comete e conserta o mesmo padrão, depois do
+     * `seguraTeclas` e do `players`. `declines` é da metade do JOGO (ADR-0139, errata de 2026-09-11: é o
+     * cartucho que declara o que NÃO tem), então um `const` tirado no arranque devolve, depois de um `mount()`,
+     * os declínios do cartucho anterior — e um declínio lido errado esconde uma linha de `problems` ou
+     * inventa outra.
+     *
+     * 📌 O vazio é uma constante e não um literal por chamada: `declines()` é lido em sítios que comparam.
+     */
+    const SEM_DECLINIOS = {};
+    const declines = () => cartucho.declines ?? SEM_DECLINIOS;
+    const problemasDoHospedeiro = [];
     const $ = (sel) => doc.querySelector(sel);
     const $$ = (sel) => [...doc.querySelectorAll(sel)];
     for (const sel of MARCACAO_EXIGIDA) {
         if (!$(sel))
-            problems.push(`marcação ausente: ${sel}`);
+            problemasDoHospedeiro.push(`marcação ausente: ${sel}`);
     }
     // ⚠️ O MUNDO DECLARADO TEM DE EXISTIR NO DOCUMENTO, e esta é a falha que o ADR-0087 deixaria aberta se
     // parasse na conformidade. `conformanceProblems` confere a FORMA — que há um seletor e que ele não está
@@ -117,9 +139,40 @@ export function createGame(o) {
     // que o registro existe para eliminar: a simulação de empatia aplicada a NADA, e um adulto informado de
     // que sentiu algo que não sentiu. É um problema do HOSPEDEIRO e não do programa, então entra em
     // `problems` como as marcações — o jogo abre, e quem o integrou lê que o mundo dele não está lá.
-    const mundo = o.declaration.world();
-    if (mundo.kind === 'element' && !$(mundo.selector)) {
-        problems.push(`mundo declarado não encontrado: ${mundo.selector}`);
+    /*
+     * AS TRÊS LINHAS DE `problems` QUE DEPENDEM DO CARTUCHO, juntas e recalculáveis.
+     *
+     * 📏 Medido: das oito que esta raiz produz, CINCO são sobre a PÁGINA — marcação ausente, sem host de
+     * filtros, sem barra de acessibilidade, uma barra que não aceita conteúdo, sem sítio para a pausa — e
+     * essas não mexem quando se troca de jogo, porque não é o jogo que as causa. Só estas três mexem.
+     *
+     * ⚠️ E é por isso que `problems` não podia continuar a ser UM array construído no arranque: metade dele
+     * descreve o hospedeiro e vale para sempre, a outra metade descreve um cartucho e caduca no `mount()`.
+     * Recalcular tudo apagaria diagnósticos do hospedeiro que ninguém consertou; não recalcular nada deixaria
+     * o diagnóstico a falar do jogo errado.
+     */
+    function problemasDoCartucho() {
+        const p = [];
+        // O mundo declarado tem de existir na página — e quem o declara é o jogo, não o hospedeiro.
+        const mundo = cartucho.declaration.world();
+        if (mundo.kind === 'element' && !$(mundo.selector)) {
+            p.push(`mundo declarado não encontrado: ${mundo.selector}`);
+        }
+        // ⚠️ MISTA, e fica deste lado por causa da segunda metade: a porta é do hospedeiro
+        // (`carregarVozNeural`), mas o declínio é do CARTUCHO — logo a linha pode aparecer ou calar-se ao
+        // trocar de jogo, com o mesmo hospedeiro.
+        if (!o.carregarVozNeural && !declines().semVozNeural) {
+            p.push('sem voz neural: declare `carregarVozNeural` (uma linha — ver ADR-0094) ou `declines.semVozNeural`. '
+                + 'Sem ela a criança que não lê fica com a voz do sistema, que em Chromebook de escola pode não existir '
+                + 'em português');
+        }
+        const assentos = (cartucho.players ?? []).length;
+        if (assentos > 1 && !declines().semAtorDePausa && !cartucho.setPauseActor) {
+            p.push(`declarou ${assentos} jogadores e não registra o ator da pausa: o painel de controle edita sempre o `
+                + 'assento 0, então ninguém além do primeiro consegue remapear. Declare `declines.semAtorDePausa` se '
+                + 'for de propósito');
+        }
+        return p;
     }
     // 1. IDIOMA ANTES DE TUDO. A interface não pode ser construída antes de a língua ser conhecida — foi o que
     //    o item 14 consertou movendo `initI18n()` para o topo do boot. O documento entra: ver o achado 15.
@@ -131,11 +184,7 @@ export function createGame(o) {
         getSoundOn: () => soundOn, getVolume: () => volume, getAudioCat: () => audioCat,
         carregarVozNeural: o.carregarVozNeural,
     });
-    if (!o.carregarVozNeural && !declines.semVozNeural) {
-        problems.push('sem voz neural: declare `carregarVozNeural` (uma linha — ver ADR-0094) ou `declines.semVozNeural`. '
-            + 'Sem ela a criança que não lê fica com a voz do sistema, que em Chromebook de escola pode não existir '
-            + 'em português');
-    }
+    // 📌 A linha da voz neural mudou-se para `problemasDoCartucho()`: o declínio que a cala é do jogo.
     /**
      * O FILTRO DE VISÃO, aplicado ao MUNDO QUE O JOGO DECLAROU (ADR-0087).
      *
@@ -149,7 +198,7 @@ export function createGame(o) {
      * filtro sobre ela seria a mentira que o ADR-0087 existe para impedir, só que ao contrário.
      */
     function aplicarFiltroDeVisao(css, alcance) {
-        const mundo = o.declaration.world();
+        const mundo = cartucho.declaration.world();
         if (mundo.kind !== 'element')
             return;
         const el = $(mundo.selector);
@@ -174,13 +223,13 @@ export function createGame(o) {
     // 4. Daltonismo: a engine ENTREGA o markup em vez de exigir que o consumidor o adivinhe (achado 7).
     const cvdFilters = installCvdFilters(o.host.cvdHost ?? null);
     if (!cvdFilters)
-        problems.push('sem host de filtros (<svg>): a correção de daltonismo não foi montada');
+        problemasDoHospedeiro.push('sem host de filtros (<svg>): a correção de daltonismo não foi montada');
     // 4c. A BARRA DE ACESSIBILIDADE DA PRIMEIRA TELA. Ver a nota em `EngineHost.a11yBarHost`: cinco dos seis
     //     jogos do catálogo não têm nenhuma, e nada o dizia. Isto não a monta — diz que ela falta, que é o
     //     passo que tira o silêncio. A frase nomeia a saída, como as outras deste bloco fazem.
     const a11yBar = o.host.a11yBarHost ?? $(SELETOR_BARRA_A11Y);
     if (!a11yBar) {
-        problems.push(`sem barra de acessibilidade na primeira tela: declare \`host.a11yBarHost\` ou ponha um ${SELETOR_BARRA_A11Y} no documento. Sem ela a criança não alcança modo cego, TTS, alto contraste nem Libras antes de começar`);
+        problemasDoHospedeiro.push(`sem barra de acessibilidade na primeira tela: declare \`host.a11yBarHost\` ou ponha um ${SELETOR_BARRA_A11Y} no documento. Sem ela a criança não alcança modo cego, TTS, alto contraste nem Libras antes de começar`);
     }
     /*
      * ⚠️ E AGORA A ENGINE MONTA-A (ADR-0106 §4, etapa 2). Até 2026-09-08 esta raiz só REPORTAVA a ausência, e o
@@ -213,7 +262,7 @@ export function createGame(o) {
      * respostas à mesma pergunta divergem, e foi assim que esta divergiu. `import * as state` dá ligação VIVA,
      * então isto lê o valor de agora e não o do arranque.
      */
-    const lerModoCego = o.isBlindMode ?? (() => state.modoCego);
+    const lerModoCego = cartucho.isBlindMode ?? (() => state.modoCego);
     const pauseIcons = initPauseIcons({
         doc,
         /*
@@ -227,9 +276,12 @@ export function createGame(o) {
          * a pé e nada dentro de um veículo declara `true`, e o registo não disse isto porque a pergunta só
          * aparece quando se monta a barra.
          */
-        seguraTeclas: o.declaration.seguraTeclas(),
-        getPlayers: () => o.players ?? [],
-        getNumPlayers: () => (o.players ?? [null]).length,
+        // ⚠️ A REFERÊNCIA, e não o resultado. Chamar aqui congelava a resposta no arranque, e o
+        // `reflectPauseIcons` — que existe porque a tabela de acções muda (ADR-0106 §5) — refrescava a partir
+        // dela. Com vários cartuchos numa raiz de composição (ADR-0142) o ícone descrevia o primeiro deles.
+        seguraTeclas: () => cartucho.declaration.seguraTeclas(),
+        getPlayers: () => cartucho.players ?? [],
+        getNumPlayers: () => (cartucho.players ?? [null]).length,
         srSay, srAlert,
         // ⚠️ NÃO `instanceof HTMLElement`: esse é um GLOBAL DO NAVEGADOR, e lê-lo onde ele não existe LANÇA —
         // não devolve falso. Escrito assim na etapa 2, fazia o `reflectPauseIcons` rebentar em qualquer ambiente
@@ -252,6 +304,14 @@ export function createGame(o) {
         reflectTtsPanelEnabled: false,
         isLibrasOn: vlibrasOpen,
         toggleLibras,
+        /*
+         * ⚠️ O QUE O JOGO ENTREGA, E QUE ATÉ HOJE NÃO TINHA POR ONDE. Os três campos são opcionais dos dois
+         * lados: ausentes, tudo se comporta como antes — tabela de acções vazia e os dois ícones visuais
+         * não montados. Ver as notas em `CreateGameOptions` para o que a ausência custava.
+         */
+        ...(cartucho.getPauseActs ? { getPauseActs: cartucho.getPauseActs } : {}),
+        ...(cartucho.setTemaDoJogador ? { setTemaDoJogador: cartucho.setTemaDoJogador } : {}),
+        ...(cartucho.setCorrecaoDoJogador ? { setCorrecaoDoJogador: cartucho.setCorrecaoDoJogador } : {}),
     });
     /*
      * ⚠️ O HOSPEDEIRO TEM DE SABER SER UMA BARRA, e perguntar isso não é zelo: `a11yBarHost` é `Element` no
@@ -265,7 +325,7 @@ export function createGame(o) {
         && typeof a11yBar.addEventListener === 'function'
         && 'innerHTML' in a11yBar;
     if (a11yBar && !barraUsavel) {
-        problems.push('o elemento da barra de acessibilidade não aceita conteúdo nem clique: os ícones não foram montados');
+        problemasDoHospedeiro.push('o elemento da barra de acessibilidade não aceita conteúdo nem clique: os ícones não foram montados');
     }
     if (a11yBar && barraUsavel) {
         a11yBar.innerHTML = iconsMarkup(pauseIcons.iconesMontados);
@@ -317,16 +377,11 @@ export function createGame(o) {
     // esquema, e não há selector de assento — o `#ctrl-players` é uma FRASE, não abas. Quem decide o assento é
     // o consumidor, passando o ator da pausa: «edita o controle de quem abriu o menu».
     //
-    // ⚠️ E É AQUI QUE ISTO FICA MUDO. O `setPauseActor` desta raiz é `() => {}` — literal, logo abaixo. Um jogo
-    // montado por `createGame` com dois assentos deixa a criança do SEGUNDO sem como remapear, e nada o diz.
-    // Não é a mesma coisa que declarar `semAtorDePausa`: essa é uma ausência declarada, e uma ausência
-    // declarada é uma escolha. Esta era uma ausência por omissão, que é a forma de defeito do ADR-0106 §2.
-    const assentos = (o.players ?? []).length;
-    if (assentos > 1 && !declines.semAtorDePausa) {
-        problems.push(`declarou ${assentos} jogadores e não registra o ator da pausa: o painel de controle edita sempre o `
-            + 'assento 0, então ninguém além do primeiro consegue remapear. Declare `declines.semAtorDePausa` se '
-            + 'for de propósito');
-    }
+    // ✅ E ISTO DEIXOU DE SER MUDO. O `setPauseActor` desta raiz era `() => {}` LITERAL, sem campo por onde um
+    // jogo o entregar: a linha abaixo dizia «conserte» sem haver por onde, e a única saída era declarar
+    // `semAtorDePausa`, que é aceitar a perda em vez de a corrigir. Agora ela só acusa quem NÃO respondeu —
+    // que é o que uma linha de `problems` deve fazer, pelo §2 do ADR-0106.
+    // 📌 A linha do ator da pausa mudou-se para `problemasDoCartucho()`: quem declara assentos é o jogo.
     /*
      * 4e. O CARTÃO DE PAUSA DA PRIMEIRA TELA — e isto fecha um LAÇO QUE ESTAVA ABERTO.
      *
@@ -343,7 +398,7 @@ export function createGame(o) {
     const hospedeiroDaPausa = o.host.pauseHost ?? $('#game-region');
     const pausaUsavel = !!hospedeiroDaPausa && typeof hospedeiroDaPausa.appendChild === 'function';
     if (!pausaUsavel) {
-        problems.push('sem sítio para o menu de pausa: declare `host.pauseHost` ou tenha um #game-region que aceite filhos. '
+        problemasDoHospedeiro.push('sem sítio para o menu de pausa: declare `host.pauseHost` ou tenha um #game-region que aceite filhos. '
             + 'Sem ele a criança não alcança os ajustes durante a partida — e NÃO há como declinar: desde o '
             + 'ADR-0122 a pausa é da engine em todo jogo, e o que este jogo declara é só ONDE ela cabe');
     }
@@ -356,13 +411,13 @@ export function createGame(o) {
     }
     // 4b. NAVEGAÇÃO SONORA. Só o contrato entra: nada de tile, caixa de colisão ou array de moedas.
     const sonar = createAudioSonar({
-        topology: () => o.declaration.topology(),
-        targetsOf: (i) => o.declaration.targetsOf(i),
-        nameAt: (at) => o.declaration.nameAt(at),
+        topology: () => cartucho.declaration.topology(),
+        targetsOf: (i) => cartucho.declaration.targetsOf(i),
+        nameAt: (at) => cartucho.declaration.nameAt(at),
         // Campo 2 + o barramento do mixer: o que o GUIA CONTÍNUO precisa e o bipe não precisava (#84 item 2). O
         // `roleAt` é o que deixa a rota contornar parede; o `catNode`/`audioOut`/`getVolume` são o que põem um
         // grafo PERMANENTE no mesmo cursor de volume que todo o resto do áudio usa.
-        roleAt: (at) => o.declaration.roleAt(at),
+        roleAt: (at) => cartucho.declaration.roleAt(at),
         tonePan, srSay, narrate: (texto) => tts.narrate(texto),
         catNode, audioOut, getVolume: () => volume,
         // ⚠️ A RESPOSTA, E NÃO A TABELA (#104). O `platform/audio-sonar` recebia o `VIZ_BY_KEY` e atravessava-o
@@ -375,11 +430,11 @@ export function createGame(o) {
         getModoCego: lerModoCego, LOGICAL_W,
         // O jogador DERIVADO do foco: campo 4 respondendo "onde a criança está". Um jogo que não fornece lista
         // ainda tem sonar, e é isso que faz a pilha de acessibilidade não ser acessório.
-        getPlayers: o.sonarPlayers ?? (() => {
-            const f = o.declaration.focusOf(0);
+        getPlayers: cartucho.sonarPlayers ?? (() => {
+            const f = cartucho.declaration.focusOf(0);
             return f ? [{ i: 0, x: f.at.x, y: f.at.y, visual: PADRAO }] : [];
         }),
-        getNumPlayers: () => (o.players ?? [null]).length,
+        getNumPlayers: () => (cartucho.players ?? [null]).length,
         getAudioCtx: () => audioCtx, getSoundOn: () => soundOn, getAudioCat: () => audioCat,
     });
     // 5. Teclado remapeável — o melhor recorte da base (achado 11): esquema de teclas, sem mundo.
@@ -389,24 +444,45 @@ export function createGame(o) {
     // primeiro arranque com a fábrica da ENGINE e o segundo com a do jogo — a pior espécie de defeito, porque
     // desaparece quando alguém vai ver.
     // 📌 E o registo aceita `null`, que é o que um jogo sem opinião produz: fica a fábrica da engine.
-    registrarMapeamentoDoTeclado(o.declaration.mapeamentoDoTeclado
-        ? (jogadores, assento) => o.declaration.mapeamentoDoTeclado(jogadores, assento)
-        : null);
-    // ⚠️ E O DO CONTROLE REGISTA-SE AQUI AINDA QUE ESTA RAIZ NÃO MONTE GAMEPAD NENHUM. Não é descuido: quem
-    // chama `initGamepad` é o cartucho, e é exactamente por isso que o registo não pode viver lá — seria mais
-    // um campo que um jogo pode esquecer, e esquecê-lo devolve o mapa da ENGINE a quem declarou outro, calado.
-    registrarMapeamentoDoPad(o.declaration.mapeamentoDoPad
-        ? (jogadores, assento) => o.declaration.mapeamentoDoPad(jogadores, assento)
-        : null);
+    /*
+     * OS DOIS REGISTOS NUMA FUNÇÃO, porque são EFEITO GLOBAL e não valor: quem os chama por último ganha.
+     *
+     * ⚠️ É o que os torna diferentes de tudo o mais nesta raiz. Repontar uma leitura para o `cartucho` chega
+     * para os campos que são lidos quando alguém pergunta; estes dois já foram escritos noutro sítio no
+     * momento do arranque, então trocar de cartucho sem os reescrever deixa o mapa do anterior a valer —
+     * calado, e exactamente no lugar onde uma criança que remapeou teclas iria notar primeiro.
+     *
+     * 📌 `null` é o valor honesto de «este jogo não tem opinião», e é também o que o `desmontar()` escreve.
+     */
+    function registrarMapeamentosDoCartucho() {
+        registrarMapeamentoDoTeclado(cartucho.declaration.mapeamentoDoTeclado
+            ? (jogadores, assento) => cartucho.declaration.mapeamentoDoTeclado(jogadores, assento)
+            : null);
+        // ⚠️ E O DO CONTROLE REGISTA-SE AQUI AINDA QUE ESTA RAIZ NÃO MONTE GAMEPAD NENHUM. Não é descuido: quem
+        // chama `initGamepad` é o cartucho, e é exactamente por isso que o registo não pode viver lá — seria mais
+        // um campo que um jogo pode esquecer, e esquecê-lo devolve o mapa da ENGINE a quem declarou outro, calado.
+        registrarMapeamentoDoPad(cartucho.declaration.mapeamentoDoPad
+            ? (jogadores, assento) => cartucho.declaration.mapeamentoDoPad(jogadores, assento)
+            : null);
+    }
+    registrarMapeamentosDoCartucho();
     initKB();
     // ⚠️ O ESQUEMA DE ARRANQUE ALCANÇA NADA, e diz isso com `null` em vez de com um objeto vazio (issue #118).
     // Ele vive um instante — `assignControls()` logo abaixo substitui-o pelo esquema real —, mas enquanto vive
     // é um `KeyScheme` como qualquer outro, e a única forma honesta de um esquema que não alcança nada é
     // catorze ausências declaradas. Um `{}` fazia o tipo mentir sobre estar completo.
     const semAlcance = Object.fromEntries(ACTIONS.map((a) => [a, null]));
-    const players = o.players ?? [{ ctrl: semAlcance }];
+    // ⚠️ O FALLBACK É UMA CONSTANTE e não um literal novo a cada chamada: `getPlayers` é lido pelo runtime de
+    // teclado a cada leitura de controlo, e devolver um array novo de cada vez faria qualquer comparação de
+    // identidade mentir — um defeito que só aparece em quem compara, e tarde.
+    const semJogadores = [{ ctrl: semAlcance }];
+    // ⚠️ LÊ `cartucho.players`, E NÃO UM INSTANTÂNEO. Os getters já existiam; o que eles fechavam é que era um `const`
+    // tirado no arranque. As linhas de `initPauseIcons` e do sonar, neste mesmo ficheiro, já liam a fonte viva —
+    // esta era a que faltava. Com vários cartuchos numa raiz de composição (ADR-0142), o teclado ficava com os
+    // jogadores do cartucho que arrancou primeiro.
+    const players = () => cartucho.players ?? semJogadores;
     const keyboard = initKeyboardRuntime({
-        getKB: () => kb, getNumPlayers: () => players.length, getPlayers: () => players,
+        getKB: () => kb, getNumPlayers: () => players().length, getPlayers: () => players(),
     });
     keyboard.assignControls();
     // 6. Navegação de menu. Os três declínios entram como AUSÊNCIA DECLARADA, não como getter que devolve null.
@@ -414,13 +490,13 @@ export function createGame(o) {
         $, getActiveElement: () => doc.activeElement,
         topVisibleOverlay: overlays.topVisibleOverlay, closeById: overlays.closeById,
         getPauseMenu: (i) => $(`#vp-pause-${i}`),
-        setPhase: o.setPhase ?? (() => { }),
-        setPauseActor: () => { },
+        setPhase: cartucho.setPhase ?? (() => { }),
+        setPauseActor: cartucho.setPauseActor ?? (() => { }),
         srSay,
         // Sem opinião declarada, o índice fica LIGADO: quem precisa dele para se orientar não tem como saber
         // que ele existe se vier desligado (a mesma razão de o modo cego nascer com TTS e sonar).
-        comIndice: o.comIndice ?? (() => true),
-        isNavigable: o.isNavigable ?? (() => true),
+        comIndice: cartucho.comIndice ?? (() => true),
+        isNavigable: cartucho.isNavigable ?? (() => true),
         /*
          * ⚠️ ESTE PADRÃO ERA `() => false` / `() => {}`, E DESDE HOJE ISSO SERIA UM BURACO QUE EU ABRI. O
          * comentário que estava aqui dizia «um hospedeiro que não tenha barra de acessibilidade responde nunca e
@@ -438,8 +514,8 @@ export function createGame(o) {
          * modo (ADR-0044 item 7). No cartucho ela chega por outra rota (o encaminhador do gamepad, `main.ts:1470`)
          * que esta raiz ainda não monta. Logo: o direcional navega a barra; sair por START, por enquanto, não.
          */
-        naBarraDe: o.naBarraDe ?? ((i) => pauseIcons.naBarraDe(i)),
-        navBar: o.navBar ?? ((i, k) => pauseIcons.navBar(i, k)),
+        naBarraDe: cartucho.naBarraDe ?? ((i) => pauseIcons.naBarraDe(i)),
+        navBar: cartucho.navBar ?? ((i, k) => pauseIcons.navBar(i, k)),
         isCapturing: () => false,
         closePadWiz: () => { },
         whichPlayer: (code) => keyboard.whichPlayer(code),
@@ -515,22 +591,50 @@ export function createGame(o) {
             return false;
         } },
     };
-    const acoesDoJogo = o.preset ? presetActions(o.preset) : [];
     // O segundo eixo entra aqui, e vem do jogo (ADR-0104 §A): quantas posições ele segura ao mesmo tempo.
     // ⚠️ O TERCEIRO EIXO ENTRA AQUI (ADR-0112), e vem do jogo tal como os outros dois. `?? false` e não um
     // padrão inventado: o campo é opcional de propósito — ver a nota nele —, e a ausência significa «este jogo
     // não desenha», que é a resposta certa para a esmagadora maioria dos trezentos.
-    const alcanceAqui = alcance(transportesPadrao(disponibilidade), acoesDoJogo, o.declaration.holdsAtOnce(), o.declaration.needsPointer?.() ?? false);
-    // ⚠️ SÓ APARECE QUANDO HÁ O QUE DIZER. Um aviso que aparece sempre deixa de ser lido, e um jogo cujas ações
-    // cabem no toque não tem nada a avisar — que é o caso comum e tem de continuar silencioso.
-    if (acoesDoJogo.length) {
-        mostrarAvisoDeAlcance({
-            procurar: (sel) => $(sel),
-            criar: (tag) => doc.createElement(tag),
-            t,
-            srAlert,
-        }, alcanceAqui);
+    /*
+     * O ALCANCE E O SEU AVISO, numa função, porque os dois dependem do cartucho e o segundo CRIA DOM.
+     *
+     * ⚠️ O aviso é o único sítio desta raiz que escreve um elemento a partir de uma resposta do jogo, e por
+     * isso é o único que precisa de ser RETIRADO antes de ser reescrito: `mostrarAvisoDeAlcance` cria um `div`
+     * com `id` fixo, então chamá-lo duas vezes deixaria dois — e o segundo cartucho ficaria com o aviso do
+     * primeiro por baixo do seu.
+     *
+     * 📌 `retirarAvisoDeAlcance()` corre SEMPRE antes, e não só quando há o que mostrar: um cartucho que não
+     * tem nada a avisar tem de apagar o aviso do anterior, e é esse o caso que se esquece.
+     */
+    function retirarAvisoDeAlcance() {
+        const aviso = $(`#${REACH_NOTICE_ID}`);
+        if (!aviso)
+            return;
+        // ⚠️ CAPACIDADE E NÃO TIPO, pela mesma razão que este ficheiro já escreve mais acima sobre o
+        // `instanceof HTMLElement`: o hospedeiro pode ser um documento falso, e os que estes testes usam têm
+        // `parentNode` mas não `remove`. Perguntar pelo método é o que funciona nos dois.
+        if (typeof aviso.remove === 'function')
+            aviso.remove();
+        else
+            aviso.parentNode?.removeChild(aviso);
+    }
+    function derivarAlcance() {
+        const acoes = cartucho.preset ? presetActions(cartucho.preset) : [];
+        const a = alcance(transportesPadrao(disponibilidade), acoes, cartucho.declaration.holdsAtOnce(), cartucho.declaration.needsPointer?.() ?? false);
+        retirarAvisoDeAlcance();
+        // ⚠️ SÓ APARECE QUANDO HÁ O QUE DIZER. Um aviso que aparece sempre deixa de ser lido, e um jogo cujas
+        // ações cabem no toque não tem nada a avisar — que é o caso comum e tem de continuar silencioso.
+        if (acoes.length) {
+            mostrarAvisoDeAlcance({
+                procurar: (sel) => $(sel),
+                criar: (tag) => doc.createElement(tag),
+                t,
+                srAlert,
+            }, a);
+        }
+        return a;
     }
+    let alcanceAtual = derivarAlcance();
     // O ANÚNCIO DE QUE O LAÇO PAROU (ADR-0054). Entregue e não instalado: quem chama `startLoop` é o JOGO, que
     // é o dono do ticker. Um jogo que monte o laço sem passar isto continua a PARAR — parar não é opcional; o
     // que ele perde é dizer que parou.
@@ -583,5 +687,57 @@ export function createGame(o) {
         void baixarPesados({ aoProgredir: o.aoProgredirPesados })
             .catch(() => { });
     }
-    return { declaration: o.declaration, pausa, tts, overlays, nav, keyboard, sonar, aplicarFiltroDeVisao, cenas: criarPilha(), cvdFilters, problems, declines, aoFalhar, alcance: alcanceAqui };
+    /*
+     * ⚠️ `declaration` E `declines` SÃO GETTERS; o resto não é, e a assimetria é a decisão.
+     *
+     * Os dois pertencem à metade do JOGO (ADR-0139 §1), logo têm de seguir o cartucho que estiver montado —
+     * um campo fixo aqui devolveria, depois de um `mount()`, a declaração do cartucho que arrancou primeiro.
+     * `pausa`, `tts`, `overlays`, `nav`, `keyboard` e o sonar são da PÁGINA e existem uma vez só, que é a
+     * decisão inteira do ADR-0117 §2 — e é por isso que eles ficam como estão.
+     *
+     * 📌 `problems` e `alcance` ainda são fixos, e ainda descrevem o arranque. É a dívida que o ADR-0142
+     * nomeia e que o `mount()` fecha.
+     */
+    /*
+     * A PILHA DE CENAS É DA RAIZ, e não do retorno, porque o `desmontar()` tem de a alcançar. Nasce uma vez
+     * (ADR-0117 §2: a página tem uma) e é esvaziada entre cartuchos, nunca substituída.
+     */
+    const cenasDaRaiz = criarPilha();
+    function montar(declaration, ganchos = {}) {
+        // ⚠️ LANÇA, NÃO DIAGNOSTICA — a mesma regra do arranque, e por isso a mesma frase. Uma declaração
+        // malformada é pré-condição: `problems` é para lacunas com que se consegue jogar, e isto não é uma.
+        const malformada = conformanceProblems(declaration);
+        if (malformada.length) {
+            recusarDeclaracao('mount', malformada);
+        }
+        cartucho = { ...ganchos, declaration };
+        registrarMapeamentosDoCartucho();
+        alcanceAtual = derivarAlcance();
+    }
+    function desmontar() {
+        registrarMapeamentoDoTeclado(null);
+        registrarMapeamentoDoPad(null);
+        retirarAvisoDeAlcance();
+        // ⚠️ `pop()` E NÃO UM `clear()`: cada `exit()` é a limpeza de DOM daquela cena, e saltá-la deixaria na
+        // página o que o cartucho anterior desenhou. O laço tem fim porque `pop()` devolve `null` na pilha vazia.
+        while (cenasDaRaiz.pop()) { /* o `exit()` de cada cena É o teardown dela */ }
+    }
+    return {
+        get declaration() { return cartucho.declaration; },
+        get declines() { return declines(); },
+        mount: montar,
+        unmount: desmontar,
+        pausa,
+        tts,
+        overlays,
+        nav,
+        keyboard,
+        sonar,
+        aplicarFiltroDeVisao,
+        cenas: cenasDaRaiz,
+        cvdFilters,
+        get problems() { return [...problemasDoHospedeiro, ...problemasDoCartucho()]; },
+        aoFalhar,
+        get alcance() { return alcanceAtual; },
+    };
 }

package/dist-pkg/ui/pause-icons.d.ts

@@ -195,8 +195,14 @@ export interface AccionaveisDoJogo {
      * controle fica DESABILITADO com o motivo, porque o aparelho EXIGE a alternância e ela não se pode
      * desligar. Aqui não há nada a travar, e um controle que explica por que não faz nada continua a ser um
      * controle que não faz nada.
+     *
+     * ⚠️ É FUNÇÃO E NÃO VALOR, e a razão é a mesma do ADR-0084: uma resposta lida uma vez envelhece em
+     * silêncio. Aqui envelhecia no pior sítio — o `reflectPauseIcons` existe justamente porque «a tabela de
+     * acções deste jogo pode ter mudado desde a montagem» (ADR-0106 §5), e refrescava a partir de um booleano
+     * congelado no arranque. Com um `createGame` a servir vários cartuchos (ADR-0142), o ícone descrevia o
+     * jogo que arrancou primeiro. O contrato nunca esteve errado: `GameDeclaration.seguraTeclas` já é função.
      */
-    readonly seguraTeclas: boolean;
+    readonly seguraTeclas: () => boolean;
 }
 /**
  * @deprecated O nome dizia «escritores VISUAIS» e a pergunta deixou de ser só visual quando o `seguraTeclas`
@@ -429,8 +435,11 @@ export interface PauseIconsCtx {
      * 📌 Quem passa pelo `createGame` não escreve isto: a raiz lê a declaração, que já é obrigatória. O campo
      * só é visível para um cartucho que chame `initPauseIcons` por fora — e é exactamente esse que não pode
      * ficar em silêncio.
+     *
+     * ⚠️ FUNÇÃO, não valor — ver a nota no campo homónimo de `EscritoresVisuais`. Um cartucho que monte isto
+     * por fora passa `() => this.declaration.seguraTeclas()` e não o resultado dela.
      */
-    seguraTeclas: boolean;
+    seguraTeclas: () => boolean;
 }
 export interface PauseIconsApi {
     /** Builds one `.screen-pause` (hidden), wired for click + hover/focus caption. Caller appends it. */

package/dist-pkg/ui/pause-icons.js

@@ -235,7 +235,7 @@ export function iconesQueAccionam(escritores) {
     // Um terceiro ramo, e não uma regra nova.
     return PAUSE_ICONS.filter((ic) => (ic.k === 'contrast' ? escritores.tema
         : ic.k === 'cvd' ? escritores.correcao
-            : ic.k === 'altmove' ? escritores.seguraTeclas
+            : ic.k === 'altmove' ? escritores.seguraTeclas()
                 : true));
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-inclusionist/engine",
-  "version": "8.0.0-rc.2",
+  "version": "9.0.0",
   "type": "module",
   "description": "Accessibility-first (WCAG 2.2 + GAG) engine for educational 2D pixel-art games, built with PixiJS. Screen reader, sonar, high contrast by role, colour-vision filters, remappable input as intent, i18n and offline PWA — the parts every game inherits (ADR-0035, ADR-0036).",
   "comment:exports": [