@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/core/i18n.js

@@ -1,162 +1,179 @@
 // 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).
 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.
+const base = pt; // the base dictionary (fallback), typed
+const DICTS = { pt: base }; // dictionaries already loaded (pt built in)
+let localePort = null;
+/** Gives this module the port for the chosen language; the composition root calls it before `initI18n`. */
+export function loadLocale(p) { localePort = p; }
+/* ===================== THE DICTIONARY OF WHOEVER CONSUMES THE ENGINE =====================
+ *
+ * ⚠️ FROM OUTSIDE, THE ENGINE'S DICTIONARIES ARE A WALL. The locales are resolved AT THIS ENGINE'S BUILD, against THIS
+ * folder. A game that installs `@the-inclusionist/engine` cannot put a file in there, and `DICTS` is private. Without
+ * this layer it would have NO way to its own keys — and pillar 3 makes no exception for a consumer.
  *
- * ⚠️ 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.
+ * A SEPARATE LAYER, and not `DICTS[code] = {...DICTS[code], ...extra}`: `DICTS.pt` IS the object imported from
+ * `../i18n/pt.ts`. Merging there would mutate the engine's own dictionary, and two games on the same page would inherit
+ * each other's strings. `tests/i18n-consumer-dict.node.test.js` pins exactly that.
  */
