@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/platform/storage.d.ts

@@ -1,117 +1,52 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-export declare function get(key: string, fallback: string): string;
-export declare function get(key: string, fallback?: null): string | null;
-export declare function set(key: string, value: string | number | boolean): boolean;
-export declare function remove(key: string): void;
-export declare function getBool(key: string, fallback?: boolean): boolean;
-export declare function setBool(key: string, on: boolean): void;
-export declare function getNum(key: string, fallback?: number): number;
-export declare function getJSON<T = unknown>(key: string, fallback?: T | null): T | null;
-export declare function setJSON(key: string, obj: unknown): void;
 /**
- * Nome completo de uma chave do escopo DO JOGO.
- *
- * ⚠️ O ID ENTRA COMO ARGUMENTO, e ele já foi uma constante aqui (`JOGO_ID = 'inclusionist'`). Pelo teste do
- * ADR-0080 — *um segundo jogo quereria um valor diferente aqui?* — a resposta é sim e é imediata: dois jogos
- * no mesmo perfil de navegador colidiam em `activity`, `quizlevel`, `cenario`, `tabsel`, `fracnot` e em toda
- * gravação `attract_*`. Um sobrescrevia o progresso do outro sem erro nenhum.
+ * What the store wraps: the three methods of the Web Storage API it calls. A window's `localStorage` has this shape, and so
+ * does `memoryBackend()` — which is how a test, or a second root on the same page, gets storage nobody else writes.
+ */
+export interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** The store every persisting module receives: typed reads with a fallback, writes that never throw. */
+export interface Store {
+    get(key: string, fallback: string): string;
+    get(key: string, fallback?: null): string | null;
+    /** `false` when the backend refused the write (quota, private mode, no storage at all). */
+    set(key: string, value: string | number | boolean): boolean;
+    remove(key: string): void;
+    getBool(key: string, fallback?: boolean): boolean;
+    setBool(key: string, on: boolean): void;
+    getNum(key: string, fallback?: number): number;
+    getJSON<T = unknown>(key: string, fallback?: T | null): T | null;
+    setJSON(key: string, obj: unknown): void;
+    /**
+     * Reads the NEW key; if it does not exist yet, inherits the LEGACY one's value. Read-only: whoever writes, writes to the
+     * new one. It is what lets a key be renamed without a migration step and without anyone losing a setting.
+     */
+    getWithLegacy(newKey: string, legacyKey: string, fallback: string): string;
+    getWithLegacy(newKey: string, legacyKey: string, fallback?: null): string | null;
+    /** `getWithLegacy`'s pair for a JSON value — the inheritance has to hold for both formats, or half the keys migrate and
+     *  the other half vanish, the worst of both worlds. */
+    getJsonWithLegacy<T = unknown>(newKey: string, legacyKey: string, fallback?: T | null): T | null;
+}
+/**
+ * THE STORE, built around the backend it is GIVEN (ADR-0232). `null` is a host with no storage at all: every read gives its
+ * fallback and every write reports `false` — the same answer a throwing `localStorage` gives, so the two cannot differ.
  *
- * ⚠️ E O ID NÃO VEM DA DECLARAÇÃO, que era o desenho óbvio. Ele não pode: `game/state` lê o armazenamento no
- * IMPORT, e o import corre antes de qualquer `createGame()`. Um id vindo da declaração chegaria depois de as
- * três chaves já terem sido resolvidas — contra vazio, e em silêncio. Quem sabe o próprio id é o JOGO, que o
- * passa como constante sua; o ADR-0080 proíbe a ENGINE de o saber, não o jogo.
+ * 📌 CLOSURES AND NOT METHODS ON `this`: `loadLocale({ ...store, ...hooks })` spreads the store into another object, and a
+ * method that read `this` would lose its backend in the spread.
  */
-export declare function kJogo(jogo: string, nome: string): string;
+export declare function createStorage(backend: StorageLike | null): Store;
 /**
- * Lê a chave NOVA; se ela ainda não existe, herda o valor da LEGADA. Só de leitura: quem grava, grava na nova.
- * É o que permite renomear chave sem um passo de migração e sem perder o ajuste de ninguém.
+ * A backend kept in memory, seeded with `entries` — for a host with no storage worth writing to, and for a test: a file that
+ * builds its own cannot inherit another file's keys nor race it for them (ADR-0232 driver D4, the browser suite's F9).
  */
