@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -1,353 +1,633 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import { type Alcance, type Disponibilidade } from '../input/transports.js';
+import { type Translate } from '../core/i18n.js';
+import { type LiveInput } from '../input/state.js';
+import { type FlashMeasurement } from '../platform/flash-sampler.js';
+import { type Reach, type Availability } from '../input/transports.js';
+import { type AccommodationAnswers } from '../core/accommodations.js';
 import { type ActionPreset } from '../core/actions.js';
 import type { KeyScheme } from '../core/entity.js';
+import { type HowToPlaySlide } from '../ui/help-panel.js';
+import { type SettingsStore } from '../core/state.js';
+import { type Interpreter } from '../ui/vlibras.js';
 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 { createTts } from '../platform/tts.js';
+import { type Reading } from '../platform/reading.js';
+import { type Audio } from '../platform/audio.js';
+import { type AudioSonar } from '../platform/audio-sonar.js';
+import { type Theme, type Correction } from '../render/viz-axes.js';
+import type { FilterReach } from '../render/port.js';
 import { type SettingsPanelApi } from '../ui/settings-panel.js';
+import { type VirtualCommand, type VirtualController } from '../input/virtual-controller.js';
+export type { VirtualCommand } from '../input/virtual-controller.js';
+import { type LqFilter } from '../render/lq-filter.js';
+import { type Crt } from '../render/crt.js';
+import { type HudNumber } from '../ui/hud-bands.js';
+import { type GameOption } from '../ui/game-options.js';
+import { type StorageLike } from '../platform/storage.js';
 import { type MenuNavApi } from '../ui/menu-nav.js';
 import type { NavKeys } from '../input/edges.js';
+import { type GamepadGameHooks } from '../input/gamepad.js';
 import { type KeyboardRuntime } from '../input/keyboard-runtime.js';
