@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/core/genres.js

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+const F = (family, names) => names.map((name) => ({ name, family }));
+export const GENRES = Object.freeze([
+    ...F('Action', ['Platform games', 'Shooter games', 'First-person shooters', 'Hero shooters', 'Light gun shooters',
+        "Shoot 'em ups", 'Fighting games', "Beat 'em up games", 'Stealth games', 'Survival games', 'Rhythm games',
+        'Battle royale games']),
+    ...F('Action-adventure', ['Survival horror', 'Metroidvania']),
+    ...F('Adventure', ['Text adventures', 'Graphic adventures', 'Visual novels', 'Interactive movie']),
+    ...F('Puzzle', ['Breakout clone game', 'Logical game', 'Physics game', 'Programming game', 'Puzzle-platform game',
+        'Hidden object game', 'Reveal the picture game', 'Tile-matching game', 'Traditional puzzle game']),
+    ...F('Role-playing', ['Action RPG', 'CRPG', 'MMORPG', 'Roguelikes', 'Tactical RPG', 'Sandbox RPG',
+        'First-person party-based RPG', 'Monster-taming']),
+    ...F('Simulation', ['Construction and management simulation', 'Life simulation', 'Vehicle simulation']),
+    ...F('Strategy', ['4X game', 'Artillery game', 'Auto battler', 'Auto chess', 'MOBA', 'RTS', 'RTT', 'Tower defense', 'TBS',
+        'TBT', 'Wargame', 'Grand strategy wargame']),
+    ...F('Sports', ['Racing', 'Sports game']),
+    ...F('MMO', ['MMO']),
+    ...F('Other notable genres', ['Board game or card game']),
+    { name: 'Casino game', family: 'Other notable genres', mark: 'refused' },
+    ...F('Other notable genres', ['Digital collectible card game', 'Digital therapeutic video game', 'Gacha game']),
+    { name: 'Horror game', family: 'Other notable genres', mark: 'avoid' },
+    ...F('Other notable genres', ['Idle game', 'Party game', 'Photography game', 'Social deduction game', 'Trivia game',
+        'Typing game']),
+].map((g) => Object.freeze(g)));
+/** Is a declared genre acceptable? EMPTY means conformant; any line refuses the boot (a malformed declaration). */
+export function genreProblems(genre) {
+    if (genre === undefined)
+        return [];
+    if (typeof genre !== 'string')
+        return ['genre: must be a genre name from the engine\'s list (ADR-0156), or absent'];
+    const g = GENRES.find((x) => x.name === genre);
+    if (!g)
+        return [`genre: «${genre}» is not in the engine's genre list (ADR-0156) - declare what the game plays like, or no genre`];
+    if (g.mark === 'refused')
+        return [`genre: Casino game is prohibited in this engine (ADR-0156 §2) - a cartridge that declares it does not boot`];
+    return [];
+}
+/** The line `problems` carries for an accepted genre with a mark: Horror game plays, and the author reads why to avoid it. */
+export function genreWarning(genre) {
+    const g = typeof genre === 'string' ? GENRES.find((x) => x.name === genre) : undefined;
+    return g?.mark === 'avoid'
+        ? `genre: Horror game is marked avoid - it is hard to make work for children (ADR-0156 §3); consider what else the game plays like`
+        : null;
+}

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

@@ -1,71 +1,82 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+/** One language's dictionary: a key and its text. */
 type LocaleDict = Record<string, string>;
+/** The languages a page can switch to — a constant, so it stays a function of the module (ADR-0232 D3). */
+export declare function availableLocales(): string[];
 /**
- * Registra as chaves DESTE jogo para um idioma. Chamável antes de o idioma existir — quem registra `en` antes
- * de qualquer `setLocale('en')` é atendido quando a troca acontecer.
- *
- * ⚠️ NÃO REAPLICA O DOM, de propósito. `applyDom` precisa de uma RAIZ, e alcançar o `document` global por
- * baixo de quem chama é o achado 15, que já custou uma correção. Um consumidor que registre depois de o
- * markup estático ter sido traduzido chama `applyDom(raiz)` ele mesmo — e o caso normal é registrar no boot,
- * antes de existir texto na tela.
- */
-export declare function registerDict(code: string, entries: LocaleDict): string[];
-export declare function t(key: string, params?: Record<string, string | number>): string;
-export declare function getLocale(): string;
-/**
- * A etiqueta BCP-47 do idioma corrente — o que se escreve em `<html lang>` e o que se entrega a APIs do
- * navegador que falam (Web Speech) ou comparam idioma.
+ * The port the chosen language is kept through (ADR-0178): `platform/storage` has this shape.
  *
- * Só o português precisa de região: 'pt' sozinho deixaria o navegador escolher entre pt-PT e pt-BR, e a
- * diferença de prosódia é audível para uma criança brasileira. Inglês e espanhol ficam sem região de
- * propósito — o navegador escolhe a variante local, que é o certo, e fixar 'en-US' imporia sotaque americano
- * a quem estivesse na Índia ou na Nigéria.
+ * 🔴 AND IT CARRIES THE BROWSER TOO (ADR-0221 step 7g): the page effects arrive as optional hooks that
+ * `platform/locale-host` builds and the composition root passes in, so `core` reaches no `document` or `window`.
  *
- * `setLocale` calculava isto em linha, ao escrever `<html lang>`. Agora os dois leem daqui: uma regra, dois
- * consumidores — que é exatamente a forma que este projeto já viu divergir quatro vezes.
+ * ⚠️ The hooks are OPTIONAL, and absent they mean «no page to tell»: a node test, a worker, a second engine in the same
+ * process.
  */