-export declare function getComLegado(nova: string, legada: string, fallback: string): string;
-export declare function getComLegado(nova: string, legada: string, fallback?: null): string | null;
-/** O par de `getComLegado` para valor em JSON — a herança tem de valer para os dois formatos, senão metade
- *  das chaves migra e a outra metade some, que é o pior dos dois mundos. */
-export declare function getJSONComLegado<T = unknown>(nova: string, legada: string, fallback?: T | null): T | null;
-export declare const KEYS: {
-    onebtn: string;
-    wheelchair: string;
-    modocego: string;
-    caneDiv: string;
-    hearingloss: string;
-    activity: (jogo: string) => string;
-    activityLegado: string;
-    quizlevel: (jogo: string) => string;
-    quizlevelLegado: string;
-    cenario: (jogo: string) => string;
-    cenarioLegado: string;
-    tabsel: (jogo: string) => string;
-    tabselLegado: string;
-    fracnot: (jogo: string) => string;
-    fracnotLegado: string;
-    viz: string;
-    lq: string;
-    cbsafe: string;
-    ownercolors: string;
-    outfg: string;
-    outbg: string;
-    hcrole: string;
-    juice: string;
-    crt: string;
-    crtLegacy: string;
-    ttsEngine: string;
-    ttsVoice: string;
-    lang: string;
-    letterCase: string;
-    captions: string;
-    tea: string;
-    menuIndex: string;
-    fontKey: string;
-    padDesign: string;
-    padDir: string;
-    touchmap: string;
-    padBtnMm: string;
-    padGapMm: string;
-    padStickMm: string;
-    padTravelMm: string;
-    padDpadMm: string;
-    reducedMotion: string;
-    toggleMoveLegacy: string;
-    /**
-     * @deprecated ⚠️ A CHAVE LEGADA do modo visual — UM valor, do tempo em que só cabia um (issue #104).
-     *
-     * Continua a ser LIDA, e é isso que impede a criança de perder o que já escolheu; continua a ser ESCRITA
-     * enquanto os controles ainda escreverem um valor de cada vez, porque um leitor antigo (o cartucho na
-     * versão publicada) faz `if (v && VIZ_BY_KEY[v])` e rejeitaria um JSON — escrever a forma nova AQUI
-     * apagaria o ajuste dela em silêncio, que é exactamente o defeito que a migração existe para não cometer.
-     */
-    vizP: (i: number) => string;
-    /**
-     * O ESTADO VISUAL de dois eixos, em JSON (ADR-0076, issue #104).
-     *
-     * ⚠️ CHAVE NOVA AO LADO DA VELHA, e não a mesma chave com conteúdo novo. É o mesmo desenho que o campo
-     * `visual` usa ao lado do `viz`: as duas formas coexistem enquanto houver leitores das duas, cada um lê a
-     * que entende, e a velha só morre quando não sobrar quem a leia. `migrarVisual` aceita as duas, então o
-     * recuo — chave nova ausente, chave velha presente — devolve exactamente o que a criança escolheu.
-     */
-    visualP: (i: number) => string;
-    sinkP: (i: number) => string;
-    easyP: (i: number) => string;
-    /**
-     * ⚠️ AS DUAS DE BAIXO SÃO AS CHAVES LEGADAS desde 2026-09-08 (ADR-0104 §C, issue #114). Continuam a ser
-     * LIDAS — é o ajuste da criança, e a herança dele é o que a impede de o perder — e não voltam a ser
-     * escritas. O que se escreve é a chave COM TRANSPORTE, porque a alternância é do APARELHO e não da pessoa:
-     * ligá-la no controle de tela, onde ninguém segura um botão virtual com conforto, ligava-a também no
-     * teclado, onde segurar uma tecla é exactamente o que a criança sabe fazer.
-     *
-     * ⚠️ E A CHAVE NOVA NÃO MORA AQUI, de propósito. Ela é `chaveDaAlternancia`, em `input/latch-scope` — este
-     * ficheiro é módulo-FOLHA e `platform/` não importa de `input/`, que é a camada acima. Montá-la aqui
-     * exigiria ou uma aresta ao contrário ou uma segunda cópia do nome, e a segunda cópia é exactamente o que
-     * o comentário do bloco acima existe para impedir. O dono do nome é quem conhece a regra do transporte.
-     */
-    toggleMoveP: (i: number) => string;
-    toggleRunP: (i: number) => string;
-    rmWalkP: (i: number) => string;
-    rmBreathP: (i: number) => string;
-    rmFlavorP: (i: number) => string;
-    attract: (jogo: string, cen: string) => string;
-    attractLegado: (cen: string) => string;
-};
+export declare function memoryBackend(entries?: Iterable<readonly [string, string]>): StorageLike;
+/**
+ * THE KEYS OUTSIDE EVERY ENGINE SCOPE (study item E2): not the child's `incl_*` (and the older `inclusionist.*`), not a
+ * game's `incl.<game>.*`. 📏 Measured: pinball stores `pinball:*`. ⚠️ A game's data stored in the CHILD's scope
+ * (chess's `incl_chess_*`) is not seen: the engine's own `incl_` keys are not one closed list, so that question would
+ * accuse the engine.
+ */
+export declare function keysOutsideScopes(storedKeys: Iterable<string>): string[];

