@the-inclusionist/engine 10.0.0 → 11.0.0

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

@@ -8,12 +8,13 @@ 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 } from '../platform/tts.js';
 import { type Reading } from '../platform/reading.js';
 import { type Audio } from '../platform/audio.js';
-import { type AudioSonar, type SonarPlayer } from '../platform/audio-sonar.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';
@@ -27,7 +28,6 @@ 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';
-export type { GamepadGameHooks } from '../input/gamepad.js';
 import { type KeyboardRuntime } from '../input/keyboard-runtime.js';
 import { type KeyboardConfigApi } from '../input/keyboard.js';
 import { type HeavyReport } from '../platform/heavy.js';
@@ -81,6 +81,13 @@ export interface EngineHost {
      * `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;
 }
 /**
  * What this game does NOT have. Declared, not deduced from a getter that returns null.
@@ -142,19 +149,15 @@ export interface CreateGameOptions {
     }[];
     /** Phase change, for a game that has phases. Absent = does nothing (a game without phases loses nothing). */
     readonly setPhase?: (p: 'title' | 'playing' | 'paused') => void;
-    /**
-     * The players as NAVIGATION SOUND sees them. Absent, `createGame` DERIVES one from field 4 of the contract: the focus
-     * says where the player is, which is all the sonar needs to know about position.
-     *
-     * A game with several players, or with an audio device per player, supplies its own list. A one-child game supplies
-     * nothing — and gets the sonar anyway, which is the point.
-     */
-    readonly sonarPlayers?: () => SonarPlayer[];
     /** Blind mode on? Absent = the engine's own stored value (`core/state.blindMode`). Applies to every player. */
     readonly isBlindMode?: () => boolean;
     /**
-     * THIS GAME'S 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).
+     * 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`.
      *
      * 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.
@@ -177,15 +180,16 @@ export interface CreateGameOptions {
      */
     readonly hud?: readonly HudNumber[];
     /**
-     * THE OPTIONS OF THIS GAME, as rows the engine draws (ADR-0182; issue #178): a label and hint in the game's words, 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
+     * 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 read at every showing, in the page's language; its figure, when given, is drawn
+     * 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`.
      */
@@ -193,9 +197,12 @@ export interface CreateGameOptions {
     /**
      * 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, as `registerDict` does; a key given in one language and not another is a line of
-     * `problems`. Decision (mechanical, ADR-0232 D3): an option and not a method on the handle, because every game measured
-     * registers BEFORE `createGame` — and a method would come after the markup was translated.
+     * 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>>>>;
     /**
@@ -218,8 +225,8 @@ export interface CreateGameOptions {
     /**
      * THE ACCOMMODATIONS THAT HAVE A SUBJECT IN THIS GAME — the cartridge's answer, REQUIRED (ADR-0153).
      *
-     * 🔴 For each of the sixteen only the game can answer (`GAME_KEYED` in `core/accommodations`): the game's WORD, if
-     * it has a subject here, or `false`. In the Dev's words: «Gênero não precisa responder todas as acomodações, mas
+     * 🔴 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.»
      *
      * ⚠️ REQUIRED, by the `holdsAtOnce` rubric: there is no safe default — yes mounts the wheelchair in chess, no
@@ -244,13 +251,20 @@ export interface CreateGameOptions {
      *   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 model of her language because of this answer. Absent, `motor.reading.listen()` refuses and
+     *   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).
@@ -321,7 +335,6 @@ export interface CreateGameOptions {
     readonly setPlayerTheme?: (i: number, theme: Theme) => void;
     readonly setPlayerCorrection?: (i: number, correction: Correction) => void;
 }
-export type { FlashMeasurement };
 export interface Engine {
     readonly declaration: GameDeclaration;
     /**
@@ -356,6 +369,14 @@ export interface Engine {
      * 📏 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.
@@ -377,6 +398,13 @@ export interface Engine {
      * 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
@@ -386,21 +414,21 @@ export interface Engine {
     /** The «assertive» announcement (`#sr-alert`): interrupts and speaks now — errors, a checkmate, a crash. See `say`. */
     readonly alert: (text: string) => void;
     /**
-     * SIGNS THIS ROOT'S ANNOUNCEMENTS TOO: every `say`/`alert` — the engine's and the game's — also goes to `sink`, until the
-     * returned release. Pass `engine.libras.say`. The root connects nothing by itself (decision DD1, pending the Dev): a game
-     * that signed its announcements before connects it here, and a game that did not keeps not signing.
+     * 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-0232 D4): the one the bar's 🦻 toggles. `isOpen` is the child's choice; `say` signs a text
-     * while it is open (a queue of one); `tick` opens the interpreter for a choice restored from storage, and a game that
-     * signs calls it from its loop; `toggle` flips the mode from a game's own control, confirming in this root's language.
+     * 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 libras: {
-        readonly isOpen: () => boolean;
-        readonly say: (text: string) => void;
-        readonly tick: () => void;
+    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
@@ -408,6 +436,12 @@ export interface Engine {
      * 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
@@ -564,13 +598,30 @@ export interface Engine {
 }
 /** 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[];
 /**
  * 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.
  *
  * 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' | 'sonarPlayers' | 'isBlindMode' | 'preset' | 'declines' | 'getPauseActs' | 'setPauseActor' | 'setPlayerTheme' | 'setPlayerCorrection' | 'accommodations' | 'genre' | 'onScreenPad' | 'hud' | 'gameOptions' | 'howToPlay' | 'onCommand' | 'gamepad'>;
+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'>;
 /**
  * Switches the engine on for a declared game.
  *