-export function registerDict(code, entries) {
-    const recusadas = [];
-    const aceites = {};
-    for (const chave in entries) {
-        if (temMarcacao(entries[chave]))
-            recusadas.push(chave);
+const EXTRA = {};
+/** 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;
+}
+/**
+ * Registers THIS game's keys for a language. Callable before the language exists — whoever registers `en` before any
+ * `setLocale('en')` is served when the switch happens.
+ *
+ * ⚠️ IT DOES NOT RE-APPLY THE DOM, on purpose. `applyDom` needs a ROOT, and reaching the global `document` under the
+ * caller's feet is a defect that already cost one fix. A consumer registering after the static markup was translated
+ * calls `applyDom(root)` itself — and the normal case is to register at boot, before any text is on screen.
+ */
+export function registerDict(code, entries) {
+    return addEntries(EXTRA, code, entries);
+}
+/**
+ * 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.
+ * Over `layers` taken together — a translator asks it for its root's dictionary (ADR-0232 D3).
+ */
+function gapsIn(layers) {
+    const registered = new Set();
+    for (const layer of layers)
+        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) => !layers.some((layer) => 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 (registerDict)`);
+    }
+    return gapLines;
 }
 /**
- * A string traz marcação?
+ * Does a string carry markup?
  *
- * ⚠️ 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ê.
+ * ⚠️ 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 — `EXTRA`: those
+ * are strings a GAME registers at run time, from another repository (ADR-0083), and a test in this tree never sees them.
  *
- * ⚠️ 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.
+ * ⚠️ AND THEY WIN OVER THE ENGINE'S DICTIONARY. The resolver looks at `EXTRA` 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.
  *
- * 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.
+ * The check sits at the BOUNDARY and not in the sinks because the boundary is ONE: every string from a game passes
+ * here. Fifteen sinks would be fifteen places to forget, and forgetting leaves no trace.
  *
- * 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 sieve is deliberately coarse — `<` followed by a letter or a slash, and `&` of an entity. Does it refuse `a < b`
+ * written with a space? No: `< ` does not match. "5<10"? No, the digit does not match. What it refuses is what looks
+ * like a tag, and an interface sentence that needs one needs another sentence.
  */
-function temMarcacao(valor) {
-    return typeof valor === 'string' && (/<[a-zA-Z/!?]/.test(valor) || /&[a-zA-Z#][a-zA-Z0-9]*;/.test(valor));
+function hasMarkup(value) {
+    return typeof value === 'string' && (/<[a-zA-Z/!?]/.test(value) || /&[a-zA-Z#][a-zA-Z0-9]*;/.test(value));
 }
 /**
- * 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:
+ * The resolution chain, in five steps. It MIRRORS the one that already existed (`locale → pt → the key itself`), with
+ * the consumer glued to each step instead of stacked on top:
  *
- *   1. consumidor no idioma corrente · 2. engine no idioma corrente ·
- *   3. consumidor em pt · 4. engine em pt · 5. a própria chave
+ *   1. consumer in the current language · 2. engine in the current language ·
+ *   3. consumer in pt · 4. engine in pt · 5. the key itself
  *
- * 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.
+ * Step 3 is what keeps a game that only wrote pt READABLE when the child switches to English: they read Portuguese,
+ * exactly as they already do when the engine lacks a key. Degrading beats going quiet, the same choice the silent
+ * `.catch` in `initI18n` makes for a chunk that does not load.
  *
- * 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.
+ * Step 2 coming BEFORE step 3 is the only defensible order: the engine's right language is worth more than the
+ * consumer's wrong one. Inverting it would show Portuguese in a Spanish interface that had the translation to hand.
  */
-function resolver(key) {
-    const doJogo = EXTRA[locale];
-    if (doJogo && key in doJogo)
-        return doJogo[key];
+function resolveKey(key, layers = [EXTRA]) {
+    for (const layer of layers) {
+        const fromGame = layer[locale];
+        if (fromGame && key in fromGame)
+            return fromGame[key];
+    }
     if (key in dict)
         return dict[key];
-    const doJogoEmPt = EXTRA.pt;
-    if (doJogoEmPt && key in doJogoEmPt)
-        return doJogoEmPt[key];
+    for (const layer of layers) {
+        const fromGameInPt = layer.pt;
+        if (fromGameInPt && key in fromGameInPt)
+            return fromGameInPt[key];
+    }
     return key in base ? base[key] : key;
 }
-/* ===================== 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.
- *
- * ⚠️ 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.
- *
- * 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. */
+/* ===================== THE LOADERS, AND WHY THEY ARE NOT A GLOB =====================
+ *
+ * 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` is not Vite: it copies `import.meta.glob(...)` as an ordinary call. In a consumer that does not transform
+ *     the module, `import.meta.glob` is `undefined` and the call blows up on load.
+ *   · And even transformed, the pattern says `*.ts` — next to the EMITTED file there are only `.js` files. The glob
+ *     would match nothing, `ensure()` would fall to `return base`, and every language but pt would become Portuguese
+ *     WITHOUT ANY ERROR — the silent failure mode this project already paid for once.
+ *
+ * ENUMERATED, THEN — and it costs little: the glob swept three files that `AVAILABLE` above ALREADY lists. Code
+ * splitting is not lost either, because what Vite splits is the dynamic `import()`, which stays: `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;
 }
+// Translates a key; the fallback chain is in `resolveKey()` above. Interpolates {param}.
+export function t(key, params) {
+    return interpolate(resolveKey(key), params);
+}
 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.
+ * THE BCP-47 TAG OF THE CURRENT LANGUAGE — what `<html lang>` says and what the browser's speech and recognition are given.
  *
- * 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.
- *
- * `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. It was pt-BR with `en` and `es` bare, so the browser picked the
+ * variant; the language button now states the place. Voices are still matched on the language alone (`voicesForLocale`), so a region
+ * narrows nothing a child can hear.
  */
-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) {
+const REGION_OF = { pt: 'pt-BR', en: 'en-US', es: 'es-MX' };
+export function bcp47(code = locale) { return REGION_OF[code] ?? code; }
+function availableLocales() { return AVAILABLE.slice(); }
+// Applies the declarative translations of the markup: [data-i18n] → textContent; [data-i18n-aria] → aria-label.
+function 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)
@@ -167,70 +184,106 @@ async function ensure(code) {
         return DICTS[code];
     const load = loaders[code];
     if (!load)
-        return base; // idioma sem arquivo → cai no pt
+        return base; // a language with no file → falls back to 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.
+// Switches the language (loading on demand), keeps it, and hands the page effects to the host.
 export async function setLocale(code) {
+    // first, before anything changes: a language switched and then refused would leave the page half moved (ADR-0178)
+    const port = localePort;
+    if (!port)
+        throw new Error('core/i18n: setLocale kept a language before loadLocale — the composition root loads the stored settings first (ADR-0178)');
     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 } }));