-import { type RelatorioPesado } from '../platform/pesados.js';
-/** O que o jogo empresta do documento. Tudo opcional menos `doc`/`win`: o que faltar vira `problems`. */
+import { type KeyboardConfigApi } from '../input/keyboard.js';
+import { type HeavyReport } from '../platform/heavy.js';
+/** What the game lends from the document. Everything optional but `doc`/`win`: what is missing becomes `problems`. */
 export interface EngineHost {
     readonly doc: Document;
     readonly win: Window;
-    /** Um `<svg>` vazio onde os seis filtros de daltonismo são montados em tempo de execução. */
+    /** An empty `<svg>` where the six colour-vision filters are mounted at run time. */
     readonly cvdHost?: SVGElement | Element | null;
     /**
-     * ONDE A BARRA DE ACESSIBILIDADE ENTRA, na PRIMEIRA tela do jogo.
+     * WHERE THE ACCESSIBILITY BAR GOES, on the game's FIRST screen.
      *
-     * ⚠️ PEDIDO DO DEV, 2026-09-07: «o menu de pausa, o design do menu de pausa e os ícones de acessibilidade
+     * ⚠️ THE DEV'S REQUEST, 2026-09-07: «o menu de pausa, o design do menu de pausa e os ícones de acessibilidade
      * que aparecem no jogo desde a primeira tela devem ser oferecidos pela ENGINE e não pela programação do
      * jogo. Todo jogo da engine inclusionist deve ter o mesmo menu de pausa e ícones de acessibilidade desde a
      * primeira.»
      *
-     * ⚠️ E A MEDIÇÃO DE 2026-09-08 MOSTROU QUE É UM ACHADO, e não uma arrumação: dos seis jogos do catálogo
-     * local, CINCO não têm barra de acessibilidade nenhuma — nem menu de pausa. `pixi-15-puzzle`, `game-chess`,
-     * `game-soccer`, `2048` e `whackwhack` não chamam `initPauseIcons` nem montam HUD, e o `createGame` nunca
-     * os montou por eles. O comentário do `ui/pause-icons` diz porquê sem o notar: «`initPauseIcons` é chamado
-     * pela raiz de composição de CADA jogo» — ou seja, cada jogo tinha de se lembrar, e cinco não se lembraram.
-     * A criança que depende do modo cego, do TTS ou do alto contraste abre esses cinco jogos e não tem por onde.
+     * Left to each game, the bar was missing from most of the catalogue: each game had to remember to call
+     * `initPauseIcons`, and a child who depends on blind mode, narration or high contrast opened those games with no way
+     * in. So the engine mounts it (ADR-0106 §4, step 2).
      *
-     * Ausente, a engine procura `#title-icons` — o id que o jogo de plataforma usa desde sempre — e, não o
-     * achando, diz-o em `problems`.
-     *
-     * ✅ E DESDE 2026-09-08 ELA TAMBÉM **MONTA** (etapa 2 do ADR-0106 §4). Este parágrafo dizia «dizer não é
-     * montar, e a montagem é o passo seguinte»; o passo seguinte aconteceu. O que a destravou foram as etapas
-     * 1 e 3: nenhuma delas era sobre montar, e sem as duas o `PauseIconsCtx` exigia sete coisas que esta raiz
-     * não sabe responder por um jogo que não conhece.
-     *
-     * ⚠️ Achando o hospedeiro, a barra é escrita e fiada aqui. Não achando, continua a ser `problems` — porque
-     * a engine pode oferecer os ícones, mas não pode adivinhar ONDE eles cabem no desenho de um jogo alheio.
+     * Absent, the engine looks for `#title-icons` — the id the platformer has always used. Found, the bar is written and
+     * wired here; not found, it is a line of `problems`: the engine can offer the icons, but it cannot guess WHERE they
+     * fit in the layout of a game it does not know.
      */
     readonly a11yBarHost?: Element | null;
     /**
-     * ONDE O CARTÃO DE PAUSA da primeira tela é pendurado. Ausente, a engine usa `#game-region`.
+     * WHERE THE PAUSE CARD of the first screen is hung. Absent, the engine uses `#game-region`.
      *
-     * ⚠️ Existe pela mesma razão do `a11yBarHost`: a engine pode OFERECER a pausa, mas não sabe onde ela cabe
-     * no desenho de um jogo alheio. 📌 E desde o ADR-0120 ONDE já não é SE: a pausa deixou de ser declinável, e
-     * o que sobra deste campo é o lugar. Um hospedeiro que não aceite filhos vira linha de `problems`, que é a
-     * diferença entre a engine não saber e a engine calar-se.
+     * ⚠️ For the same reason as `a11yBarHost`: the engine OFFERS the pause, but does not know where it fits in the
+     * layout of a game it does not know. 📌 And since ADR-0120/ADR-0122 WHERE is not WHETHER: the pause is not
+     * declinable, and what this field keeps is the place. A host that takes no children becomes a line of `problems` —
+     * the difference between the engine not knowing and the engine keeping quiet.
      */
     readonly pauseHost?: Element | null;
+    /**
+     * WHERE THE VIRTUAL CONTROLLER IS HUNG (ADR-0143). Absent, the engine uses `#game-region`.
+     *
+     * ⚠️ For the same reason as `pauseHost`: the engine draws the pad from the `preset`, but does not know where it fits
+     * in the layout of a game it does not know. And the stylesheet puts `.touch` at `position:absolute` at the bottom of
+     * the host — so the host is the game's rectangle, not the page.
+     */
+    readonly touchHost?: Element | null;
+    /**
+     * WHERE THE CHILD'S SETTINGS ARE KEPT (ADR-0232, issue #207). The root builds the page's one store from it and hands that
+     * store to every module that persists.
+     *
+     * 📌 OPTIONAL, against ADR-0224/ADR-0227's preference for required ports, because here absence has a SAFE answer rather
+     * than a silent one: the host window's `localStorage`, which is what «this browser remembers the child's choices» means.
+     * A host passes one to keep a root's settings apart from everything else on the origin — a test file its own
+     * `memoryBackend()`, so no file inherits or races another's keys; a page with two roots one each (ADR-0142).
+     */
+    readonly storage?: StorageLike;
+    /**
+     * WHO SIGNS IN DEAF MODE (ADR-0234): the Libras player behind the `Interpreter` port, handed the text the sonar reads. Absent:
+     * the free player the delivery shipped (`ui/libras-avatar-player`, `inclusionist-heavy --libras`); and where it shipped none,
+     * the answer `NO_INTERPRETER` gives — «signing unavailable», a line of `problems` and a notice to the child, with the captions
+     * and the text intact. A host's own interpreter always wins; a test hands its double here.
+     */
+    readonly interpreter?: Interpreter;
 }
 /**
- * O que este jogo NÃO tem. Declarado, e não deduzido de um getter que devolve null.
+ * What this game does NOT have. Declared, not deduced from a getter that returns null.
  *
- * O achado 10 do segundo consumidor é a razão de isto existir como tipo: o quiz precisava se declarar
- * "pausado" para navegar os próprios menus, porque a engine não tinha por onde ouvir "eu não tenho fases".
+ * Finding 10 of the second consumer is why this exists as a type: the quiz had to declare itself paused to navigate its
+ * own menus, because the engine had no way to hear that a game has no phases.
  */
 export interface Declinios {
-    /** Sem assistente de mapeamento de controle. */
-    readonly semAssistenteDePad?: boolean;
-    /** Sem "ator da pausa" — quem apertou o botão que abriu o menu. */
-    readonly semAtorDePausa?: boolean;
+    /** No pause actor — who pressed the button that opened the menu. */
+    readonly noPauseActor?: boolean;
     /**
-     * Sem voz neural — este jogo não abre a porta do ADR-0094.
-     *
-     * ⚠️ EXISTE PORQUE A AUSÊNCIA ESTAVA A SER SILENCIOSA, e a medição de 2026-09-08 diz quanto: dos SEIS jogos
-     * do catálogo local, TRÊS declaram `carregarVozNeural` (platformer, 15-puzzle, 2048) e TRÊS não
-     * (`game-soccer`, `whackwhack`, `game-chess`). Nos três últimos não há voz neural nenhuma, e nada o dizia.
+     * No neural voice — this game does not declare `uses: { neuralVoice: true }` (ADR-0216 §3).
      *
-     * ⚠️ E ISSO CONTRADIZ UMA PROMESSA ESCRITA. O ADR-0065 §3 diz que as vozes «fazem parte da engine, e não do
-     * jogo em si» e que um cartucho «não tem de saber que existe»; o ADR-0094 — com razão, e por 135 MB de WASM
-     * — passou a exigir UMA LINHA do jogo. As duas coisas podem ser verdade ao mesmo tempo (a engine é dona das
-     * VOZES, o jogo nomeia o FORNECEDOR), mas só se quem esquece a linha for avisado. Declinar é escolha; não
-     * declarar era omissão.
+     * Exists because the absence is otherwise silent: a game that does not ask for one has only the browser's voice, which a school
+     * Chromebook may not have for the child's language. Declining is a choice; not declaring is an omission, and `problems` says so.
      */
-    readonly semVozNeural?: boolean;
+    readonly noNeuralVoice?: boolean;
 }
 export interface CreateGameOptions {
-    /** Os SETE CAMPOS (core/contract). É o que a pilha de acessibilidade lê, e a única coisa que ela lê. */
+    /** The SEVEN FIELDS (core/contract). It is what the accessibility stack reads, and the only thing it reads. */
     readonly declaration: GameDeclaration;
     readonly host: EngineHost;
     readonly declines?: Declinios;
     /**
-     * É AGORA hora de navegar menu? A plataforma responde `phase === 'paused'`; um quiz responde `true`.
-     * Ausente = `true`, que é o caso do jogo sem fases — o mais simples, e o que não obriga a inventar uma.
+     * Is it menu-navigation time NOW? The platformer answers `phase === 'paused'`; a quiz answers `true`.
+     * Absent = `true`, the case of a game with no phases — the simplest one, and the one that does not force one to be invented.
      */
     readonly isNavigable?: () => boolean;
+    /** Is the position index (item N of M) on? Absent = yes. See `withIndex` in ui/menu-nav. */
+    readonly withIndex?: () => boolean;
     /**
-     * O MODO `accessibility` do ADR-0044 (item 7): o direcional dirige a barra rápida em vez do personagem.
+     * ADR-0044's `accessibility` MODE (item 7): the directional drives the quick bar instead of the character.
      *
-     * Opcionais porque um hospedeiro pode não ter barra nenhuma — sem eles a resposta é "ninguém está nela" e
-     * nada é chamado. O jogo de plataforma os fornece; um quiz sem HUD de a11y, não.
+     * Optional: absent, the engine answers with the bar it mounted itself (`ui/pause-icons`). A game that draws its own
+     * bar answers for it.
      */
-    /** O índice "N de M" está ligado? Ausente = sim. Ver `comIndice` em ui/menu-nav. */
-    readonly comIndice?: () => boolean;
-    readonly naBarraDe?: (i: number) => boolean;
+    readonly onBar?: (i: number) => boolean;
     readonly navBar?: (i: number, k: NavKeys) => void;
-    /** Jogadores para o teclado remapeável. `Pick<ControlledPlayer,'ctrl'>` — esquema de teclas e nada mais.
-     *  ⚠️ `KeyScheme` e não `Record<string, string[]>` desde a #118: era uma CÓPIA ESTRUTURAL do tipo, e uma
-     *  cópia que ninguém obriga a concordar diverge — é a lição que o próprio `core/entity` abre a dizer, com
-     *  o `DomQuery` (dezasseis cópias) e o `KeyScheme` (seis) como as contas já pagas. */
+    /**
+     * Players for the remappable keyboard. `Pick<ControlledPlayer,'ctrl'>` — a key scheme and nothing more.
+     * ⚠️ `KeyScheme` and not `Record<string, string[]>` (#118): a structural COPY of a type that nothing forces to agree
+     * drifts — the lesson `core/entity` opens with.
+     *
+     * ⚠️ `audioSink` is ADDITIVE AND OPTIONAL: no consumer needs to write it.
+     *
+     * 🎯 It is here because the seat has a second reader inside the engine. The hearing panel, which the engine mounts,
+     * writes into it the audio output the child chose — and `ui/pause-icons` reads it to answer a question that changes
+     * what the bar offers: does this child have an output of HER OWN? Without it, changing sound, narration or blind
+     * mode on a shared headset would change everyone's audio.
+     *
+     * 📌 AND ONLY THIS FIELD. The MOTOR fields (`easy`, `toggleMove`, `toggleRun`) are left out: they are required in
+     * `MobilityPlayer` — the panel READS them to draw its state — and making them required here would force every game
+     * to carry them. That is a contract decision still to be taken, and it is not taken in passing by a cast that would
+     * silence the compiler.
+     */
     readonly players?: {
         ctrl: KeyScheme;
+        audioSink?: string | null;
     }[];
-    /** Troca de fase, para quem tem fases. Ausente = não faz nada (o jogo sem fases não perde nada). */
+    /** Phase change, for a game that has phases. Absent = does nothing (a game without phases loses nothing). */
     readonly setPhase?: (p: 'title' | 'playing' | 'paused') => void;
+    /** Blind mode on? Absent = the engine's own stored value (`core/state.blindMode`). Applies to every player. */
+    readonly isBlindMode?: () => boolean;
     /**
-     * Os jogadores como a NAVEGAÇÃO SONORA os vê. Ausente, `createGame` DERIVA um do campo 4 do contrato: o
-     * foco diz onde o jogador está, que é tudo o que o sonar precisa saber sobre posição.
+     * THIS GAME'S POSITIONS AND THE KEYS OF THEIR WORDS (`core/actions`). Without them the engine does not know HOW MANY
+     * actions to ask of a transport, and ADR-0079 §3's guarantee cannot be measured (issue #112).
+     *
+     * 🔴 KEYS of `dictionaries`, never words (ADR-0232 D3, erratum of 2026-09-25): the root's translator resolves them each
+     * time the engine draws or speaks them, so a language change reaches the help, the remap screen, the pad and the scan.
+     * A key the dictionaries lack leaves its position unnamed and is a line of `problems`.
      *
-     * Um jogo com vários jogadores, ou com dispositivo de áudio por jogador, fornece a sua lista. Um jogo de
-     * uma criança só não fornece nada — e ganha sonar assim mesmo, que é o ponto.
+     * Optional because a game may not declare a preset yet; without it the reach notice simply does not appear, and the
+     * help and the scan have no words to show.
      */
-    readonly sonarPlayers?: () => SonarPlayer[];
-    /** Modo cego ligado? Ausente = não. Vale para todos os jogadores, como no jogo de plataforma. */
-    readonly isBlindMode?: () => boolean;
+    readonly preset?: ActionPreset;
+    /**
+     * THE ON-SCREEN PAD, only when the cartridge asks for it (ADR-0166): «Controle de tela é só para jogo que não funciona tão
+     * bem como via mouse e/ou touch (o cartucho decide), nunca para menu.» Absent = no pad — a game played by touching its
+     * own elements, and every menu, need none on top of them. It leaves the pause card and the panels; it stays on the quick
+     * pause.
+     */
+    readonly onScreenPad?: boolean;
+    /**
+     * THE NUMBERS THIS GAME SHOWS, each in the band of what it is about (ADR-0168, ADR-0175; issue #162). The engine mounts
+     * the HUD and places them: `identity` top left and `mission` under it, `power` top right (under the clock), `learning` bars (one to three, as
+     * `educational/segment-bar.barOf` returns them) centred in the footer, under the explanation; the room the game leaves free at the
+     * top (`--barra-a11y-h`) grows by what they take. Absent = no HUD mounted, and the game keeps drawing its own.
+     * 📏 Measured on 2026-09-13: six sibling games, six HUDs of their own, none in the bands.
+     * A malformed list is refused at boot and at `mount`, like the declaration.
+     */
+    readonly hud?: readonly HudNumber[];
     /**
-     * AS PALAVRAS DESTE JOGO (`core/actions`). Sem elas a engine não sabe QUANTAS ações pedir a um transporte,
-     * e a garantia do ADR-0079 §3 não tem como ser medida — foi a lacuna que a issue #112 encontrou: a
-     * aritmética existia, testada, e o `createGame` tinha ZERO ocorrências de qualquer coisa sobre ações.
+     * THE OPTIONS OF THIS GAME, as rows the engine draws (ADR-0182; issue #178): the keys of a label and hint in the game's
+     * dictionary (resolved at every drawing, ADR-0232 D3), a kind (steps, list or switch), how to read the value and how to write it. «Opções do jogo» opens them in a panel of the
+     * engine's own; absent or empty, the door stays on the card locked with its reason (ADR-0161). A cartridge draws its own
+     * options only where rows cannot express what it needs. A malformed list is refused at boot and at `mount`.
+     */
+    readonly gameOptions?: readonly GameOption[];
+    /**
+     * HOW TO PLAY THIS GAME, as slides the help shows before the buttons (ADR-0195; issue #188): «O "Como jogar" é justamente algo a
+     * ser feito pelo cartucho.» Each slide's text is a KEY of `dictionaries`, resolved at every showing in the page's language
+     * (ADR-0232 D3); its figure, when given, is drawn
+     * by the cartridge on a surface the engine gives, with the time for an animation (still under reduced motion). Absent = the help
+     * shows the buttons alone. A malformed list is refused at boot and at `mount`.
+     */
+    readonly howToPlay?: readonly HowToPlaySlide[];
+    /**
+     * THIS GAME'S DICTIONARIES, one per language (`pt`, `en`, `es`), registered into THIS ROOT's translator before anything is
+     * translated (ADR-0232 D3 erratum): a key resolves for this game and for no other root on the page. A string with markup is
+     * refused and named in the console; a key given in one language and not another is a line of `problems`.
+     *
+     * 🔴 THE ONE PLACE A GAME'S WORDS LIVE (ADR-0232 D3, erratum of 2026-09-25): every word the game DECLARES — `preset`,
+     * `accommodations`, `gameOptions`, `howToPlay`, `hud` — is a key of these, and a declared key they lack is a line of
+     * `problems` and is never shown. A cartridge `mount()` swaps in may bring its own; they are added to these.
+     * Decision (mechanical, ADR-0232 D3): an option and not a method on the handle, because the markup is translated at boot.
+     */
+    readonly dictionaries?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /**
+     * THE VIRTUAL CONTROLLER'S COMMANDS, CARRIED TO THE GAME (ADR-0111 and its erratum; issue #197): «a engine lida com o hardware e passa
+     * para o jogo o nome virtual do botão». Each press and release of a position the child's hardware reached — the keyboard by the
+     * child's scheme, the eyes — with its source and seat. What it executes is the game's, named by its `preset`. Not called while a menu
+     * has the directional. Absent = the game hears commands only through what it reads itself.
+     */
+    readonly onCommand?: (command: VirtualCommand) => void;
+    /**
+    /**
+     * WHAT ONLY THIS GAME KNOWS ABOUT THE GAMEPAD (ADR-0224). The engine mounts the transport; these are the few answers
+     * nothing in it can know — the title screen, the attract demo, the modal, joining and respawning a seat, the waiting
+     * badge, the wizard's art, and whether the world is running.
      *
-     * Opcional porque um jogo pode não declarar preset ainda; sem ele o aviso de alcance simplesmente não
-     * aparece, que é o comportamento de hoje e não uma regressão.
+     * 🎯 **Absent altogether is an answer**, not an oversight: the gamepad works, and what depends on the cartridge's
+     * world simply does not happen. Each absence is written in `GamepadGameHooks`.
      */
-    readonly preset?: ActionPreset;
+    readonly gamepad?: GamepadGameHooks;
     /**
-     * COMO SE CARREGA A VOZ NEURAL — uma linha do lado do jogo (ADR-0094):
+     * THE ACCOMMODATIONS THAT HAVE A SUBJECT IN THIS GAME — the cartridge's answer, REQUIRED (ADR-0153).
      *
-     *     carregarVozNeural: () => import('@mintplex-labs/piper-tts-web')
+     * 🔴 For each of the sixteen only the game can answer (`GAME_KEYED` in `core/accommodations`): the KEYS of the game's
+     * word in `dictionaries` (ADR-0232 D3), if it has a subject here, or `false`. In the Dev's words: «Gênero não precisa responder todas as acomodações, mas
+     * sim o cartucho, obrigatoriamente.»
      *
-     * ⚠️ AUSENTE POR OMISSÃO, E ISSO É A DECISÃO E NÃO UM DESCUIDO. A engine não pode nomear o fornecedor:
-     * ele traz `onnxruntime-web` como peer NÃO-opcional, que o npm instala sozinho — **135,4 MB** no
-     * `node_modules` de todo consumidor, incluindo um jogo que nunca fale por voz neural. E declará-lo em
-     * `devDependencies`, que era o estado até 06/09, publicou uma engine que NÃO COMPILAVA para ninguém
-     * (ADR-0093). A porta é a única forma que resolve as duas coisas ao mesmo tempo.
+     * ⚠️ REQUIRED, by the `holdsAtOnce` rubric: there is no safe default — yes mounts the wheelchair in chess, no
+     * hides it from the platformer — and forgetting fails INVISIBLY to whoever writes the game. A missing or incomplete
+     * answer is a malformed declaration, and the boot REFUSES.
      *
-     * Sem ela a narração cai na voz do navegador (Web Speech), que fala o idioma certo e não pesa nada — e o
-     * painel de áudio deixa de OFERECER o motor neural, em vez de o oferecer e nunca o carregar.
+     * 📌 The general ones always mount and the contract's are derived; none of them is answered here.
+     */
+    readonly accommodations: AccommodationAnswers;
+    /**
+     * The game's genre, OPTIONAL (ADR-0153), from the engine's list (`core/genres`, ADR-0156): what the game plays like.
+     * The cartridge chooses it and nobody assigns it. Casino game and a name outside the list refuse the boot; Horror game
+     * boots and `problems` carries its «avoid» mark.
      */
-    readonly carregarVozNeural?: CarregarVozNeural;
+    readonly genre?: string;
     /**
-     * BAIXAR AS COISAS PESADAS NO PRIMEIRO CARREGAMENTO? Padrão **sim** (ADR-0110 (b), ADR-0116, ADR-0119).
+     * WHAT THIS GAME USES OF THE VOICE (ADR-0216 §3) — never how. Two answers, and each one is a sentence about the child, not
+     * about a library:
+     *
+     * · `neuralVoice: true` — a child who cannot read is read TO by this game, so it wants a voice even where the device has
+     *   none of its own. The engine loads Kokoro from the delivery at the first such utterance (ADR-0216 §1); the game names no
+     *   phonemizer, runtime or model. Absent, no Kokoro voice is listed, the audio panel does not offer the neural engine, and
+     *   the 371 MiB of model, voices and runtime never enter the delivery.
+     * · `reading: true` — a child reads aloud TO this game and it wants the text; the engine decides who hears her, and a
+     *   delivery carries the reading models of pt, en and es because of this answer (each device keeps the three, her
+     *   language's first: she can switch at any moment). Absent, `motor.reading.listen()` refuses and
+     *   says which line is missing: a game that asks for a microphone it never declared would also be a delivery without the
+     *   model, which is a silence in a school nobody can debug.
+     * · `fonts: ['Lato', 'Press Start 2P']` — the font LIBRARY's families this game draws with (ADR-0255). The engine packages only
+     *   its own faces (the typography button's and the mathematics face); every other family is delivered in `heavy/` when the
+     *   delivery is built with `inclusionist-heavy <folder> --fonts …`. The engine writes their `@font-face` rules and keeps each
+     *   file in the checked cache for the days without a network; a family the library does not hold, or the delivery did not
+     *   carry, is a line of `problems`. The engine's own faces need no declaration.
+     */
+    readonly uses?: {
+        readonly reading?: boolean;
+        readonly neuralVoice?: boolean;
+        readonly fonts?: readonly string[];
+    };
+    /**
+     * FETCH THE HEAVY FILES ON THE FIRST LOAD? Default **yes** (ADR-0110 (b), ADR-0116, ADR-0119).
      *
-     * As quatro vozes neurais são ~241 MB e descem em SEGUNDO PLANO, uma de cada vez, sem bloquear o jogo: a
-     * criança joga enquanto elas chegam, e o que não pode acontecer é ela voltar no segundo dia, sem rede, e
-     * descobrir que a voz nunca foi buscada. O pilar 8 é «primeiro dia ONLINE, depois offline-first», e o
-     * ADR-0116 tirou a contradição que travava isto — instalar já é um acto de rede.
+     * The vision runtime and models, and with `uses.neuralVoice` Kokoro's model, voices and runtime (371 MiB), come down in the
+     * BACKGROUND, one at a time, without blocking the game: the child plays while they arrive, and what must not happen is a child
+     * back on the second day, offline, finding they were never fetched. Pillar 8 is «first day ONLINE, then offline-first», and
+     * ADR-0116 removed the contradiction that blocked this — installing is already a network act.
      *
-     * ⚠️ PÔR `false` É PARA QUEM TEM RAZÃO PARA O FAZER, e a razão que já existe é um TESTE: um caso que monte
-     * o arranque num navegador de verdade não pode disparar 241 MB contra o Hugging Face. Um jogo em produção
-     * que o desligue está a decidir que a criança dele fica sem voz neural offline.
+     * ⚠️ `false` IS FOR WHOEVER HAS A REASON, and the reason that exists is a TEST: a case that mounts the start in a real browser
+     * cannot fire hundreds of MB at the network. A game in production that turns it off decides its child has no neural voice offline.
      *
-     * 📌 E o ADR-0117 diz que quem devia pagar isto uma vez é a PLATAFORMA, não cada cartucho — a Cache Storage
-     * é particionada por origem, e num site só os 241 MB descem uma vez para todos os jogos. Enquanto a
-     * plataforma não os pede, é o jogo que os pede: melhor descer duas vezes do que nunca.
+     * 📌 ADR-0117 says the one who should pay this once is the PLATFORM, not each cartridge — the Cache Storage is partitioned by
+     * origin, and on one site the heavy files come down once for every game. Until the platform asks for them, the game does: better
+     * twice than never.
      */
-    readonly baixarPesados?: boolean;
+    readonly downloadHeavy?: boolean;
     /**
-     * O QUE ACONTECEU COM CADA COISA PESADA, à medida que acontece. Ausente = ninguém está a ver.
+     * WHAT HAPPENED TO EACH HEAVY FILE, as it happens. Absent = nobody is watching.
      *
-     * ⚠️ É AQUI E NÃO EM `problems` porque a descarga é de FUNDO: `problems` é devolvido sincronamente pelo
-     * `createGame`, e uma linha que chegue depois disso entra num vector que o leitor já leu. O ADR-0110 pede
-     * que uma busca falhada seja REPORTADA — reportar é ter um canal que existe quando a notícia chega, e não
-     * empurrar para uma lista que já foi entregue.
+     * ⚠️ HERE AND NOT IN `problems`, because the download runs in the BACKGROUND: `createGame` returns `problems` synchronously, and a
+     * line arriving later lands in an array its reader already read. ADR-0110 asks that a failed fetch be REPORTED — reporting is having
+     * a channel that exists when the news arrives, not pushing into a list already delivered.
      *
-     * 📌 A engine não inventa superfície nenhuma com isto: quem sabe onde cabe «faltam 241 MB» na tela de um
-     * jogo é o jogo. `pesoPorBaixar(relatorio)` dá o número para a frase.
+     * 📌 The engine invents no surface for this: where «N MB left» fits on a game's screen is the game's to know.
+     * `bytesLeftToDownload(relatorio)` gives the number for the sentence.
      */
-    readonly aoProgredirPesados?: (r: RelatorioPesado) => void;
+    readonly onHeavyProgress?: (r: HeavyReport) => void;
     /**
-     * Como se descobre que cada transporte está aqui. Ausente = a engine pergunta ao aparelho.
+     * How each transport is found to be here. Absent = the engine asks the device.
      *
-     * Injetável porque «há um controle ligado?» e «isto é uma tela de toque?» são perguntas ao navegador, e um
-     * teste que não as possa responder não consegue exercitar a tela que depende delas.
+     * Injectable because whether a gamepad is connected and whether this is a touch screen are questions to the browser, and a
+     * test that cannot answer them cannot exercise the screen that depends on them.
      */
-    readonly disponibilidade?: Disponibilidade;
+    readonly availability?: Availability;
     /**
-     * O QUE CADA ITEM DO CARTÃO DE PAUSA FAZ NESTE JOGO — «continuar», «sair», «ajuda», o que o jogo ligar.
+     * WHAT EACH ITEM OF THE PAUSE CARD DOES IN THIS GAME — «continuar», «sair», «ajuda», whatever the game wires.
      *
-     * 🔴 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.
+     * 🔴 The engine hides every item nothing acts on (ADR-0106 §5, no dead buttons — `refreshPauseItems` in
+     * `ui/pause-icons`), so without this field a game could wire no item beyond the ones the engine acts on itself
+     * (`ENGINE_ITEMS` and the engine's own actions below). The game's table is spread over the engine's, so the game wins.
      *
-     * ⚠️ 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.
+     * 📌 A FUNCTION and not a value, for the reason `ui/pause-icons` records: a game's table changes during a match (a
+     * «sair» that is wired only after the first level), and freezing it at boot broke a case there. Absent = only what
+     * the engine acts on.
      */
     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.
+     * WHO OPENED THE PAUSE, when there is more than one seat — the keyboard panel edits the seat of THIS index.
      *
-     * ⚠️ 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.
+     * ⚠️ Without it the child in the SECOND seat cannot remap, and `problems` says so for a game that declares more than
+     * one player and does not answer this (`core/cartridge-problems`).
      */
-    readonly setPauseActor?: (i: number, ...resto: unknown[]) => void;
+    readonly setPauseActor?: (i: number, ...rest: unknown[]) => void;
     /**
-     * COMO ESTE JOGO REPINTA PARA ALTO CONTRASTE, e como corrige daltonismo — os dois eixos do ADR-0104.
+     * HOW THIS GAME REPAINTS FOR HIGH CONTRAST, and how it corrects colour vision — the two axes of 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.
+     * 🔴 THE ⚫ ICON IS OFFERED ONLY TO A GAME THAT HANDS IN A WRITER. `iconsThatAct` mounts an icon only for whoever
+     * hands in its writer, and that rule is right — an icon that acts on nothing is worse than one icon fewer. What
+     * these fields add is the DOOR: without it, an outside consumer read the absence as this game having its own
+     * controls, true about the result and false about the cause. A gap the consumer reads as a choice is the worst kind.
+     * The 🚥 has an engine default (a filter over the world, below); a game that corrects colour in its own render wins.
      *
-     * ⚠️ 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.
+     * ⚠️ TWO FIELDS AND NOT ONE, because they are two questions: a game may know how to repaint textures and have no way
+     * to correct colour, or the other way round — `game-pinball`'s image is a 320×180 framebuffer with no texture to
+     * repaint, and it applies the colour filter itself.
      */
-    readonly setTemaDoJogador?: (i: number, tema: Tema) => void;
-    readonly setCorrecaoDoJogador?: (i: number, correcao: Correcao) => void;
+    readonly setPlayerTheme?: (i: number, theme: Theme) => void;
+    readonly setPlayerCorrection?: (i: number, correction: Correction) => void;
 }
 export interface Engine {
     readonly declaration: GameDeclaration;
     /**
-     * A PAUSA QUE ESTA RAIZ MONTOU — mostrar e esconder, sem o consumidor caçar id nenhum.
-     *
-     * ⚠️ EXISTE PORQUE MONTAR NÃO É MOSTRAR, e a etapa 2 do ADR-0106 tinha ficado a meio sem que nada o
-     * dissesse. O cartão nasce `hidden` (é assim que o `buildScreenPause` o entrega, e tem de ser: a pausa
-     * abre-se, não está aberta) e QUEM O REVELA é o `ui/shell`, por fase — que esta raiz **não monta**, de
-     * propósito: «não substitui o boot do main.js, que tem catorze anos de ordem própria».
+     * THE PAUSE THIS ROOT MOUNTED — show and hide, without the consumer hunting for any id.
      *
-     * ⚠️ Sem estas duas, um jogo montado por `createGame` ficava com um cartão de pausa que NADA mostrava. Não
-     * é «o consumidor esqueceu-se»: não havia por onde, a não ser procurar `#vp-pause-0` no documento — que é
-     * exactamente o tipo de conhecimento que este ficheiro existe para não exigir.
+     * ⚠️ IT EXISTS BECAUSE MOUNTING IS NOT SHOWING. The card is born `hidden` (that is how `buildScreenPause` delivers
+     * it, and it must be: a pause is opened, not open). The engine opens it on SELECT, the ☰ and the quick pause's
+     * `action4`; these two let a game open and close it too, without looking for `#vp-pause-0` in the document — exactly
+     * the kind of knowledge this file exists not to demand.
      *
-     * 📌 A engine OFERECE o mecanismo e não toma a fase. Quando abrir a pausa continua a ser do jogo, porque só
-     * ele sabe o que é estar a jogar; o que deixa de ser dele é saber COMO.
+     * 📌 The engine OFFERS the mechanism and does not take the phase. When to open the pause stays the game's, because
+     * only it knows what playing is; what stops being its business is HOW.
      */
-    readonly pausa: {
-        /** Revela o cartão da tela `i` e refaz os itens — o §5 avaliado no instante em que ela abre. */
-        readonly mostrar: (i: number) => void;
-        /** Esconde-o outra vez. */
-        readonly esconder: (i: number) => void;
+    readonly pause: {
+        /** Reveals screen `i`'s card and rebuilds its items — ADR-0106 §5 evaluated the moment it opens. */
+        readonly show: (i: number) => void;
+        /** Hides it again. */
+        readonly hide: (i: number) => void;
     };
     readonly tts: ReturnType<typeof createTts>;
+    /**
+     * THE CHILD READS ALOUD AND THIS ANSWERS WITH TEXT (ADR-0216, issue #200; the Dev, 2026-09-21: «o jogo… apenas deve pedir
+     * para ouvir e receber o texto»). `listen()` ends when she goes quiet or the ceiling falls; `stop()` gives the microphone
+     * back; `ready()` says whether this device can hear her language at all. Which recogniser hears her is the engine's
+     * business — and never one that would send her voice to a server. A game that wants it declares `uses: { reading: true }`.
+     */
+    readonly reading: Reading;
+    /**
+     * THE SOUND CAPTION, hosted by the engine (study item D3; ADR-0014; ADR-0164 rules 4–5): a line for eyes that cannot
+     * hear, in the screen footer above the explanation, at most two lines, gone after a moment. Written only while the
+     * child has captions on. Pass it as `createAudioEarcons`'s `showCaption`.
+     * 📏 Before it, each game wrote its own `#caption` with its own timer (platformer 1300 ms, soccer 2600 ms).
+     */
+    readonly captionSound: (text: string) => void;
+    /**
+     * THE GAME EXPLAINS THE ITEM UNDER ITS OWN CURSOR IN THE ENGINE'S FOOTER (ADR-0244): `text`, already in the child's language as
+     * `say` takes it, becomes the footer's RESTING text — the engine's own items (a quick-bar icon, a pause-card item) take the
+     * footer while pointed and give it back to this text when they leave. `null` clears it; call it again when the cursor moves
+     * or the language changes, and with `null` when the screen it explains goes. At most two lines (ADR-0164): a longer text is
+     * clamped there, so say it whole through narration too. Releasing the cartridge clears it.
+     */
+    readonly explain: (text: string | null) => void;
+    /**
+     * The game speed the child chose on the quick bar (ADR-0180): 1 is 100%, down to 0.5. Pass it as `startLoop`'s REQUIRED
+     * `speed` (ADR-0232 D2c), which multiplies the frame time by it; a game that runs its own frames multiplies by this.
+     */
+    readonly gameSpeed: () => number;
+    /**
+     * Does the child want the «N de M» said after an item (ADR-0044 item 3)? Read at each announcement: the hearing panel
+     * turns it off and on. A game that announces its own items asks here instead of reading the settings store by import
+     * (ADR-0232 D2c), as it asks `gameSpeed` — the demo quiz does.
+     */
+    readonly menuIndexOn: () => boolean;
+    /**
+     * TRANSLATES IN THIS ROOT'S LANGUAGE (ADR-0232 D3): the root's own `t`, the one every engine module receives. A game that
+     * writes its own words asks here instead of importing `core/i18n` — the demo quiz does — as it asks `gameSpeed`.
+     */
+    readonly t: Translate;
+    /**
+     * Resolves when the language chosen at boot has loaded — at once for pt (ADR-0232 D3). A game that draws its first screen
+     * waits on it, or the screen is born in the fallback language.
+     */
+    readonly localeReady: () => Promise<void>;
+    /**
+     * THE PAGE'S LANGUAGE (`pt`, `en`, `es`) as this root speaks it, and the door to switch it — the one the 🌐 on the bar uses.
+     * Since `core/i18n` holds no state (ADR-0232 D3, erratum of 2026-09-25) a game asks here instead of `getLocale`/`setLocale`
+     * by import; a switch is kept, told to the page, and followed by every root on it.
+     */
+    readonly locale: () => string;
+    readonly setLocale: (code: string) => Promise<void>;
+    /**
+     * THIS ROOT'S SCREEN-READER ANNOUNCEMENTS (ADR-0232 D4): «polite» (`#sr-status`, does not interrupt) — the announcer every
+     * engine module receives. A game announces HERE instead of importing `core/a11y-sr`, which is a factory now: a second
+     * announcer would write the same regions but carry none of this root's Libras mirror.
+     */
+    readonly say: (text: string) => void;
+    /** The «assertive» announcement (`#sr-alert`): interrupts and speaks now — errors, a checkmate, a crash. See `say`. */
+    readonly alert: (text: string) => void;
+    /**
+     * Every `say`/`alert` — the engine's and the game's — also goes to `sink`, until the returned release. The root connects
+     * nothing. ⚠️ Deaf mode does NOT sign announcements: the interpreter signs what the sonar finds, when the child asks
+     * (ADR-0234) — no queue of messages.
+     */
+    readonly mirrorAnnouncements: (sink: (text: string) => void) => () => void;
+    /**
+     * THIS ROOT'S DEAF MODE (ADR-0234): the one the bar's 🦻 toggles. With it on, every sound is captioned and the sonar has
+     * the interpreter sign what it found; `isOn` is the child's choice, `toggle` flips it from a game's own control.
+     * `captionsOn` is whether a sound gets its caption now — the captions setting OR deaf mode: pass it as
+     * `createAudioEarcons`'s `getCaptionsOn`, beside `captionSound` as its `showCaption`.
+     */
+    readonly deafMode: {
+        readonly isOn: () => boolean;
+        readonly toggle: () => void;
+        readonly captionsOn: () => boolean;
+    };
+    /**
+     * THIS ROOT'S SETTINGS STORE (ADR-0232 D4): the child's settings, read through live getters (`settings.blindMode`) and written
+     * by the setters, plus the bus a game subscribes and emits on. A game reads HERE instead of importing `core/state`, which is
+     * a factory now: a second store would read the same storage but hear none of this root's changes.
+     */
+    readonly settings: SettingsStore;
+    /**
+     * WHERE A GAME MOUNTS ITS MAP (ADR-0239 point 4): the bottom-right cell of the HUD row. The engine draws nothing in it — an
+     * empty slot takes no room — and a game with a map appends its own element here. `null` where the page has no
+     * `#game-region` to hold the row.
+     */
+    readonly mapSlot: HTMLElement | null;
+    /**
+     * THIS ROOT'S INPUT STATE (ADR-0232 D4): the held keys and who pressed them, the transport in use per player, the pads'
+     * frames, and `held(player, action)`. A game reads and writes HERE instead of importing `input/state`, which is a factory
+     * now: a second instance would hold keys this root's transports never press.
+     */
+    readonly input: LiveInput;
+    /**
+     * THIS ROOT'S KEYBOARD MAP and its doors (ADR-0232 D4): `kb()` the live map, `set`, `save`, `reset` (back to the GAME's
+     * default, ADR-0115), `factoryWithGame()` and `load()`. For a game with a remapping screen of its own — `game-2048`'s —
+     * instead of importing `input/keyboard`'s module map, which no longer exists.
+     */
+    readonly keyboardConfig: KeyboardConfigApi;
+    /**
+     * THIS ROOT'S SOUND (ADR-0232 D4): the context (made at the first sound, from the host's window), the master, the mixer and
+     * the syntheses. Read through live getters (`audio.soundOn`, `audio.audioCat`) and moved by its methods (`ensureAC()`,
+     * `tone(…)`). A game asks HERE instead of importing `platform/audio`, which is a factory now: a second one would make a
+     * second context and a second mixer, deaf to this root's volume and categories.
+     */
+    readonly audio: Audio;
+    /**
+     * THIS ROOT'S CRT (ADR-0232 D4): its live config, `apply()` (classes on `#game-region`, kept in the store) and
+     * `scanVars()`, which re-anchors the scanlines to real pixels. A game that scales its own stage with `ui/layout`'s
+     * `createLayout` passes `engine.crt.scanVars` as `afterScale`; a game with a CRT menu of its own reads and writes `cfg`
+     * and calls `apply()` here instead of importing `render/crt`, as it asks `gameSpeed`.
+     */
+    readonly crt: Crt;
+    /**
+     * THIS ROOT'S L→Q CONTRAST ENHANCEMENT (ADR-0232 D4): `filter()` for composing a CSS filter, `t()` the amount, `set(t)`
+     * to change it (kept in the store; the root recomposes the world's filter). A game asks here instead of importing
+     * `render/lq-filter`.
+     */
+    readonly lq: LqFilter;
+    /**
+     * MEASURES WHAT THE WORLD'S CANVAS FLASHES for `ms`, against the WCAG 2.3.1 general flash threshold (study item B2;
+     * `core/flash-threshold`). Only when called — reading pixels every frame costs a school machine (pillar 1), so play never
+     * pays for it. A failure is also a line of `problems`. `lido: false` says why nothing was measured (no canvas, a canvas
+     * the page may not read, or one that reads transparent, as a WebGL canvas without `preserveDrawingBuffer` does) — never a
+     * pass by silence. The red flash is not measured.
+     */
+    readonly measureFlashes: (ms: number) => Promise<FlashMeasurement>;
     readonly overlays: SettingsPanelApi;
     readonly nav: MenuNavApi;
     readonly keyboard: KeyboardRuntime;
     /**
-     * APLICA O FILTRO DE VISÃO NO MUNDO QUE ESTE JOGO DECLAROU (ADR-0087).
+     * THE CONTROLLER OBJECT, offered to the cartridge (ADR-0216, in the Dev's words: «Assim como a engine oferece o objeto de
+     * controle, ela deve oferecer objetos de leitura e TTS»).
+     *
+     * 📌 Every transport the engine knows — keyboard, gamepad (ADR-0224), touch, eyes, face, hands, voice, scan — is mounted
+     * here and presses this controller by itself. This is for a transport a game mounts ITSELF: pressing a position by hand
+     * is telling the engine that the child's device produced that position — with the source, which ADR-0109 demands.
+     *
+     * ⚠️ What it is NOT: a second way for the game to receive input. The game receives through `onCommand`.
+     */
+    readonly controller: VirtualController;
+    /**
+     * APPLIES THE VISION FILTER TO THE WORLD THIS GAME DECLARED (ADR-0087).
      *
-     * ⚠️ Existe porque, sem ela, cada consumidor escrevia a sua — e o `game-15puzzle` escreveu, com o
-     * raciocínio certo e sozinho. O que ela acrescenta é a regra dos MENUS, que um consumidor não tem como
-     * saber: eles vivem por cima da simulação e são o instrumento de sair dela, então se herdaram o filtro por
-     * estarem DENTRO do mundo, ele é desfeito neles. Uma cegueira que apagasse o menu de pausa trancaria a
-     * criança dentro da simulação (#82).
+     * ⚠️ It exists because, without it, each consumer wrote its own — and `game-15puzzle` did, with the right reasoning
+     * and on its own. What it adds is the rule of MENUS, which a consumer has no way to know: they live over the
+     * simulation and are the way out of it, so if they inherited the filter by being INSIDE the world, it is undone on
+     * them. A blindness that blacked out the pause menu would lock the child inside the simulation (#82).
      */
-    readonly aplicarFiltroDeVisao: (css: string, alcance: AlcanceDoFiltro) => void;
+    readonly applyVisionFilter: (css: string, reach: FilterReach) => void;
     /**
-     * A NAVEGAÇÃO SONORA, pronta e ligada à declaração deste jogo (item 19).
+     * NAVIGATION SOUND, ready and wired to this game's declaration (item 19).
      *
-     * Ela vem de graça porque o sonar deixou de precisar de tiles: pergunta topologia (campo 1), alvos (campo
-     * 5) e nome (campo 3), e o jogo já declarou os três para existir. Era o achado 9 do segundo consumidor —
-     * "ligá-lo exigiria MENTIR para a engine" —, e a mentira era exigida pela FORMA da pergunta, não pelo som.
+     * It comes for free because the sonar no longer needs tiles: it asks for topology (field 1), targets (field 5) and
+     * names (field 3), and the game already declared all three to exist. It was finding 9 of the second consumer: wiring
+     * the sonar meant LYING to the engine, and the lie was demanded by the SHAPE of the question, not by the sound.
      */
     readonly sonar: AudioSonar;
     /**
-     * A PILHA DE CENAS (item 22, C3 do ADR-0030), vazia e pronta.
+     * THE SCENE STACK (item 22, C3 of ADR-0030), empty and ready.
      *
-     * Vem de `createGame` e não de cada jogo pelo mesmo motivo do sonar: é infraestrutura, e um jogo que a
-     * montasse sozinho montaria a décima quinta versão de push/pop. O que ela substitui é o
-     * `phase: 'title' | 'playing' | 'paused'` — um enum DESTE jogo que doze módulos leem, e que um jogo com
-     * mapa de fases ou tela de resultados não teria como estender sem pedir constante nova à engine (o ADR-0030
-     * registra alargar a união como NÃO-opção, e é essa a razão).
+     * It comes from `createGame` and not from each game for the same reason as the sonar: it is infrastructure. What it
+     * replaces is `phase: 'title' | 'playing' | 'paused'` — ONE game's enum that engine modules read, and that a game
+     * with a level map or a results screen could not extend without asking the engine for a new constant (ADR-0030
+     * records widening the union as a NON-option, and that is why).
      *
-     * Nasce VAZIA: quem empilha é o jogo, porque quais são as cenas é a única parte disto que é dele.
+     * It is born EMPTY: the game pushes, because which scenes there are is the only part of this that is its own.
      */
-    readonly cenas: SceneStack;
-    /** Quantos filtros de daltonismo foram montados. `0` = não havia host, e o menu visual perde metade. */
+    readonly scenes: SceneStack;
+    /**
+     * TELLS THE CARTRIDGE THE LANGUAGE CHANGED — the only thing it needs to know about it (ADR-0225).
+     *
+     * 📌 The engine already redraws everything that IS its own: the bar, the caption, the card, the pad, an open panel, the
+     * voice that speaks and the model that listens. What it cannot redraw is the ACTIVITY — and without this door the
+     * cartridge would have to subscribe to `i18n:change` on the window, knowing the event's name and reaching a global to
+     * do it. It is the rule the Dev wrote for reading and speech: «o jogo não deve precisar saber como isso funciona»
+     * (ADR-0216).
+     *
+     * ⚠️ Called AFTER the engine has redrawn itself, so the cartridge never sees a half-translated screen.
+     */
+    readonly onLocaleChange: (fn: () => void) => void;
+    /** How many colour-vision filters were mounted. `0` = there was no host, and the visual menu loses half. */
     readonly cvdFilters: number;
-    /** O que FALTOU no documento do consumidor. Vazia = o hospedeiro cumpriu o contrato de marcação. */
+    /** What the host page lacks and what the cartridge left undone, each line naming its fix. Empty = nothing to fix. */
     readonly problems: readonly string[];
-    /** O que este jogo declarou não ter. Devolvido para poder ser auditado — declinar fica no registro. */
+    /** What this game declared it does not have. Returned so it can be audited — declining stays on the record. */
     readonly declines: Declinios;
     /**
-     * O ANÚNCIO DE QUE O LAÇO PAROU, pronto para entrar em `startLoop(ticker, quadro, maxDt, { aoFalhar })`.
+     * THE ANNOUNCEMENT THAT THE LOOP STOPPED, ready to go into `startLoop(ticker, frame, maxDt, { onFailure })`.
      *
-     * ⚠️ O ADR-0054 diz por escrito que fica *"só metade verdadeiro"* enquanto isto não existir, e a metade que
-     * faltava é a que importa: **criança cega não vê tela congelada.** Sem anúncio, o modo cego não distingue
-     * «travou» de «está pensando», e o silêncio é a mesma coisa nos dois casos.
+     * ⚠️ ADR-0054 says in writing that it is only half true while this does not exist, and the missing half is the one
+     * that matters: **a blind child does not see a frozen screen.** Without an announcement, blind mode cannot tell
+     * a crash from a pause to think, and the silence is the same in both cases.
      *
-     * ⚠️ VEM DA ENGINE E NÃO DE CADA JOGO porque a mensagem é a mesma em todos e o canal (leitor de tela +
-     * narração + o que se VÊ) é infraestrutura. Mas quem chama `startLoop` é o JOGO — ele é o dono do ticker —,
-     * então isto é entregue e não instalado: um jogo que monte o laço sem passar isto continua a PARAR, porque
-     * parar não é opcional; o que ele perde é dizer que parou.
+     * ⚠️ IT COMES FROM THE ENGINE AND NOT FROM EACH GAME because the message is the same in all of them and the channel
+     * (screen reader + narration + what is SEEN) is infrastructure. The game owns the ticker and calls `startLoop`, whose
+     * `onFailure` is REQUIRED (ADR-0232 D4): the game passes this, and no registration in `core/loop` stands in for it.
      */
-    readonly aoFalhar: (erro: unknown) => void;
+    readonly onFailure: (failure: unknown) => void;
     /**
-     * O ALCANCE MEDIDO NO ARRANQUE — a garantia do ADR-0079 §3 como dado, para quem quiser lê-la.
+     * THE REACH MEASURED FOR THE MOUNTED CARTRIDGE — ADR-0079 §3's guarantee as data, for whoever wants to read it.
      *
-     * A engine já mostrou o aviso se havia o que dizer; isto fica devolvido porque um jogo pode querer decidir
-     * mais (esconder uma fase que exige doze ações, por exemplo), e porque `ok: false` é o tipo de facto que
-     * tem de poder ser auditado em vez de ficar só numa tela que já fechou.
+     * The engine has already shown the notice if there was something to say; this is returned because a game may want to
+     * decide more (hide a level that demands twelve actions, for example), and because `ok: false` is the kind of fact
+     * that must be auditable instead of living only on a screen that has closed.
      */
-    readonly alcance: Alcance;
+    readonly reach: Reach;
     /**
-     * TORNA ESTE CARTUCHO O CORRENTE (ADR-0142). Uma raiz de composição, vários jogos.
+     * MAKES THIS CARTRIDGE THE CURRENT ONE (ADR-0142). One composition root, several games.
      *
-     * ⚠️ **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.
+     * ⚠️ **THROWS** on a malformed declaration, and does not put it in `problems`: the contract is a PRECONDITION and not
+     * a diagnosis, as at boot. A bad cartridge is never mounted.
      *
-     * 📌 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.
+     * 📌 What it redoes is only what reading again cannot fix: effects written elsewhere — the two mapping registers, the
+     * HUD, the game-options rows, the bar, the reach notice and the pad. `problems` and `reach` describe the mounted
+     * cartridge because they are derived when read, not because `mount` copies them.
      */
-    mount(declaration: GameDeclaration, ganchos?: GanchosDoCartucho): void;
+    mount(declaration: GameDeclaration, hooks?: CartridgeHooks): void;
     /**
-     * SOLTA O CORRENTE: mapeamentos a `null`, aviso de alcance retirado, pilha de cenas esvaziada.
+     * RELEASES THE CURRENT ONE: mappings set to `null`, reach notice and HUD removed, reading thread
+     * closed, scene stack emptied.
      *
-     * ⚠️ 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.
+     * ⚠️ The stack is emptied with `pop()` and not with a `clear()`, and the difference is the decision: a scene's `exit()`
+     * is its DOM cleanup, so running it is the teardown wanted. A `clear()` that skipped them would be the wrong fix.
      */
     unmount(): void;
+    /**
+     * ENDS THIS ROOT: it releases the current cartridge, like `unmount()`, AND STOPS LISTENING TO THE WINDOW.
+     *
+     * 🔴 The two are separate on purpose, and the separation is the whole point. `unmount()` releases the CARTRIDGE (ADR-0142) and
+     * a `mount()` after it must find a root that still hears the keyboard — so `unmount()` may not take the listeners off. But a
+     * page that is finished with a root had, until this method existed, no way to say so: the root kept its ~30 window listeners
+     * for the lifetime of the document, and since every query it makes is document-wide, it went on driving the pause card of
+     * whatever root came after it. 📏 Measured: one ArrowDown moved the cursor one item with one root, two with a second root
+     * alive, three with a third.
+     *
+     * ⚠️ A disposed root is not to be used again: it no longer hears anything. Call it when the page drops the root, not between
+     * cartridges — that is what `unmount()` is for.
+     */
+    dispose(): void;
 }
-/** A metade do jogo SEM a declaração — o que `mount` recebe ao lado dela. */
-export type GanchosDoCartucho = Omit<MetadeDoJogo, 'declaration'>;
+/** The game's half WITHOUT the declaration — what `mount` receives beside it. */
+export type CartridgeHooks = Omit<GameHalf, 'declaration'>;
+/**
+ * EVERY LINE `createGame` AND `mount()` REFUSE A CARTRIDGE WITH — one list, read by the boot, by `mount()` and by the
+ * cartridge checker the engine ships (`inclusionist-check-cartridge`, ADR-0253). EMPTY means the cartridge holds.
+ *
+ * 🎯 ONE LIST AND NOT A CHECKER'S COPY OF IT: a checker that re-listed these rules would drift from the boot the first time
+ * a rule was added here, and it would then accept a cartridge the platform refuses — the drift ADR-0253 exists to end.
+ *
+ * ⚠️ EACH ROW THROWS AT BOOT, by the rubric of ADR-0169: every one is a PROGRAM defect, never a gap of the host, and
+ * `problems` is for what still lets the child play.
+ *   · the declaration's shape (`core/contract`, ADR-0030);
+ *   · «start» and «select» belong to the pause, and a cartridge does not take them (ADR-0144 §4, ADR-0155) — the sentences
+ *     live in `core/actions`, where the validity of a preset lives;
+ *   · the accommodations are ANSWERED, all of them (ADR-0153): the engine would not know which rows to mount;
+ *   · a genre outside the engine's list, or Casino game (ADR-0156 §2, §4); an absent genre is conformant;
+ *   · a malformed `hud`, game options or `howToPlay` (ADR-0169): the engine would not know what to place, draw or show.
+ */
+export declare function cartridgeRefusals(declaration: Partial<GameDeclaration> | null | undefined, hooks: Partial<CartridgeHooks> | null | undefined): string[];
 /**
- * Liga a engine para um jogo declarado.
+ * THE GAME'S HALF of `CreateGameOptions` — the fields ADR-0139 §1 says a cartridge SUPPLIES, apart from the ones that
+ * describe the page and the device.
  *
- * ⚠️ 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`.
+ * The test that record gives: could a PAGE answer this without knowing which game runs? If not, the field is here.
  */
+type GameHalf = Pick<CreateGameOptions, 'declaration' | 'isNavigable' | 'withIndex' | 'onBar' | 'navBar' | 'players' | 'setPhase' | 'isBlindMode' | 'preset' | 'declines' | 'getPauseActs' | 'setPauseActor' | 'setPlayerTheme' | 'setPlayerCorrection' | 'accommodations' | 'genre' | 'onScreenPad' | 'hud' | 'gameOptions' | 'howToPlay' | 'onCommand' | 'gamepad' | 'dictionaries'>;
 /**
- * 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.
+ * Switches the engine on for a declared game.
  *
- * ⚠️ 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.
+ * ⚠️ THROWS if the declaration is malformed, and does NOT throw if markup is missing. The difference is not taste: a
+ * wrong declaration is a PROGRAM defect, and a game that runs half-declared is worse than one that does not open; a
+ * missing id is a gap of the HOST, and the quiz proved that switching on only the part that serves is legitimate —
+ * that is how it declined the pad and the sonar without lying. So one becomes an exception and the other `problems`.
  */
-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 {};