-export declare function bcp47(code?: string): string;
-export declare function availableLocales(): string[];
-export declare function applyDom(root?: ParentNode): void;
-export declare function setLocale(code: string): Promise<void>;
+export interface LocalePort {
+    get(key: string, fallback: string | null): string | null;
+    set(key: string, value: string): unknown;
+    readonly KEYS: {
+        readonly lang: string;
+    };
+    /** What the HOST does once a language is kept: `<html lang>`, re-translating the markup, telling the page. */
+    readonly applied?: (locale: string, tag: string) => void;
+    /** The language the host prefers when nothing is stored (the browser's `navigator.language`). */
+    readonly preferred?: () => string | null;
+    /**
+     * Hears a language ANOTHER root on the same page switched to — the page's signal to its host (`i18n:change`).
+     * The LANGUAGE is the page's (`<html lang>` is one attribute), so every root follows it (ADR-0232 D3 erratum point 3).
+     */
+    readonly follow?: (react: (locale: string) => void) => void;
+}
+/** What a module that only TRANSLATES receives (ADR-0232 D3): a key and its `{param}`s in, the text of the page's language out. */
+export type Translate = (key: string, params?: Record<string, string | number>) => string;
+export declare function bcp47(code: string): string;
 /**
- * Boot: aplica pt (síncrono, para a página nunca ficar em branco) e, se o idioma preferido for outro, PEDE a
- * troca — que é assíncrona, porque os outros locales são chunks sob demanda.
+ * THE TRANSLATOR A ROOT BUILDS AND HANDS DOWN (ADR-0232 D3, and its errata).
  *
- * Continua devolvendo o locale de forma síncrona e NÃO bloqueia por si: quem precisar esperar chama
- * `idiomaPronto()`. Foi essa separação que faltava — ver o comentário lá embaixo.
- *
- * `root` ENTRA em vez de ser lido do global, e foi o `boot/createGame()` que cobrou (item 13): a raiz de
- * composição recebe o documento do hospedeiro por injeção e não tinha como repassá-lo — esta linha alcançava
- * o `document` global por baixo dela. Num navegador dá no mesmo; no project `node` é a diferença entre
- * bootar contra um DOM de mentira e não bootar. O padrão continua sendo o global, então nenhum chamador
- * muda: é a mesma regra do `applyDom` logo acima.
+ * It holds everything that changes: the page's language as this root knows it, the dictionaries loaded, and the GAME's own
+ * dictionary, which no other root on the page reads. A module that only translates receives the bare `t`; one that reads or
+ * sets the language receives this object.
  */