+    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));
+    // and then every translator's listeners, each root's through its own disposing door (ADR-0232 D3, ADR-0220)
+    for (const listener of [...changeListeners]) {
+        try {
+            listener(locale);
+        }
+        catch { /* a listener failed; the language changed */ }
+    }
 }
+/** Who hears a language change — the PAGE's, as the language is (ADR-0232 D3 erratum): each translator subscribes here. */
+const changeListeners = new Set();
 function pickDefault() {
-    const saved = store.get(STORE_KEY, null);
+    const saved = localePort ? localePort.get(localePort.KEYS.lang, null) : null;
     if (saved && AVAILABLE.includes(saved))
         return saved;
-    const nav = ((navigator.language || 'pt').slice(0, 2)).toLowerCase();
+    const nav = ((localePort?.preferred?.() || '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();
+/** The promise of the load asked for at boot. Resolves at once when the language is pt (static dictionary). */
+let pending = Promise.resolve();
 /**
- * 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.
+ * Boot: applies pt (synchronously, so the page is never blank) and, if the preferred language is another, ASKS for the
+ * switch — which is asynchronous, because the other locales are on-demand chunks.
  *
- * 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.
+ * It still returns the locale synchronously and does NOT block on its own: whoever needs to wait calls `localeReady()`.
  *
- * `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.
+ * `root` COMES IN instead of being read from the global: the composition root receives the host's document by
+ * injection and had no way to pass it on while this line reached the global `document` under it. In a browser it is
+ * the same; in the `node` project it is the difference between booting against a fake DOM and not booting.
  */
-export function initI18n(root = document) {
+export function initI18n(root) {
     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.
+    // 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 localeReady()` outside would bring the whole game down over the language.
     if (def !== 'pt')
-        pendente = setLocale(def).catch(() => { });
+        pending = setLocale(def).catch(() => { });
     return locale;
 }
 /**
- * Resolve quando o idioma escolhido no boot terminou de carregar (na hora, se for pt).
+ * Resolves when the language chosen at boot has finished loading (at once, if it is 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.
+ * ========================= WHY THIS HAD TO EXIST =========================
+ * When the language loaded LAST, after the HUD and the menus were built, pt cost nothing — and en/es cost half the
+ * interface: `applyDom` fixes the STATIC markup (`data-i18n`), but what JavaScript builds had captured the pt text and
+ * nobody rebuilt it. `t()` answered "City" and the button on screen said "Cidade".
  *
- * O sintoma era desconcertante: `t('cen.cidade')` devolvia "City" e o botão na tela dizia "Cidade".
+ * This answers the narrow question, which has one answer: the interface is not built before the language is known.
+ * Switching language AT RUN TIME is a different question, answered by the redraw on `i18n:change` (ADR-0225).
+ */
+export function localeReady() { return pending; }
+/**
+ * Builds a translator, with a game dictionary of its OWN (ADR-0232 D3 erratum): what one root registers, another root on the
+ * same page does not read. The language stays the page's.
  *
- * 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.
+ * ⚠️ TRANSITIONAL: after its own dictionary it still reads the page-wide one that the module-level `registerDict` writes,
+ * so a game that registers there before `createGame` keeps its words — until the Dev decides how a game translates what it
+ * declares, and the module-level `t` and `registerDict` leave (issue #207).
  */
-export function idiomaPronto() { return pendente; }
-const i18n = { t, getLocale, availableLocales, applyDom, setLocale, initI18n, idiomaPronto, registerDict };
+export function createTranslator() {
+    const own = {};
+    const layers = [own, EXTRA];
+    const tr = (key, params) => interpolate(resolveKey(key, layers), params);
+    const applyTo = (root) => {
+        root.querySelectorAll('[data-i18n]').forEach((el) => { const k = el.getAttribute('data-i18n'); if (k)
+            el.textContent = tr(k); });
+        root.querySelectorAll('[data-i18n-aria]').forEach((el) => { const k = el.getAttribute('data-i18n-aria'); if (k)
+            el.setAttribute('aria-label', tr(k)); });
+    };
+    return {
+        t: tr,
+        locale: () => locale,
+        bcp47,
+        setLocale,
+        onChange: (react) => { changeListeners.add(react); return () => { changeListeners.delete(react); }; },
+        applyDom: applyTo,
+        ready: () => pending,
+        registerDict: (code, entries) => addEntries(own, code, entries),
+        dictionaryGaps: () => gapsIn(layers),
+    };
+}
+const i18n = { t, getLocale, availableLocales, applyDom, setLocale, initI18n, localeReady, registerDict };
 export default i18n;
-if (typeof window !== 'undefined')
-    window.__i18n = i18n; // exposto p/ teste/preview
+// 🔴 Exposing this on `window.__i18n` is not done here (ADR-0221 step 7g): hanging off a window is the job of whoever
+// HAS one. `platform/locale-host.exposeI18n` does it, called by the root — and the object exposed is exactly this default.

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

@@ -4,14 +4,25 @@ type Ticker = {
     deltaTime: number;
     remove?: (fn: () => void) => void;
 };
-export interface OpcoesDoLaco {
+export interface LoopOptions {
     /**
-     * Chamado UMA vez, com o erro, quando o quadro lança. É o canal de quem não enxerga a tela parar.
+     * THE GAME SPEED the child chose (ADR-0180): 1 is 100%, down to 0.5. Read EACH FRAME, so a change is felt on the next
+     * one. A game beside `createGame` passes `engine.gameSpeed`; a game that is its own root passes
+     * `() => state.gameSpeed`.
      *
-     * A raiz de composição liga isto ao `srAlert` e a uma mensagem visível. Opcional de propósito: um consumidor
-     * que monte o laço sem casca (um teste, o quiz) continua parando — o anúncio é opcional, **parar não é**.
+     * 🔴 REQUIRED (ADR-0232 D2c erratum; ADR-0224/0227's precedent): the loop no longer reads the settings store by import,
+     * and an optional port defaulting to 100% would ignore the child's choice in every game that forgot it — silently.
      */
-    aoFalhar?: (erro: unknown) => void;
+    speed: () => number;
+    /**
+     * Called ONCE, with the error, when the frame throws. It is the channel of whoever cannot see the screen stop.
+     *
+     * A game beside `createGame` passes `engine.onFailure` (the screen reader, the narration and a visible message); a game
+     * that is its own root passes its own. 🔴 REQUIRED (ADR-0232 D4; the D2b erratum rejected the registration shape): the
+     * root used to register a default notice in this module, which was module state a second root overwrote, and an optional
+     * port is one more field a game forgets — a frame that stopped in silence is what a blind child cannot tell from a pause.
+     */
+    onFailure: (failure: unknown) => void;
 }
-export declare function startLoop(ticker: Ticker, frame: (dt: number) => void, maxDt?: number, opcoes?: OpcoesDoLaco): void;
+export declare function startLoop(ticker: Ticker, frame: (dt: number) => void, maxDt: number | undefined, options: LoopOptions): void;
 export {};

package/dist-pkg/core/loop.js

@@ -1,36 +1,36 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// core/loop.ts — driver do loop de jogo. Registra a função de frame num "ticker" (o app.ticker do PixiJS, ou
-// qualquer objeto com .add(fn) e .deltaTime) e passa o dt CLAMPADO (evita saltos gigantes após a aba ficar em
-// segundo plano). Módulo-folha. Mantém a cadência ATUAL (não muda o timing) — o fixed-timestep determinístico
-// fica para depois, pois mudaria a física.
+// core/loop.ts — the game loop driver. Registers the frame function on a "ticker" (PixiJS's app.ticker, or any object
+// with .add(fn) and .deltaTime) and passes a CLAMPED dt (no giant jump after the tab was in the background). A leaf
+// module. It keeps the CURRENT cadence — a deterministic fixed timestep would change the physics, so it waits.
 //
-// ========================= O BOUNDARY DE ERRO (D16), E POR QUE ELE FALHA ALTO =========================
-// Sem ele, um quadro que lança lança OUTRA VEZ no quadro seguinte, para sempre: tela congelada, console cheio, e
-// nada na tela dizendo o que houve. A spec do `demos` pede isto por escala — "across 383 games, one bad game has
-// to be distinguishable from a broken engine". A razão daqui é mais urgente: **criança cega não vê tela
-// congelada.** Sem anúncio, o modo cego não distingue "travou" de "está pensando".
+// ========================= THE ERROR BOUNDARY (D16), AND WHY IT FAILS LOUD =========================
+// Without it, a frame that throws throws AGAIN on the next frame, forever: a frozen screen, a full console, and nothing
+// on screen saying what happened. The `demos` spec asks for it by scale — "across 383 games, one bad game has to be
+// distinguishable from a broken engine". The reason here is more urgent: **a blind child does not see a frozen
+// screen.** Without an announcement, blind mode cannot tell "it froze" from "it is thinking".
 //
-// ⚠️ E A TENTAÇÃO É O CONTRÁRIO DO CONSERTO. `try { frame() } catch { /* segue */ }` é pior que o defeito: vira
-// jogo silenciosamente errado, rodando para sempre computando lixo. A regra aqui é a mesma que o ADR-0047 aplicou
-// ao CRT — pega UMA vez, PARA, e ANUNCIA.
-export function startLoop(ticker, frame, maxDt = 2, opcoes = {}) {
-    let parado = false;
-    const passo = () => {
-        if (parado)
-            return; // ticker sem `remove` não desregistra — a trava é o que faz o laço parar mesmo assim
+// ⚠️ AND THE TEMPTATION IS THE OPPOSITE OF THE FIX. `try { frame() } catch { /* carry on */ }` is worse than the defect:
+// it becomes a silently wrong game, computing garbage forever. The rule is the one ADR-0047 applied to the CRT — catch
+// ONCE, STOP, and ANNOUNCE.
+export function startLoop(ticker, frame, maxDt = 2, options) {
+    let stopped = false;
+    const step = () => {
+        if (stopped)
+            return; // a ticker without `remove` cannot unregister — this latch is what stops the loop anyway
         try {
-            frame(Math.min(ticker.deltaTime, maxDt));
+            // the game speed (ADR-0180) applies to the clamped time, read each frame: a change is felt on the next one
+            frame(Math.min(ticker.deltaTime, maxDt) * options.speed());
         }
-        catch (erro) {
-            parado = true;
-            ticker.remove?.(passo); // some do ticker quando dá: callback que roda 60×/s para nada custa em hardware fraco
-            // O anúncio não pode ressuscitar o problema. Se o próprio aviso quebrar — sem leitor de tela, sem DOM —,
-            // uma exceção aqui voltaria a ser invisível dentro do ticker, que é exatamente o defeito que isto fecha.
+        catch (failure) {
+            stopped = true;
+            ticker.remove?.(step); // leave the ticker when possible: a callback running 60×/s for nothing costs on weak hardware
+            // The announcement must not revive the problem. If the notice itself breaks — no screen reader, no DOM — an
+            // exception here would be invisible inside the ticker again, which is exactly the defect this closes.
             try {
-                opcoes.aoFalhar?.(erro);
+                options.onFailure(failure);
             }
-            catch { /* noop: o aviso falhou; o laço já parou, que é o essencial */ }
+            catch { /* noop: the notice failed; the loop already stopped, which is what matters */ }
         }
     };
-    ticker.add(passo);
+    ticker.add(step);
 }

package/dist-pkg/core/pause-icon-catalogue.d.ts

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+export interface PauseIcon {
+    /** `data-pi` key — the dispatch key of iconAct/iconLabel/reflectIconBtn. */
+    k: string;
+    /** The emoji glyph rendered inside the button. */
+    e: string;
+    /** i18n KEY of the base name; also the `aria-label` when the icon carries no state. */
+    n: string;
+}
+/** The accessibility shortcut bar at the top of every pause screen (and of the splash `#title-icons`).
+ *  Sound-bound icons (blind/TTS) require a private audio output; the webcam and the voice require the device to have one.
+ *  The order and behaviour came verbatim from the monolith, which left with the cartridge (#111); the names became
+ *  i18n keys in the Phase-5 pass. */
+export declare const PAUSE_ICONS: readonly PauseIcon[];
+export declare function pauseIcon(k: string): PauseIcon | undefined;