package/dist-pkg/platform/storage.js

@@ -1,183 +1,118 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// platform/storage.ts — Camada única de persistência (localStorage) — módulo-folha. À prova de exceção:
-// localStorage LANÇA em file:// e no modo privado de alguns navegadores, e isso derrubava o boot inteiro (por
-// isso todo acesso é try/catch). Centralizar aqui: um lugar para trocar a estratégia (namespacing, IndexedDB…)
-// sem caçar ~60 pontos. Migração gradual — nem todo game.js usa isto ainda.
-export function get(key, fallback = null) {
-    try {
-        const v = localStorage.getItem(key);
-        return v == null ? fallback : v;
-    }
-    catch {
-        return fallback;
-    }
-}
-export function set(key, value) {
-    try {
-        localStorage.setItem(key, String(value));
-        return true;
-    }
-    catch {
-        return false;
+// platform/storage.ts — the single persistence layer, as a FACTORY: `createStorage(backend)` wraps the browser object it is
+// given (ADR-0232 point 2). The composition root builds the one store of a page from what the HOST lends it, and every
+// module that persists receives that store through its ctx or deps (issue #207).
+//
+// Exception-proof: `localStorage` THROWS on file:// and in some browsers' private mode, and that used to bring the whole
+// boot down (hence every access is try/catch). Centralised here: one place to change the strategy (namespacing,
+// IndexedDB…) without hunting dozens of call sites.
+/**
+ * THE STORE, built around the backend it is GIVEN (ADR-0232). `null` is a host with no storage at all: every read gives its
+ * fallback and every write reports `false` — the same answer a throwing `localStorage` gives, so the two cannot differ.
+ *
+ * 📌 CLOSURES AND NOT METHODS ON `this`: `loadLocale({ ...store, ...hooks })` spreads the store into another object, and a
+ * method that read `this` would lose its backend in the spread.
+ */
+export function createStorage(backend) {
+    function get(key, fallback = null) {
+        try {
+            const v = backend ? backend.getItem(key) : null;
+            return v == null ? fallback : v;
+        }
+        catch {
+            return fallback;
+        }
     }
-}
-export function remove(key) { try {
-    localStorage.removeItem(key);
-}
-catch { /* noop */ } }
-export function getBool(key, fallback = false) { const v = get(key, null); return v == null ? fallback : v === '1'; }
-export function setBool(key, on) { set(key, on ? '1' : '0'); }
-export function getNum(key, fallback = 0) {
-    const v = get(key, null);
-    const n = v == null ? NaN : parseFloat(v);
-    return isFinite(n) ? n : fallback;
-}
-export function getJSON(key, fallback = null) {
-    try {
-        const s = get(key, null);
-        return s == null ? fallback : JSON.parse(s);
+    const set = (key, value) => {
+        if (!backend)
+            return false;
+        try {
+            backend.setItem(key, String(value));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const remove = (key) => { try {
+        backend?.removeItem(key);
     }
-    catch {
-        return fallback;
+    catch { /* noop */ } };
+    const getJSON = (key, fallback = null) => {
+        try {
+            const s = get(key, null);
+            return s == null ? fallback : JSON.parse(s);
+        }
+        catch {
+            return fallback;
+        }
+    };
+    function getWithLegacy(newKey, legacyKey, fallback = null) {
+        const v = get(newKey, null);
+        if (v !== null)
+            return v;
+        const inherited = get(legacyKey, null);
+        return inherited !== null ? inherited : fallback;
     }
+    return {
+        get, set, remove, getJSON, getWithLegacy,
+        getBool: (key, fallback = false) => { const v = get(key, null); return v == null ? fallback : v === '1'; },
+        setBool: (key, on) => { set(key, on ? '1' : '0'); },
+        getNum: (key, fallback = 0) => {
+            const v = get(key, null);
+            const n = v == null ? NaN : parseFloat(v);
+            return isFinite(n) ? n : fallback;
+        },
+        setJSON: (key, obj) => { try {
+            set(key, JSON.stringify(obj));
+        }
+        catch { /* noop */ } },
+        getJsonWithLegacy: (newKey, legacyKey, fallback = null) => {
+            const v = getJSON(newKey, null);
+            if (v !== null)
+                return v;
+            const inherited = getJSON(legacyKey, null);
+            return inherited !== null ? inherited : fallback;
+        },
+    };
 }
-export function setJSON(key, obj) { try {
-    set(key, JSON.stringify(obj));
+/**
+ * A backend kept in memory, seeded with `entries` — for a host with no storage worth writing to, and for a test: a file that
+ * builds its own cannot inherit another file's keys nor race it for them (ADR-0232 driver D4, the browser suite's F9).
+ */
+export function memoryBackend(entries = []) {
+    const kept = new Map(entries);
+    return {
+        getItem: (key) => kept.get(key) ?? null,
+        setItem: (key, value) => { kept.set(key, String(value)); },
+        removeItem: (key) => { kept.delete(key); },
+    };
 }
-catch { /* noop */ } }
-/* ===================== os DOIS escopos (save com namespace, ADR-0027 passo 7) ===================== */
+/* ===================== the TWO scopes (namespaced saves, ADR-0027 step 7) ===================== */
 //
-// O namespacing óbvio — um prefixo por jogo em TUDO — seria um defeito de acessibilidade grave, e vale dizer
-// por quê antes de dizer o que foi feito.
+// The obvious namespacing — a per-game prefix on EVERYTHING — would be a serious accessibility defect, and it is worth
+// saying why before saying what was done.
 //
-// Uma criança cega configura o modo cego, a bengala, a voz, a velocidade da narração. Uma criança daltônica
-// escolhe a correção. Uma criança disléxica escolhe a fonte. Se cada jogo do catálogo tivesse o próprio
-// espaço de nomes, ela teria de REFAZER tudo isso em cada jogo do catálogo — e quem mais depende dos ajustes
-// é justamente quem tem menos margem para refazê-los. (O número que estava aqui era 35, do plano que morreu
-// em 2026-08-28; o catálogo do MVP são 300+ jogos, o que só torna o argumento mais forte.)
+// A blind child sets up blind mode, the cane, the voice, the narration speed. A colour-blind child picks the correction.
+// A dyslexic child picks the font. If every game had its own namespace, they would have to REDO all of that in every
+// game — and whoever depends most on the settings is exactly whoever has the least margin to redo them.
 //
-// Então são DOIS escopos, e a linha entre eles não é técnica, é de quem a coisa pertence:
+// So there are TWO scopes, and the line between them is not technical, it is about whom the thing belongs to:
 //
-//   · COMPARTILHADO (`incl_*`, como sempre foi) — o que pertence à CRIANÇA: acessibilidade, tipografia,
-//     idioma, voz, controles, toque. Segue com ela de jogo em jogo, de propósito. O segundo consumidor (o
-//     quiz) já lê a fonte escolhida no jogo de plataforma, e isso está CERTO.
-//   · DO JOGO (`incl.<jogo>.*`) — o que pertence a ESTA partida: atividade, nível, cenário, gravação da
-//     demonstração. Dois jogos com um "nível 3" não são o mesmo nível 3.
+//   · SHARED (`incl_*`) — what belongs to the CHILD: accessibility, typography, language, voice, controls, touch. It
+//     follows them from game to game, on purpose: a second game reading the font chosen in the first is RIGHT.
+//   · THE GAME'S (`incl.<game>.*`) — what belongs to THIS play-through: activity, level, scenery, the demo recording.
+//     Two games with a "level 3" do not have the same level 3.
 //
-// A LEITURA HERDA DA CHAVE ANTIGA e a escrita vai só para a nova (`getComLegado`). Sem passo de migração no
-// boot, porque `core/state` lê no IMPORT — uma migração agendada chegaria tarde. E a chave velha fica onde
-// está: é dado da criança, não meu para apagar, e a sua permanência é o que torna um retorno possível.
+// THE READ INHERITS FROM THE OLD KEY and the write goes to the new one only (`getWithLegacy`). No migration step, because
+// a scheduled migration would arrive after the reads. And the old key stays where it is: it is the child's data, not mine
+// to delete, and keeping it is what makes a way back possible.
 /**
- * Nome completo de uma chave do escopo DO JOGO.
- *
- * ⚠️ O ID ENTRA COMO ARGUMENTO, e ele já foi uma constante aqui (`JOGO_ID = 'inclusionist'`). Pelo teste do
- * ADR-0080 — *um segundo jogo quereria um valor diferente aqui?* — a resposta é sim e é imediata: dois jogos
- * no mesmo perfil de navegador colidiam em `activity`, `quizlevel`, `cenario`, `tabsel`, `fracnot` e em toda
- * gravação `attract_*`. Um sobrescrevia o progresso do outro sem erro nenhum.
- *
- * ⚠️ E O ID NÃO VEM DA DECLARAÇÃO, que era o desenho óbvio. Ele não pode: `game/state` lê o armazenamento no
- * IMPORT, e o import corre antes de qualquer `createGame()`. Um id vindo da declaração chegaria depois de as
- * três chaves já terem sido resolvidas — contra vazio, e em silêncio. Quem sabe o próprio id é o JOGO, que o
- * passa como constante sua; o ADR-0080 proíbe a ENGINE de o saber, não o jogo.
+ * THE KEYS OUTSIDE EVERY ENGINE SCOPE (study item E2): not the child's `incl_*` (and the older `inclusionist.*`), not a
+ * game's `incl.<game>.*`. 📏 Measured: pinball stores `pinball:*`. ⚠️ A game's data stored in the CHILD's scope
+ * (chess's `incl_chess_*`) is not seen: the engine's own `incl_` keys are not one closed list, so that question would
+ * accuse the engine.
  */
-export function kJogo(jogo, nome) { return 'incl.' + jogo + '.' + nome; }
-export function getComLegado(nova, legada, fallback = null) {
-    const v = get(nova, null);
-    if (v !== null)
-        return v;
-    const antigo = get(legada, null);
-    return antigo !== null ? antigo : fallback;
-}
-/** O par de `getComLegado` para valor em JSON — a herança tem de valer para os dois formatos, senão metade
- *  das chaves migra e a outra metade some, que é o pior dos dois mundos. */
-export function getJSONComLegado(nova, legada, fallback = null) {
-    const v = getJSON(nova, null);
-    if (v !== null)
-        return v;
-    const antigo = getJSON(legada, null);
-    return antigo !== null ? antigo : fallback;
+export function keysOutsideScopes(storedKeys) {
+    return [...storedKeys].filter((k) => !k.startsWith('incl_') && !k.startsWith('inclusionist.') && !k.startsWith('incl.'));
 }
-// Registro das chaves conhecidas (documentação em UM lugar; a fonte de verdade ainda é o uso). Vai sendo
-// completado à medida que os lotes migram. Chaves com {i}/{cen}/{id} são parametrizadas por jogador/cenário/controle.
-export const KEYS = {
-    // empatia motora/auditiva
-    onebtn: 'incl_onebtn', wheelchair: 'incl_wheelchair', modocego: 'incl_modocego', caneDiv: 'incl_cane_div',
-    hearingloss: 'incl_hearingloss',
-    // atividade / quiz / cenário — ESCOPO DO JOGO (ver os dois escopos acima). `*Legado` é o nome antigo, de
-    // onde a leitura herda uma vez; a escrita vai só para o novo.
-    //
-    // ⚠️ SÃO FUNÇÕES DO ID DO JOGO, e as da criança são strings. A diferença de FORMA é o que impede o engano:
-    // não há como prefixar por engano uma preferência da criança, porque ela não tem onde receber o id — e não
-    // há como esquecer de escopar uma chave da partida, porque sem o argumento não compila. A regra que antes
-    // vivia só num comentário passou a viver no tipo.
-    activity: (jogo) => kJogo(jogo, 'activity'), activityLegado: 'incl_activity',
-    quizlevel: (jogo) => kJogo(jogo, 'quizlevel'), quizlevelLegado: 'incl_quizlevel',
-    cenario: (jogo) => kJogo(jogo, 'cenario'), cenarioLegado: 'incl_cenario',
-    tabsel: (jogo) => kJogo(jogo, 'tabsel'), tabselLegado: 'incl_tabsel',
-    fracnot: (jogo) => kJogo(jogo, 'fracnot'), fracnotLegado: 'incl_fracnot',
-    // visual / contraste / cor
-    viz: 'incl_viz', lq: 'incl_lq', cbsafe: 'incl_cbsafe', ownercolors: 'incl_ownercolors',
-    outfg: 'incl_outfg', outbg: 'incl_outbg', hcrole: 'incl_hcrole', juice: 'incl_juice', crt: 'incl_crt2',
-    crtLegacy: 'incl_crt', // formato antigo (booleano); crt.ts migra p/ incl_crt2 na 1ª leitura (fresh)
-    // áudio / voz / i18n
-    ttsEngine: 'incl_tts_engine', ttsVoice: 'incl_tts_voice', lang: 'incl_lang', // audiocat_{k}
-    // comunicação / legendas (ADR-0028: todo menu persiste)
-    letterCase: 'incl_lettercase', captions: 'incl_captions',
-    // ⚠️ O NÍVEL TEA (calmo / silencioso) PASSOU A PERSISTIR EM 2026-09-07, e antes não persistia: era um
-    // `let calmMode = 0` em `ui/pause-icons`, com o comentário «deliberately NOT persisted — verbatim: game.js
-    // never wrote it to storage». O «verbatim» é a chave — foi PRESERVADO na extração do monólito, não
-    // decidido. O custo era da criança que mais precisa dele: quem usa o modo silencioso voltava a pô-lo a
-    // cada sessão, e é para quem o barulho inesperado custa mais. O ADR-0028 diz que todo menu persiste.
-    tea: 'incl_tea',
-    menuIndex: 'incl_menuindex', // "6 de 10" no fim do anuncio de item (ADR-0044, item 3)
-    // tipografia / controles / toque
-    fontKey: 'incl_font_k', padDesign: 'incl_paddesign', padDir: 'incl_paddir', touchmap: 'incl_touchmap',
-    padBtnMm: 'incl_padbtnmm', padGapMm: 'incl_padgapmm', padStickMm: 'incl_padstickmm',
-    padTravelMm: 'incl_padtravelmm', padDpadMm: 'incl_paddpadmm',
-    // movimento reduzido (objeto inteiro num JSON so) + a chave antiga de alternar-movimento, que
-    // loadPlayerA11y ainda le uma vez para migrar quem vinha da versao anterior
-    reducedMotion: 'inclusionist.reducedmotion.v1', toggleMoveLegacy: 'inclusionist.togglemove',
-    // POR JOGADOR — parametrizadas pelo indice da tela. Eram sufixos '_p'+i montados a mao em varios
-    // pontos do game.js; virar funcao aqui e o que impede que um deles escreva num nome torto.
-    /**
-     * @deprecated ⚠️ A CHAVE LEGADA do modo visual — UM valor, do tempo em que só cabia um (issue #104).
-     *
-     * Continua a ser LIDA, e é isso que impede a criança de perder o que já escolheu; continua a ser ESCRITA
-     * enquanto os controles ainda escreverem um valor de cada vez, porque um leitor antigo (o cartucho na
-     * versão publicada) faz `if (v && VIZ_BY_KEY[v])` e rejeitaria um JSON — escrever a forma nova AQUI
-     * apagaria o ajuste dela em silêncio, que é exactamente o defeito que a migração existe para não cometer.
-     */
-    vizP: (i) => 'incl_viz_p' + i,
-    /**
-     * O ESTADO VISUAL de dois eixos, em JSON (ADR-0076, issue #104).
-     *
-     * ⚠️ CHAVE NOVA AO LADO DA VELHA, e não a mesma chave com conteúdo novo. É o mesmo desenho que o campo
-     * `visual` usa ao lado do `viz`: as duas formas coexistem enquanto houver leitores das duas, cada um lê a
-     * que entende, e a velha só morre quando não sobrar quem a leia. `migrarVisual` aceita as duas, então o
-     * recuo — chave nova ausente, chave velha presente — devolve exactamente o que a criança escolheu.
-     */
-    visualP: (i) => 'incl_visual_p' + i,
-    sinkP: (i) => 'incl_sink_p' + i,
-    easyP: (i) => 'incl_easy_p' + i,
-    /**
-     * ⚠️ AS DUAS DE BAIXO SÃO AS CHAVES LEGADAS desde 2026-09-08 (ADR-0104 §C, issue #114). Continuam a ser
-     * LIDAS — é o ajuste da criança, e a herança dele é o que a impede de o perder — e não voltam a ser
-     * escritas. O que se escreve é a chave COM TRANSPORTE, porque a alternância é do APARELHO e não da pessoa:
-     * ligá-la no controle de tela, onde ninguém segura um botão virtual com conforto, ligava-a também no
-     * teclado, onde segurar uma tecla é exactamente o que a criança sabe fazer.
-     *
-     * ⚠️ E A CHAVE NOVA NÃO MORA AQUI, de propósito. Ela é `chaveDaAlternancia`, em `input/latch-scope` — este
-     * ficheiro é módulo-FOLHA e `platform/` não importa de `input/`, que é a camada acima. Montá-la aqui
-     * exigiria ou uma aresta ao contrário ou uma segunda cópia do nome, e a segunda cópia é exactamente o que
-     * o comentário do bloco acima existe para impedir. O dono do nome é quem conhece a regra do transporte.
-     */
-    toggleMoveP: (i) => 'incl_togglemove_p' + i,
-    toggleRunP: (i) => 'incl_togglerun_p' + i, // alternância do botão de CORRER (irmã da de movimento)
-    rmWalkP: (i) => 'incl_rmWalk_p' + i,
-    rmBreathP: (i) => 'incl_rmBreath_p' + i,
-    rmFlavorP: (i) => 'incl_rmFlavor_p' + i,
-    // demo/attract: uma gravação por cenário (fn em vez de string — chave parametrizada). ESCOPO DO JOGO: a
-    // gravação é de uma fase DESTE jogo e não faz sentido nenhum em outro.
-    attract: (jogo, cen) => kJogo(jogo, 'attract_' + cen),
-    attractLegado: (cen) => 'incl_attract_' + cen,
-};

package/dist-pkg/platform/tts.d.ts

@@ -1,33 +1,27 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Store } from './storage.js';
+import type { Translator } from '../core/i18n.js';
+import { type NeuralVoice } from './voice-plan.js';
+import { type LoadKokoro, type KokoroModule, type KokoroSession } from './kokoro.js';
+import type { SpeechPort } from './speech.js';
+export type { LoadKokoro, KokoroModule, KokoroSession };
 interface TtsEngine {
     id: string;
     speak: (text: string) => void;
 }
-/**
- * O QUE A ENGINE PRECISA DE UM MOTOR NEURAL — e nada mais. Duas chamadas, escritas aqui em vez de importadas
- * do fornecedor, porque importar o TIPO obrigaria o pacote a estar instalado para o `tsc` do consumidor
- * correr: seria o mesmo defeito do ADR-0093 mudado de campo, do `dependencies` para o espaço de tipos.
- */
-export interface SessaoNeural {
-    predict: (texto: string) => Promise<{
-        arrayBuffer: () => Promise<ArrayBuffer>;
-    }>;
-}
-export interface ModuloNeural {
-    TtsSession: {
-        create: (o: {
-            voiceId: string;
-            progress?: (p: {
-                loaded: number;
-                total: number;
-            }) => void;
-            logger?: (...a: unknown[]) => void;
-        }) => Promise<SessaoNeural>;
-    };
-}
-/** A PORTA (ADR-0094). Uma linha do lado do jogo: `() => import('@mintplex-labs/piper-tts-web')`. */
-export type CarregarVozNeural = () => Promise<ModuloNeural>;
 export interface TtsCtx {
+    /**
+     * Where the chosen engine and voice are kept: the page's store, built by the root (ADR-0232, issue #207). Required — a
+     * voice choice read from nowhere would speak with the first voice of the list at every visit, and the child who picked
+     * one would lose it in silence.
+     */
+    store: Pick<Store, 'get' | 'set'>;
+    /**
+     * The root's translator, narrowed to what narration needs (ADR-0232 D3): `t` for what it announces, and `bcp47()` — the
+     * PAGE's language tag, read at every utterance and every voice list — because narration speaks the language of now.
+     * REQUIRED: a voice that did not know the page's language would read English words with Portuguese phonetics.
+     */
+    translator: Pick<Translator, 't' | 'bcp47'>;
     srSay: (t: string) => void;
     srAlert: (t: string) => void;
     ensureAC: () => AudioContext | null;
@@ -39,16 +33,28 @@ export interface TtsCtx {
         on: boolean;
     }> | null;
     /**
-     * COMO SE CARREGA O MOTOR NEURAL — fornecido pelo JOGO, ausente por omissão (ADR-0094).
-     *
-     * ⚠️ A engine NÃO NOMEIA O FORNECEDOR, e o motivo é medido: o `@mintplex-labs/piper-tts-web` traz
-     * `onnxruntime-web` como peer NÃO-opcional, que o npm instala sozinho — **135,4 MB** no `node_modules` de
-     * todo consumidor, incluindo um que nunca fale por voz neural. Nomeá-lo aqui obrigaria os 135 MB, e
-     * declará-lo em `devDependencies` (como estava até 06/09) publica um pacote que não compila.
-     *
-     * Ausente = a narração cai na voz do navegador (Web Speech), que fala o idioma certo e não pesa nada.
+     * DOES THIS GAME SPEAK WITH A NEURAL VOICE (ADR-0216 §3)? The game's answer, not a loader: absent, no Kokoro voice is listed, the
+     * browser's voice speaks, and the delivery carries neither the model nor the runtime.
+     */
+    neuralVoice?: boolean;
+    /**
+     * How that voice is built (ADR-0216 §1 and §5). REQUIRED (ADR-0232 D4): the root's loader reads the delivery with the host's
+     * `fetch` and WebAssembly — `import('platform/kokoro-runtime')` at the FIRST neural utterance and not before, so a game that never
+     * speaks neurally never loads a byte of espeak-ng or the ONNX runtime. A game under `createGame` never passes this — it says
+     * `uses: { neuralVoice: true }` and the engine does the rest; a case hands in a module without a wasm engine.
+     */
+    loadKokoro: LoadKokoro;
+    /** The child's speech rate, words a minute (ADR-0183 §1). Absent = each voice at its own rate. */
+    getSpeechPpm?: () => number;
+    /**
+     * Makes the element a neural utterance plays through: the root's `<audio>`, in its document. REQUIRED (ADR-0232 D4). An element,
+     * not an `AudioBufferSourceNode`: only a media element changes speed without changing pitch.
      */
-    carregarVozNeural?: CarregarVozNeural;
+    createAudio: () => HTMLAudioElement;
+    /** The browser's speech (`platform/speech`'s port), lent by the root from `host.win`. REQUIRED (ADR-0232 D4). */
+    speech: SpeechPort;
+    /** The clock a browser utterance and a neural load are timed with: the root's `performance.now`. REQUIRED (ADR-0232 D4). */
+    now: () => number;
 }
 export interface Tts {
     narrate: (text: string) => void;
@@ -64,11 +70,18 @@ export interface Tts {
     readonly failed: boolean;
     readonly narrateCount: number;
     /**
-     * ESTA MONTAGEM TEM MOTOR NEURAL? (ADR-0094) O painel de áudio pergunta antes de o oferecer: uma opção
-     * que não pode funcionar é pior que uma opção a menos — quem a escolhe fica à espera de um download que
-     * nunca começa, e quem navega por escuta não tem como ver que não começou.
+     * DOES THIS GAME ASK FOR A NEURAL ENGINE? (ADR-0216 §3) The audio panel asks before offering it: an option that cannot
+     * work is worse than one option fewer — whoever picks it waits for a download that never starts, and whoever navigates
+     * by ear has no way to see that it did not start.
      */
-    readonly neuralDisponivel: boolean;
+    readonly neuralAvailable: boolean;
+    /** The voices of the current language the child may pick (ADR-0185); empty locks the speech rows and the bar's button. */
+    voices: () => readonly NeuralVoice[];
+    /** Where the loaded Kokoro voice runs: WebGPU when its test synthesis was speech, else WASM; null before one loads. */
+    readonly kokoroDevice: 'webgpu' | 'wasm' | null;
+    /** The voice in use: the stored choice when it speaks the language, else the language's first voice, else none. */
+    currentVoice: () => NeuralVoice | null;
+    /** Stores the choice. A voice that does not speak the current language is refused (`false`). */
+    setVoice: (id: string) => boolean;
 }
 export declare function createTts(ctx: TtsCtx): Tts;
-export {};