-export declare function initI18n(root?: ParentNode): string;
+export interface Translator {
+    readonly t: Translate;
+    /** The page's language code (`pt`, `en`, `es`). */
+    readonly locale: () => string;
+    /** The BCP-47 tag of a language, the page's by default — what speech and recognition are given. */
+    readonly bcp47: (code?: string) => string;
+    /** Switches the PAGE's language; every root on the page follows (through the port's `follow`). */
+    readonly setLocale: (code: string) => Promise<void>;
+    /** Hears a language change; returns the release (the root passes this through its disposing door, ADR-0220). */
+    readonly onChange: (react: (locale: string) => void) => () => void;
+    /** Translates the declarative markup (`data-i18n`, `data-i18n-aria`) under `root`. */
+    readonly applyDom: (root: ParentNode) => void;
+    /**
+     * Boot: translates `root` in pt (synchronously, so the page is never blank) and, if the stored or preferred language is
+     * another, ASKS for the switch — asynchronous, because the other locales are on-demand chunks. Returns the locale now;
+     * whoever needs to wait calls `ready()`. `root` comes in, never the global `document` (finding 15 of `boot/create-game`).
+     */
+    readonly init: (root: ParentNode) => string;
+    /** Resolves when the language chosen at boot has loaded. */
+    readonly ready: () => Promise<void>;
+    /**
+     * Registers a game's keys for a language IN THIS TRANSLATOR — its root's dictionary, which no other root on the page
+     * reads (ADR-0232 D3 erratum); returns the refused ones (markup).
+     */
+    readonly registerDict: (code: string, entries: LocaleDict) => string[];
+    /** The keys this translator's game registered in one language and not another, for `problems` (study item E4). */
+    readonly dictionaryGaps: () => string[];
+    /**
+     * A WORD THE GAME DECLARED, by its key (ADR-0232 D3 erratum of 2026-09-25): resolved in the page's language from THIS
+     * game's dictionary, falling back to its pt — and `null` when the game's dictionary has it in neither. Never the key: a
+     * key on screen is an identifier in front of a child. Whoever draws decides what an absent word means (a row not drawn).
+     */
+    readonly word: (key: string) => string | null;
+    /** Does this game's dictionary have `key` in any language? What `problems` asks of every declared key. */
+    readonly declares: (key: string) => boolean;
+}
 /**
- * Resolve quando o idioma escolhido no boot terminou de carregar (na hora, se for pt).
- *
- * ========================= POR QUE ISTO PRECISOU EXISTIR =========================
- * O `initI18n()` do main.js era a ÚLTIMA linha do boot, depois de o HUD, os menus de título e as telas de
- * pausa já estarem montados. Para pt isso não custava nada — já estava tudo em português. Para en/es, custava
- * metade da interface: o `applyDom` conserta o markup ESTÁTICO (`data-i18n`), mas o que o JavaScript monta
- * (os botões de cenário, os de atividade) tinha capturado o texto de pt e ninguém reconstruía.
- *
- * O sintoma era desconcertante: `t('cen.cidade')` devolvia "City" e o botão na tela dizia "Cidade".
- *
- * Isto NÃO responde à pergunta maior — QUANDO a interface se reconstrói ao trocar de idioma EM EXECUÇÃO —,
- * que segue com o Dev. Responde à menor, que não tem duas respostas: a interface não se constrói antes de o
- * idioma ser conhecido.
+ * Builds a translator. `port` keeps the chosen language and tells the page (ADR-0178); without one there is no page to tell
+ * and nothing to keep, and `setLocale` refuses — a test that only translates needs none.
  */
-export declare function idiomaPronto(): Promise<void>;
-declare const i18n: {
-    t: typeof t;
-    getLocale: typeof getLocale;
-    availableLocales: typeof availableLocales;
-    applyDom: typeof applyDom;
-    setLocale: typeof setLocale;
-    initI18n: typeof initI18n;
-    idiomaPronto: typeof idiomaPronto;
-    registerDict: typeof registerDict;
-};
-export default i18n;
+export declare function createTranslator(port?: LocalePort): Translator;
+export {};

package/dist-pkg/core/i18n.js

@@ -1,236 +1,222 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// i18n — internacionalização (ver docs/plano-i18n.md).
-// O idioma padrão (pt) é import ESTÁTICO → dicionário pronto antes do game.js rodar (boot síncrono, sem
-// refatorar o init para async). Os demais entram sob demanda ao trocar de idioma, via import.meta.glob (o
-// Vite gera um chunk por locale e o SW cacheia). import.meta.glob (em vez de import(`…${code}.ts`) cru) é o
-// jeito nativo do Vite: casa arquivos .ts no build de forma explícita, sem depender do glob "adivinhado".
+// core/i18n — internationalisation.
+// The default language (pt) is a STATIC import, so its dictionary is ready before anything renders (a synchronous boot).
+// The others load on demand when the language changes, as their own chunks (see the loaders below).
+//
+// 🔴 THIS MODULE HOLDS NO STATE (ADR-0232 D3, erratum of 2026-09-25). Everything that changes — the language in use, the
+// dictionaries loaded, the game's own dictionary, who listens to a change, the boot's pending load, the port the choice is
+// kept through — lives in the TRANSLATOR a composition root builds (`createTranslator`). What stays at module level is
+// constant: the base dictionary, the list of languages, their loaders and their regions. Two roots on one page, or two
+// test files, share nothing through this module.
 import pt from '../i18n/pt.js';
-import * as store from '../platform/storage.js';
 const AVAILABLE = ['pt', 'en', 'es'];
-const base = pt; // dicionário-base (fallback), tipado
-const DICTS = { pt: base }; // dicionários já carregados (pt embutido)
-const STORE_KEY = store.KEYS.lang;
-/* ===================== O DICIONÁRIO DE QUEM CONSOME A ENGINE =====================
- *
- * O achado 2 do `consumer-quiz` dizia que os dicionários são do jogo de plataforma e que um segundo jogo
- * herda 253 chaves para usar um punhado — "peso morto no pacote". Estava certo para um consumidor que mora
- * DENTRO deste repositório, porque as chaves dele cabem em `../i18n/pt.ts`.
- *
- * ⚠️ DE FORA, O MESMO ACHADO DEIXA DE SER PESO E VIRA PAREDE. Os locales entram pelo `import.meta.glob` logo
- * abaixo, e esse glob é resolvido NO BUILD DESTA ENGINE, contra ESTA pasta. Um jogo que instala
- * `@the-inclusionist/engine` não tem como pôr arquivo lá dentro, e `DICTS` é privado. Sem esta camada ele
- * fica sem NENHUM caminho para as próprias chaves — e o pilar 3 não abre exceção para consumidor.
- *
- * CAMADA SEPARADA, e não `DICTS[code] = {...DICTS[code], ...extra}`: `DICTS.pt` É o objeto importado de
- * `../i18n/pt.ts`. Mesclar ali mutaria o dicionário da própria engine, e dois jogos na mesma página herdariam
- * as strings um do outro. `tests/i18n-consumer-dict.node.test.js` prende exatamente isso.
- */
-const EXTRA = {};
-/**
- * Registra as chaves DESTE jogo para um idioma. Chamável antes de o idioma existir — quem registra `en` antes
- * de qualquer `setLocale('en')` é atendido quando a troca acontecer.
- *
- * ⚠️ NÃO REAPLICA O DOM, de propósito. `applyDom` precisa de uma RAIZ, e alcançar o `document` global por
- * baixo de quem chama é o achado 15, que já custou uma correção. Um consumidor que registre depois de o
- * markup estático ter sido traduzido chama `applyDom(raiz)` ele mesmo — e o caso normal é registrar no boot,
- * antes de existir texto na tela.
- */
-export function registerDict(code, entries) {
-    const recusadas = [];
-    const aceites = {};
-    for (const chave in entries) {
-        if (temMarcacao(entries[chave]))
-            recusadas.push(chave);
+const base = pt; // the base dictionary (fallback), typed
+/** The languages a page can switch to — a constant, so it stays a function of the module (ADR-0232 D3). */
+export function availableLocales() { return AVAILABLE.slice(); }
+/** Puts `entries` into `layer` for `code`, refusing what carries markup (see `hasMarkup`); returns the refused keys. */
+function addEntries(layer, code, entries) {
+    const refused = [];
+    const accepted = {};
+    for (const key in entries) {
+        if (hasMarkup(entries[key]))
+            refused.push(key);
         else
-            aceites[chave] = entries[chave];
+            accepted[key] = entries[key];
     }
-    if (recusadas.length) {
-        // Alto, e não em silêncio: quem escreveu a string tem de saber que ela não entrou. Descartar calado
-        // faria a chave crua aparecer na tela sem nada explicando, e isso lê-se como defeito da engine.
+    if (refused.length) {
+        // Loud, not silent: whoever wrote the string has to know it did not go in. Dropping it quietly would put the raw
+        // key on screen with nothing explaining it, and that reads as an engine defect.
         try {
-            console.error('[inclusionist] i18n: chaves recusadas por conterem marcação — ' + recusadas.join(', '));
+            console.error('[inclusionist] i18n: keys refused because they contain markup — ' + refused.join(', '));
         }
         catch { /* noop */ }
     }
-    EXTRA[code] = { ...EXTRA[code], ...aceites };
-    return recusadas;
+    layer[code] = { ...layer[code], ...accepted };
+    return refused;
 }
 /**
- * A string traz marcação?
- *
- * ⚠️ POR QUE ISTO EXISTE AQUI, E NÃO NOS ~15 SINKS QUE CONSOMEM i18n. O gate
- * `tests/i18n-sem-markup.node.test.js` varre os dicionários DESTA árvore e prova que nenhuma entrada tem
- * tag. Ele não alcança — e não tem como alcançar — o `EXTRA`: são strings que um JOGO regista em tempo de
- * execução, de outro repositório (ADR-0083), e um teste desta árvore não as vê.
- *
- * ⚠️ E ELAS GANHAM DO DICIONÁRIO DA ENGINE. `resolver` consulta `EXTRA` primeiro, então um jogo pode sobrepor
- * QUALQUER chave — inclusive as que a engine cola em markup. Sem este cheque, «i18n» tinha deixado de
- * significar «texto que alguém desta árvore reviu», e nada registava a mudança.
- *
- * A verificação vai na FRONTEIRA e não nos sinks porque a fronteira é UMA: toda string de um jogo passa por
- * aqui. Quinze sinks seriam quinze lugares para esquecer, e o esquecimento não deixa rasto.
- *
- * O crivo é deliberadamente grosseiro — `<` seguido de letra ou de barra, e `&` de entidade. Ele recusa
- * `a < b` escrito com espaço? Não: `< ` não casa. Recusa «5<10»? Não, o dígito não casa. O que ele recusa é
- * o que se parece com uma tag, e uma frase de interface que precise disso precisa de outra frase.
+ * THE KEYS A CARTRIDGE REGISTERED IN ONE OF THE THREE LANGUAGES AND NOT IN ANOTHER (study item E4; ADR-0010 pillar 3),
+ * one line per missing language, for `problems`. 📏 Measured: the games that register a dictionary do it in pt, en and es,
+ * and nothing checked it — a key forgotten in one language shows Portuguese there, and nobody is told.
+ * A cartridge that registered nothing is not accused: strings it never gave the engine, the engine cannot see.
  */
-function temMarcacao(valor) {
-    return typeof valor === 'string' && (/<[a-zA-Z/!?]/.test(valor) || /&[a-zA-Z#][a-zA-Z0-9]*;/.test(valor));
+function gapsIn(layer) {
+    const registered = new Set();
+    for (const code of AVAILABLE)
+        for (const key in layer[code] ?? {})
+            registered.add(key);
+    if (!registered.size)
+        return [];
+    const SHOW = 5;
+    const gapLines = [];
+    for (const code of AVAILABLE) {
+        const missing = [...registered].filter((key) => !(key in (layer[code] ?? {})));
+        if (!missing.length)
+            continue;
+        const rest = missing.length > SHOW ? ` (and ${missing.length - SHOW} more)` : '';
+        gapLines.push(`the cartridge's dictionary lacks ${code} for ${missing.slice(0, SHOW).join(', ')}${rest}: `
+            + `a child playing in ${code} reads the fallback there (CreateGameOptions.dictionaries)`);
+    }
+    return gapLines;
 }
 /**
- * A cadeia de resolução, em cinco degraus. Ela ESPELHA a que já existia (`locale → pt → a própria chave`),
- * com o consumidor colado a cada degrau em vez de empilhado por cima:
+ * Does a string carry markup?
+ *
+ * ⚠️ WHY THIS LIVES HERE, AND NOT IN THE ~15 SINKS THAT CONSUME i18n. The gate `tests/i18n-without-markup.node.test.js`
+ * sweeps THIS tree's dictionaries and proves no entry has a tag. It does not reach — and cannot reach — a game's own
+ * dictionary: those are strings a GAME registers at run time, from another repository (ADR-0083), and a test in this tree
+ * never sees them.
  *
- *   1. consumidor no idioma corrente · 2. engine no idioma corrente ·
- *   3. consumidor em pt · 4. engine em pt · 5. a própria chave
+ * ⚠️ AND THEY WIN OVER THE ENGINE'S DICTIONARY. The resolver looks at the game's dictionary first, so a game can override
+ * ANY key — including the ones the engine pastes into markup. Without this check "i18n" would have stopped meaning "text
+ * someone in this tree reviewed", and nothing would record the change.
  *
- * O degrau 3 é o que faz um jogo que só escreveu pt seguir LEGÍVEL quando a criança troca para inglês: ela lê
- * português, exatamente como já lê hoje quando falta chave na engine. Degradar é melhor que calar, e é a
- * mesma escolha que o `.catch` mudo do `initI18n` já faz para o chunk que não carrega.
+ * The check sits at the BOUNDARY and not in the sinks because the boundary is ONE: every string from a game passes here.
  *
- * O degrau 2 vir ANTES do 3 é a única ordem defensável: idioma certo da engine vale mais que idioma errado do
- * consumidor. A inversão daria "Potência de 2" numa interface em espanhol que tinha a tradução na mão.
+ * The sieve is deliberately coarse — `<` followed by a letter or a slash, and `&` of an entity. `a < b` with a space and
+ * "5<10" pass; what it refuses is what looks like a tag, and an interface sentence that needs one needs another sentence.
  */
-function resolver(key) {
-    const doJogo = EXTRA[locale];
-    if (doJogo && key in doJogo)
-        return doJogo[key];
-    if (key in dict)
-        return dict[key];
-    const doJogoEmPt = EXTRA.pt;
-    if (doJogoEmPt && key in doJogoEmPt)
-        return doJogoEmPt[key];
-    return key in base ? base[key] : key;
+function hasMarkup(value) {
+    return typeof value === 'string' && (/<[a-zA-Z/!?]/.test(value) || /&[a-zA-Z#][a-zA-Z0-9]*;/.test(value));
 }
-/* ===================== OS CARREGADORES, E POR QUE DEIXARAM DE SER UM GLOB =====================
- *
- * Isto era `import.meta.glob<{default: LocaleDict}>('../i18n/*.ts')`, e a razão escrita no topo do arquivo
- * continua verdadeira para este repositório: o Vite gera um chunk por locale e o service worker o cacheia.
+/* ===================== THE LOADERS, AND WHY THEY ARE NOT A GLOB =====================
  *
- * ⚠️ O QUE MUDOU FOI O DESTINO DO ARQUIVO, NÃO O ARGUMENTO. Medido em 2026-09-05 no primeiro build de
- * pacote (`tsc -p tsconfig.pkg.json`): a linha SOBREVIVE ao emit, intacta, em `dist-pkg/core/i18n.js` —
- * e ali ela é falsa em dois níveis ao mesmo tempo.
- *   · O `tsc` não é o Vite: ele copia `import.meta.glob(...)` como chamada comum. Num consumidor que não
- *     transforme o módulo, `import.meta.glob` é `undefined` e a chamada estoura no carregamento.
- *   · E mesmo transformado, o padrão diz `*.ts` — ao lado do arquivo EMITIDO só existem `.js`. O glob casaria
- *     zero arquivos, `ensure()` cairia no `return base`, e todo idioma que não fosse pt viraria português
- *     SEM ERRO NENHUM. É o modo de falhar que este projeto já pagou uma vez, quando uma regex morreu em
- *     silêncio com a checagem verde.
+ * This used to be `import.meta.glob('../i18n/*.ts')`. ⚠️ In the PACKAGE build (`tsc -p tsconfig.pkg.json`) that line
+ * survives the emit intact, and there it is false twice over: `tsc` copies `import.meta.glob(...)` as an ordinary call
+ * (undefined in a consumer that does not transform the module), and the pattern says `*.ts` next to emitted `.js` files —
+ * every language but pt would silently become Portuguese.
  *
- * ENUMERADO, ENTÃO — e o preço é MENOR do que eu escrevi antes de medir. O glob varria três arquivos que a
- * constante `AVAILABLE` logo acima JÁ ENUMERA, então não havia descoberta nenhuma a preservar.
- *
- * ⚠️ E O CODE-SPLITTING NÃO SE PERDE, o que eu tinha suposto que se perderia. O que o Vite divide é o
- * `import()` DINÂMICO, e ele continua aqui — a primeira versão deste comentário dizia que o custo eram
- * "~63 KB de parse a mais", e o build de 2026-09-05 mostrou o contrário na saída: `dist/assets/en-*.js`
- * (24,8 KB) e `dist/assets/es-*.js` (26,7 KB) seguem como chunks próprios, exatamente como com o glob. Quem
- * fica em pt nunca os avalia. O custo real é UM: três linhas a manter à mão no dia em que entrar um quarto
- * idioma — e `AVAILABLE` já era essa lista, então é o mesmo dia e o mesmo arquivo. */
+ * ENUMERATED, THEN — and code splitting is not lost, because what Vite splits is the dynamic `import()`: `en` and `es`
+ * still ship as their own chunks, and a child who stays in pt never evaluates them. The one cost is three lines to keep
+ * by hand the day a fourth language arrives — the same day and the same file as `AVAILABLE`. */
 const loaders = {
     en: () => import('../i18n/en.js'),
     es: () => import('../i18n/es.js'),
 };
-let locale = 'pt';
-let dict = base;
-// Traduz uma chave; a cadeia de fallback está em `resolver()` logo acima. Interpola {param}.
-export function t(key, params) {
-    let s = resolver(key);
+/** Interpolates `{param}` into a resolved string. */
+function interpolate(s, params) {
     if (params)
         for (const k in params)
             s = s.replaceAll('{' + k + '}', String(params[k]));
     return s;
 }
-export function getLocale() { return locale; }
 /**
- * A etiqueta BCP-47 do idioma corrente — o que se escreve em `<html lang>` e o que se entrega a APIs do
- * navegador que falam (Web Speech) ou comparam idioma.
- *
- * Só o português precisa de região: 'pt' sozinho deixaria o navegador escolher entre pt-PT e pt-BR, e a
- * diferença de prosódia é audível para uma criança brasileira. Inglês e espanhol ficam sem região de
- * propósito — o navegador escolhe a variante local, que é o certo, e fixar 'en-US' imporia sotaque americano
- * a quem estivesse na Índia ou na Nigéria.
+ * THE BCP-47 TAG OF A LANGUAGE — what `<html lang>` says and what the browser's speech and recognition are given.
  *
- * `setLocale` calculava isto em linha, ao escrever `<html lang>`. Agora os dois leem daqui: uma regra, dois
- * consumidores — que é exatamente a forma que este projeto já viu divergir quatro vezes.
+ * Each language carries the REGION its flag stands for (the Dev, 2026-09-16: «Brasil, Estados Unidos e México. Cada bandeira indica a
+ * localização para qual o app está configurado»): pt-BR, en-US, es-MX. Voices are still matched on the language alone
+ * (`voicesForLocale`), so a region narrows nothing a child can hear. A translator answers it for the page's language.
  */
-export function bcp47(code = locale) { return code === 'pt' ? 'pt-BR' : code; }
-export function availableLocales() { return AVAILABLE.slice(); }
-// Aplica as traduções declarativas do HTML: [data-i18n] → textContent; [data-i18n-aria] → aria-label.
-export function applyDom(root = document) {
-    root.querySelectorAll('[data-i18n]').forEach((el) => { const k = el.getAttribute('data-i18n'); if (k)
-        el.textContent = t(k); });
-    root.querySelectorAll('[data-i18n-aria]').forEach((el) => { const k = el.getAttribute('data-i18n-aria'); if (k)
-        el.setAttribute('aria-label', t(k)); });
-}
-async function ensure(code) {
-    if (DICTS[code])
-        return DICTS[code];
-    const load = loaders[code];
-    if (!load)
-        return base; // idioma sem arquivo → cai no pt
-    const mod = await load();
-    DICTS[code] = mod.default;
-    return DICTS[code];
-}
-// Troca o idioma (carrega sob demanda), persiste, atualiza <html lang>, reaplica o DOM e avisa a UI.
-export async function setLocale(code) {
-    if (!AVAILABLE.includes(code))
-        code = 'pt';
-    dict = await ensure(code);
-    locale = code;
-    store.set(STORE_KEY, code);
-    document.documentElement.lang = bcp47(code);
-    applyDom(document);
-    window.dispatchEvent(new CustomEvent('i18n:change', { detail: { locale } }));
-}
-function pickDefault() {
-    const saved = store.get(STORE_KEY, null);
-    if (saved && AVAILABLE.includes(saved))
-        return saved;
-    const nav = ((navigator.language || 'pt').slice(0, 2)).toLowerCase();
-    return AVAILABLE.includes(nav) ? nav : 'pt';
-}
-/** Promessa do carregamento pedido no boot. Resolve na hora quando o idioma é pt (dicionário estático). */
-let pendente = Promise.resolve();
+const REGION_OF = { pt: 'pt-BR', en: 'en-US', es: 'es-MX' };
+export function bcp47(code) { return REGION_OF[code] ?? code; }
 /**
- * Boot: aplica pt (síncrono, para a página nunca ficar em branco) e, se o idioma preferido for outro, PEDE a
- * troca — que é assíncrona, porque os outros locales são chunks sob demanda.
- *
- * Continua devolvendo o locale de forma síncrona e NÃO bloqueia por si: quem precisar esperar chama
- * `idiomaPronto()`. Foi essa separação que faltava — ver o comentário lá embaixo.
- *
- * `root` ENTRA em vez de ser lido do global, e foi o `boot/createGame()` que cobrou (item 13): a raiz de
- * composição recebe o documento do hospedeiro por injeção e não tinha como repassá-lo — esta linha alcançava
- * o `document` global por baixo dela. Num navegador dá no mesmo; no project `node` é a diferença entre
- * bootar contra um DOM de mentira e não bootar. O padrão continua sendo o global, então nenhum chamador
- * muda: é a mesma regra do `applyDom` logo acima.
+ * Builds a translator. `port` keeps the chosen language and tells the page (ADR-0178); without one there is no page to tell
+ * and nothing to keep, and `setLocale` refuses — a test that only translates needs none.
  */
-export function initI18n(root = document) {
-    applyDom(root);
-    const def = pickDefault();
-    // `.catch` mudo de propósito: um chunk de locale que não carrega degrada para pt, e degradar é MUITO melhor
-    // que travar o boot. Sem ele, um `await idiomaPronto()` lá fora derrubaria o jogo inteiro por causa do idioma.
-    if (def !== 'pt')
-        pendente = setLocale(def).catch(() => { });
-    return locale;
+export function createTranslator(port) {
+    let locale = 'pt';
+    let dict = base;
+    /** Dictionaries already loaded (pt built in). */
+    const loaded = { pt: base };
+    /** THIS game's dictionary. A separate layer and not a merge into `loaded`: `loaded.pt` IS the imported engine object. */
+    const own = {};
+    const listeners = new Set();
+    let pending = Promise.resolve();
+    /*
+     * The resolution chain, in five steps: 1. game in the current language · 2. engine in the current language · 3. game in pt ·
+     * 4. engine in pt · 5. the key itself. Step 3 keeps a game that only wrote pt READABLE in English (degrading beats going
+     * quiet); step 2 before step 3 because the engine's right language is worth more than the game's wrong one.
+     */
+    const resolveKey = (key) => {
+        const fromGame = own[locale];
+        if (fromGame && key in fromGame)
+            return fromGame[key];
+        if (key in dict)
+            return dict[key];
+        const fromGameInPt = own.pt;
+        if (fromGameInPt && key in fromGameInPt)
+            return fromGameInPt[key];
+        return key in base ? base[key] : key;
+    };
+    const t = (key, params) => interpolate(resolveKey(key), params);
+    const applyDom = (root) => {
+        root.querySelectorAll('[data-i18n]').forEach((el) => { const k = el.getAttribute('data-i18n'); if (k)
+            el.textContent = t(k); });
+        root.querySelectorAll('[data-i18n-aria]').forEach((el) => { const k = el.getAttribute('data-i18n-aria'); if (k)
+            el.setAttribute('aria-label', t(k)); });
+    };
+    const ensure = async (code) => {
+        if (loaded[code])
+            return loaded[code];
+        const load = loaders[code];
+        if (!load)
+            return base; // a language with no file → falls back to pt
+        const mod = await load();
+        loaded[code] = mod.default;
+        return loaded[code];
+    };
+    const tellListeners = () => {
+        for (const listener of [...listeners]) {
+            try {
+                listener(locale);
+            }
+            catch { /* a listener failed; the language changed */ }
+        }
+    };
+    const setLocale = async (requested) => {
+        // first, before anything changes: a language switched and then refused would leave the page half moved (ADR-0178)
+        if (!port)
+            throw new Error('core/i18n: setLocale on a translator without a port — the composition root builds it with the stored settings (ADR-0178)');
+        const code = AVAILABLE.includes(requested) ? requested : 'pt';
+        dict = await ensure(code);
+        locale = code;
+        port.set(port.KEYS.lang, code);
+        // 📌 The three page effects — `<html lang>`, re-translating the markup, telling the page — in ONE call to the host, which
+        // is what keeps this module free of `document` and `window` (ADR-0173, ADR-0221 step 7g).
+        port.applied?.(locale, bcp47(code));
+        tellListeners();
+    };
+    // 📌 ANOTHER ROOT SWITCHED THE PAGE: this one follows without keeping or telling again — the root that switched did both.
+    port?.follow?.((code) => {
+        if (code === locale || !AVAILABLE.includes(code))
+            return;
+        void ensure(code).then((d) => { dict = d; locale = code; tellListeners(); });
+    });
+    const pickDefault = () => {
+        const saved = port ? port.get(port.KEYS.lang, null) : null;
+        if (saved && AVAILABLE.includes(saved))
+            return saved;
+        const nav = ((port?.preferred?.() || 'pt').slice(0, 2)).toLowerCase();
+        return AVAILABLE.includes(nav) ? nav : 'pt';
+    };
+    const init = (root) => {
+        applyDom(root);
+        const def = pickDefault();
+        // A silent `.catch` on purpose: a locale chunk that fails to load degrades to pt, and degrading is FAR better than
+        // freezing the boot. Without it, an `await ready()` outside would bring the whole game down over the language.
+        if (def !== 'pt')
+            pending = setLocale(def).catch(() => { });
+        return locale;
+    };
+    const word = (key) => {
+        const inLocale = own[locale];
+        if (inLocale && key in inLocale)
+            return inLocale[key];
+        const inPt = own.pt;
+        return inPt && key in inPt ? inPt[key] : null;
+    };
+    return {
+        t,
+        locale: () => locale,
+        bcp47: (code = locale) => bcp47(code),
+        setLocale,
+        onChange: (react) => { listeners.add(react); return () => { listeners.delete(react); }; },
+        applyDom,
+        init,
+        ready: () => pending,
+        registerDict: (code, entries) => addEntries(own, code, entries),
+        dictionaryGaps: () => gapsIn(own),
+        word,
+        declares: (key) => Object.values(own).some((entries) => key in entries),
+    };
 }
-/**
- * Resolve quando o idioma escolhido no boot terminou de carregar (na hora, se for pt).
- *
- * ========================= POR QUE ISTO PRECISOU EXISTIR =========================
- * O `initI18n()` do main.js era a ÚLTIMA linha do boot, depois de o HUD, os menus de título e as telas de
- * pausa já estarem montados. Para pt isso não custava nada — já estava tudo em português. Para en/es, custava
- * metade da interface: o `applyDom` conserta o markup ESTÁTICO (`data-i18n`), mas o que o JavaScript monta
- * (os botões de cenário, os de atividade) tinha capturado o texto de pt e ninguém reconstruía.
- *
- * O sintoma era desconcertante: `t('cen.cidade')` devolvia "City" e o botão na tela dizia "Cidade".
- *
- * Isto NÃO responde à pergunta maior — QUANDO a interface se reconstrói ao trocar de idioma EM EXECUÇÃO —,
- * que segue com o Dev. Responde à menor, que não tem duas respostas: a interface não se constrói antes de o
- * idioma ser conhecido.
- */
-export function idiomaPronto() { return pendente; }
-const i18n = { t, getLocale, availableLocales, applyDom, setLocale, initI18n, idiomaPronto, registerDict };
-export default i18n;
-if (typeof window !== 'undefined')
-    window.__i18n = i18n; // exposto p/ teste/preview