@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/input/vocabulary-migration.js

@@ -1,125 +1,126 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// input/vocabulary-migration — O ÚNICO SÍTIO DA ENGINE QUE PODE DIZER `jump`, E POR QUANTO TEMPO.
+// input/vocabulary-migration — THE ONLY PLACE IN THE ENGINE ALLOWED TO SAY `jump`, AND FOR HOW LONG.
 //
-// ========================= POR QUE ESTE MÓDULO EXISTE SEPARADO =========================
-// O gate `action-vocabulary-boundary` reprova a engine por nomear os verbos do jogo, e estava certo ao
-// reprovar esta tabela quando ela nasceu dentro de `input/keyboard.ts`. Só que a tabela PRECISA de os nomear:
-// traduzir o vocabulário antigo é literalmente a função dela.
+// ========================= WHY THIS MODULE STANDS APART =========================
+// The `action-vocabulary-boundary` gate fails the engine for naming the game's verbs, and it was right to fail
+// this table when it was born inside `input/keyboard.ts`. But the table HAS to name them: translating the old
+// vocabulary is literally its job.
 //
-// ⚠️ E A SAÍDA NÃO FOI LEVANTAR O TETO. Levantar um teto que "só encolhe" é o afrouxamento que o gate existe
-// para impedir, e uma exceção sem endereço vira precedente para a próxima. A saída foi QUARENTENAR: o
-// acoplamento inteiro mora aqui, num ficheiro cujo nome diz que ele é histórico, com um teto próprio e uma
-// data de morte.
+// ⚠️ AND THE WAY OUT WAS NOT RAISING THE CEILING. Raising a ceiling that "only shrinks" is the loosening the gate
+// exists to prevent, and an exception with no address becomes a precedent for the next one. The way out was
+// QUARANTINE: the whole coupling lives here, in a file whose name says it is historical, with a ceiling of its
+// own and a date of death.
 //
-// ⚠️ QUANDO ISTO SE APAGA: quando não restar dado salvo no formato antigo. Não há como saber isso do lado do
-// código — o dado está no navegador de cada criança —, então o critério é de tempo e é do Dev. Enquanto
-// houver, apagar este ficheiro apaga o remapeamento de quem o fez.
+// ⚠️ WHEN THIS GETS DELETED: when no data saved in the old format remains. The code side has no way to know that
+// — the data is in each child's browser — so the criterion is time, and it is the Dev's. While any remains,
+// deleting this file deletes the remapping of whoever made one.
 //
-// ========================= O QUE SE PERDE SE ISTO ESTIVER ERRADO =========================
-// Quem remapeou teclas normalmente remapeou por NECESSIDADE — alcance de mão, dedo que não estica, teclado
-// sem numpad. Um esquema salvo que deixe de casar não dá erro: as teclas simplesmente param de responder, e
-// a criança conclui que o jogo quebrou. É perda de uma adaptação, não de uma preferência.
+// ========================= WHAT IS LOST IF THIS IS WRONG =========================
+// Whoever remapped keys usually remapped out of NEED — hand reach, a finger that does not stretch, a keyboard
+// without a numpad. A saved scheme that stops matching raises no error: the keys simply stop responding, and the
+// child concludes the game is broken. It is the loss of an adaptation, not of a preference.
 /**
- * Nome de plataforma → posição abstrata. **ADR-0086 §2**, e não o ADR-0074.
+ * Platform name → abstract position. **ADR-0086 §2**, not ADR-0074.
  *
- * ⚠️ A DIFERENÇA ENTRE OS DOIS REGISTROS É A TECLA DA CRIANÇA. O ADR-0074 dizia `jump → action1` e
- * `run → action4`; o ADR-0086 corrigiu para `run → action1` e `jump → action2`, medindo que a correção é a
- * leitura CONSERVADORA — ela deixa cada verbo na tecla e no botão que já ocupava. Traduzir por engano pela
- * tabela do 0074 não daria erro nenhum: moveria o pulo de `J` para `U` em silêncio.
+ * ⚠️ THE DIFFERENCE BETWEEN THE TWO RECORDS IS THE CHILD'S KEY. ADR-0074 said `jump → action1` and
+ * `run → action4`; ADR-0086 corrected it to `run → action1` and `jump → action2`, having measured that the
+ * correction is the CONSERVATIVE reading — it leaves each verb on the key and the button it already held.
+ * Translating by mistake with 0074's table would raise no error at all: it would move jump from `J` to `U`
+ * silently.
  */
-export const VOCABULARIO_ANTIGO = Object.freeze({
+export const OLD_VOCABULARY = Object.freeze({
     run: 'action1',
     jump: 'action2',
     especial: 'action3',
     swap: 'action4',
-    // ⚠️ E UMA QUINTA ENTRADA QUE NÃO É UM VERBO DE PLATAFORMA. A camada de toque chamava `pause` a posição
-    // que todo o resto chama `start` — duas palavras para a mesma coisa, e a do toque era a única que não
-    // existia no conjunto abstrato. Um mapa de toque gravado antes disto tem `start: 'pause'` no slot do
-    // START, e sem esta linha esse botão deixaria de pausar: `decide()` passa a procurar `'start'` e
-    // receberia `'pause'`, que já não é nada — sem erro, sem aviso, e o único botão de pausa de um tablet.
+    // ⚠️ AND A FIFTH ENTRY THAT IS NOT A PLATFORM VERB. The touch layer called `pause` the position everything
+    // else calls `start` — two words for the same thing, and the touch one was the only one missing from the
+    // abstract set. A touch map saved before this has `start: 'pause'` in the START slot, and without this line
+    // that button would stop pausing: `decide()` now looks for `'start'` and would get `'pause'`, which is no
+    // longer anything — no error, no warning, and the only pause button a tablet has.
     pause: 'start',
 });
 /**
- * ⚠️ O SEGUNDO DADO SALVO, e ele quase passou. O mapa de toque (`incl_touchmap`) guarda SLOT → AÇÃO, ou seja
- * o nome da ação está no VALOR e não na chave: `{ b0: 'jump', b1: 'especial' }`. O tradutor de esquemas de
- * teclado, que traduz CHAVES, passaria por cima dele sem tocar em nada.
+ * ⚠️ THE SECOND SAVED DATA, and it nearly slipped through. The touch map (`incl_touchmap`) stores SLOT → ACTION,
+ * so the action name is in the VALUE and not the key: `{ b0: 'jump', b1: 'especial' }`. The keyboard scheme
+ * translator, which translates KEYS, would pass over it without touching anything.
  *
- * ⚠️ E O DANO SERIA PIOR DO QUE NO TECLADO. `normalizeTouchMap` funde o guardado SOBRE o padrão, então um
- * `b0: 'jump'` gravado sobrescreveria o `b0: 'action2'` correto — e o botão da tela deixaria de fazer
- * qualquer coisa. Num tablet de escola pública o toque não é o caminho alternativo: é o único.
+ * ⚠️ AND THE DAMAGE WOULD BE WORSE THAN ON THE KEYBOARD. `normalizeTouchMap` merges what is stored OVER the
+ * default, so a saved `b0: 'jump'` would overwrite the correct `b0: 'action2'` — and the on-screen button would
+ * stop doing anything. On a public-school tablet, touch is not the alternative path: it is the only one.
  *
- * Foi um teste de NAVEGADOR que o encontrou (`tests/touch.browser.test.js`), depois de a suíte `node` já
- * estar verde — o que é o argumento para os dois projetos existirem.
+ * A BROWSER test found it (`tests/touch.browser.test.js`), after the `node` suite was already green — which is
+ * the argument for having both projects.
  */
-export function migrarMapaDeToque(mapa) {
-    if (!mapa)
+export function migrateTouchMap(touchMap) {
+    if (!touchMap)
         return null;
-    const saida = {};
-    for (const [slot, acao] of Object.entries(mapa)) {
-        saida[slot] = VOCABULARIO_ANTIGO[acao] ?? acao;
+    const migrated = {};
+    for (const [slot, action] of Object.entries(touchMap)) {
+        migrated[slot] = OLD_VOCABULARY[action] ?? action;
     }
-    return saida;
+    return migrated;
 }
 /**
- * ⚠️ O TERCEIRO DADO SALVO, encontrado por varredura e não por acidente. Depois de o segundo aparecer num
- * teste de navegador, a pergunta certa deixou de ser «este está migrado?» e passou a ser «QUANTOS formatos
- * persistidos existem?». São três, e este é o do assistente de controle: `incl_padmap_<id>` guarda
- * AÇÃO → BINDING FÍSICO, `{ jump: { b: 0 }, run: { b: 2 } }`, um por modelo de controle.
+ * ⚠️ THE THIRD SAVED DATA, found by a sweep and not by accident. After the second turned up in a browser test,
+ * the right question stopped being "is this one migrated?" and became "HOW MANY persisted formats exist?". There
+ * are three, and this is the pad wizard's: `incl_padmap_<id>` stores ACTION → PHYSICAL BINDING,
+ * `{ jump: { b: 0 }, run: { b: 2 } }`, one per pad model.
  *
- * ⚠️ E ELE É O MAIS CARO DE PERDER DOS TRÊS. Um mapa desses existe porque a criança (ou quem a acompanha)
- * passou por um assistente de nove passos apertando botão a botão, provavelmente porque o controle dela não
- * é «standard» — controles genéricos e adaptados raramente são. Perdê-lo manda essa pessoa de volta ao
- * assistente inteiro.
+ * ⚠️ AND IT IS THE MOST EXPENSIVE OF THE THREE TO LOSE. Such a map exists because the child (or whoever is with
+ * them) went through the wizard pressing button after button, one step per position the game names — probably
+ * because their pad is not "standard", and generic and adapted pads rarely are. Losing it sends that person back
+ * through the whole wizard.
  *
- * `_skip` e qualquer chave desconhecida atravessam, pela mesma razão das outras duas migrações.
+ * `_skip` and any unknown key pass through, for the same reason as the other two migrations.
  */
-export function migrarMapaDeControle(mapa) {
-    if (!mapa)
+export function migrateControlMap(touchMap) {
+    if (!touchMap)
         return null;
-    const saida = {};
-    for (const [chave, valor] of Object.entries(mapa)) {
-        saida[VOCABULARIO_ANTIGO[chave] ?? chave] = valor;
+    const migrated = {};
+    for (const [key, value] of Object.entries(touchMap)) {
+        migrated[OLD_VOCABULARY[key] ?? key] = value;
     }
-    return saida;
+    return migrated;
 }
 /**
- * Traduz UM esquema salvo do vocabulário antigo para o abstrato.
+ * Translates ONE saved scheme from the old vocabulary to the abstract one.
  *
- * ⚠️ CHAVE DESCONHECIDA ATRAVESSA INTACTA, e é decisão e não descuido: `up`, `down`, `left` e `right` nunca
- * mudaram de nome, e um esquema pode carregar uma chave que este código não conhece — dado de uma versão
- * futura, ou lixo. Apagá-la seria destruir dado que não entendemos, e é o que faria as quatro direções
- * sumirem. É também o que torna esta função IDEMPOTENTE: aplicada sobre um esquema já migrado, nenhuma chave
- * casa e o resultado é igual à entrada, o que importa porque `loadKB` pode correr mais de uma vez na sessão.
+ * ⚠️ AN UNKNOWN KEY PASSES THROUGH UNTOUCHED, and that is a decision, not carelessness: `up`, `down`, `left` and
+ * `right` never changed names, and a scheme may carry a key this code does not know — data from a future
+ * version, or garbage. Deleting it would destroy data we do not understand, and it is what would make the four
+ * directions vanish. It is also what makes this function IDEMPOTENT: applied to an already migrated scheme, no
+ * key matches and the result equals the input, which matters because `loadKB` may run more than once a session.
  */
-export function migrarEsquema(esquema) {
-    if (!esquema)
+export function migrateScheme(saved) {
+    if (!saved)
         return null;
-    const saida = {};
-    for (const [chave, teclas] of Object.entries(esquema)) {
-        const nova = VOCABULARIO_ANTIGO[chave] ?? chave;
-        // ⚠️ Esquema MEIO migrado (as duas chaves presentes): a UNIÃO, nunca a sobreposição. Perder uma tecla é
-        // o dano que este módulo existe para impedir; ter a mesma tecla duas vezes não é dano nenhum.
-        saida[nova] = saida[nova] ? [...new Set([...saida[nova], ...teclas])] : [...teclas];
+    const migrated = {};
+    for (const [key, keys] of Object.entries(saved)) {
+        const newKey = OLD_VOCABULARY[key] ?? key;
+        // ⚠️ A HALF-migrated scheme (both keys present): the UNION, never the overwrite. Losing a key is the damage
+        // this module exists to prevent; having the same key twice is no damage at all.
+        migrated[newKey] = migrated[newKey] ? [...new Set([...migrated[newKey], ...keys])] : [...keys];
     }
-    return saida;
+    return migrated;
 }
-/** Traduz o objeto salvo inteiro — o esquema solo e as listas por contagem de jogadores. */
-export function migrarSalvo(s) {
+/** Translates the whole saved object — the solo scheme and the lists per player count. */
+export function migrateSaved(s) {
     if (!s)
         return null;
-    const lista = (arr) => (Array.isArray(arr) ? arr.map((m) => migrarEsquema(m)) : undefined);
+    const list = (arr) => (Array.isArray(arr) ? arr.map((m) => migrateScheme(m)) : undefined);
     const out = {};
-    const solo = migrarEsquema(s.solo);
+    const solo = migrateScheme(s.solo);
     if (solo)
         out.solo = solo;
     for (const g of ['p2', 'p3', 'p4']) {
-        const v = lista(s[g]);
+        const v = list(s[g]);
         if (v)
             out[g] = v;
     }
-    // `p34` migra de VOCABULÁRIO aqui e de FORMA em `loadKB`, que já o fazia antes deste módulo existir.
-    // Sem esta linha, o dado mais velho de todos seria o único a perder-se.
+    // `p34` migrates its VOCABULARY here and its SHAPE in `loadKB`, which already did that before this module
+    // existed. Without this line, the oldest data of all would be the only one to get lost.
     if (Array.isArray(s.p34))
-        out.p34 = s.p34.map((m) => migrarEsquema(m));
+        out.p34 = s.p34.map((m) => migrateScheme(m));
     return out;
 }

package/dist-pkg/input/voice-map.d.ts

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Action } from '../core/actions.js';
+/**
+ * Every word of one language, by position.
+ *
+ * ⚠️ WRITTEN AS THE RECOGNISER'S VOCABULARY SPELLS THEM — lowercase, with their accents (the Dev's words are «ação» and
+ * «Acción»): a grammar word the model does not know is dropped and its position goes mute (measured below). Comparing ignores
+ * accents: the reader (`platform/speech-recognition`) matches a heard sentence and a table entry by a key without them.
+ */
+export type VoiceWords = {
+    readonly [A in Action]?: readonly string[];
+};
+/** The table of the child's language. An unknown tag falls back to Portuguese, the project's base language (ADR-0010 pillar 3). */
+export declare function voiceWordsFor(language: string): VoiceWords;
+/**
+ * THE CLOSED GRAMMAR: every word the recogniser is allowed to return, and nothing else (ADR-0189, ADR-0193).
+ *
+ * 📌 A grammar is what makes 32 MiB answer in a quarter of a second, and it is also what makes it answer WRONG when a child
+ * says something that is not a command: the lab measured free speech being pushed to the nearest word («configurações de
+ * inclusão» → «quatro»). That is the cost of the closed list and the reason the words are short and unlike each other.
+ * ⚠️ `extra` is what the MENU is showing right now (ADR-0194): saying the name of an item activates it, so those words join the
+ * grammar while that menu is open and leave with it — AS THE LANGUAGE WRITES THEM (§1, «as shown»), accents kept: stripped,
+ * «configurações» is not in the model's vocabulary and the name goes mute, the same defect «acao» was.
+ */
+export declare function voiceGrammar(language: string, extra?: readonly string[]): readonly string[];
+/** What a heard phrase asks for: a position of the controller, or the item of the open menu that has this name (ADR-0194). */
+export type VoiceCommand = {
+    readonly kind: 'position';
+    readonly action: Action;
+}
+/** `name` is the item's name exactly as it was handed to `items` — the name on screen, to find the item by. */
+ | {
+    readonly kind: 'item';
+    readonly name: string;
+};
+export interface VoiceCommands {
+    /**
+     * The names the open menu is showing, as shown (ADR-0194 §2): from now on, saying one is a command — until the next call.
+     * An empty list is a menu closed.
+     */
+    items(names: readonly string[]): void;
+    /**
+     * What the recogniser has heard SO FAR in this utterance → the commands it completes that were not answered before.
+     * ⚠️ It answers on the PARTIAL and not at the end of the sentence (ADR-0193 erratum, the Dev's choice after running both):
+     * 0.25–0.45 s against 1.3–1.4 s, which is the difference between a command and a delay a child gives up on — except for a
+     * name another item's name continues, which waits for `final` (ADR-0194 §3).
+     */
+    partial(text: string): readonly VoiceCommand[];
+    /** The utterance ended with this text: what it completes that the partials held back. The next partial starts afresh. */
+    final(text: string): readonly VoiceCommand[];
+}
+/**
+ * The Dev's words and the open menu's names, READ BY `platform/speech-recognition.createCommandReader` — the one reader of what
+ * was heard (ADR-0194 §2–§3); this adds only what a word MEANS here, the position it presses.
+ *
+ * 🎯 A PARTIAL GROWS, AND ONLY WHAT IS NEW FIRES. «acima» then «acima abaixo» is a child who said two words, and the second
+ * press must be `down`, not `up` all over again — the reader counts what it already answered for in each utterance.
+ */
+export declare function createVoiceCommands(language: string): VoiceCommands;

package/dist-pkg/input/voice-map.js

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/voice-map — THE WORDS A CHILD SAYS, AND THE POSITION EACH ONE PRESSES (ADR-0204 erratum; issues #184, #190).
+//
+// This is the pure half of playing by voice: a table of words per language, a closed grammar built from it and the open menu's
+// names, and what a heard phrase MEANS — a position, or an item by name (ADR-0194). WHEN a phrase is heard is the reader's
+// (`platform/speech-recognition`). Nothing here opens a microphone or loads a model — the same division that let the gaze cycle
+// be measured without a camera.
+//
+// 🎯 THE WORDS ARE THE DEV'S, checked by the Dev against what games use (racing R2 accelerate / L2 brake, shooters L2 aim / R2 fire)
+// and then run in the lab's bar protocol in the three languages: pt 23/23, es 24/24, en 24/24 detected, all rated «ok».
+// A position answers to ANY of its words, and L1/R1 are the ship's sides — his adaptation.
+//
+// ⚠️ ONE WORD IS KNOWN TO BE MISSING from a model's vocabulary: «boreste» is not in Vosk small pt (measured against its `Gr.fst`
+// symbol table), so under that recogniser R1 answers only to «estibordo». It stays in the table because the browser's own
+// recogniser has no closed vocabulary and does hear it — a word is dropped by the RECOGNISER that cannot hear it, never by this
+// table, which is the Dev's decision written down.
+import { spokenText, createCommandReader } from '../platform/speech-recognition.js';
+const PT = {
+    up: ['acima'], down: ['abaixo'], left: ['esquerda'], right: ['direita'],
+    start: ['start'], select: ['select'],
+    // 🔴 `ação` WITH THE CEDILLA AND THE TILDE, measured in a browser: written `acao`, the pt model answered "Ignoring word
+    // missing in vocabulary: 'acao'" and the first position was MUTE — the child said the word and nothing happened. The
+    // spelling here is the recogniser's VOCABULARY's; whoever compares no longer looks at accents (the reader's key), so spelling it
+    // right costs nothing on the hearing side. ⚠️ `boreste` is still outside the small model's vocabulary (ADR-0204 erratum)
+    // and stays on the table on purpose: it is the Dev's word, and a larger model hears it.
+    action1: ['ação'], action2: ['confirma', 'pega', 'ativar', 'pulo'], action3: ['voltar', 'solta', 'cancelar', 'especial'],
+    action4: ['lista', 'troca'],
+    leftShoulder: ['bombordo'], leftTrigger: ['mira', 'freia'],
+    rightShoulder: ['estibordo', 'boreste'], rightTrigger: ['gatilho', 'acelera'],
+};
+const ES = {
+    up: ['arriba'], down: ['abajo'], left: ['izquierda'], right: ['derecha'],
+    start: ['start'], select: ['select'],
+    // `acción` with its accent, by the pt line's measurement: the model's vocabulary keeps the word as the language writes it.
+    action1: ['acción'], action2: ['confirma', 'recoger', 'activar', 'saltar'], action3: ['volver', 'soltar', 'cancelar', 'especial'],
+    action4: ['inventario', 'lista', 'cambiar'],
+    leftShoulder: ['babor'], leftTrigger: ['apuntar', 'frenar'],
+    rightShoulder: ['estribor'], rightTrigger: ['disparar', 'acelerar'],
+};
+const EN = {
+    up: ['up'], down: ['down'], left: ['left'], right: ['right'],
+    start: ['start'], select: ['select'],
+    action1: ['action'], action2: ['confirm', 'grab', 'pick up', 'activate', 'jump'], action3: ['back', 'drop', 'cancel', 'special'],
+    action4: ['inventory', 'swap'],
+    leftShoulder: ['port'], leftTrigger: ['aim', 'brake'],
+    rightShoulder: ['starboard'], rightTrigger: ['trigger', 'accelerate'],
+};
+const BY_LANGUAGE = { pt: PT, es: ES, en: EN };
+/** The table of the child's language. An unknown tag falls back to Portuguese, the project's base language (ADR-0010 pillar 3). */
+export function voiceWordsFor(language) {
+    return BY_LANGUAGE[language.split('-')[0].toLowerCase()] ?? PT;
+}
+/**
+ * THE CLOSED GRAMMAR: every word the recogniser is allowed to return, and nothing else (ADR-0189, ADR-0193).
+ *
+ * 📌 A grammar is what makes 32 MiB answer in a quarter of a second, and it is also what makes it answer WRONG when a child
+ * says something that is not a command: the lab measured free speech being pushed to the nearest word («configurações de
+ * inclusão» → «quatro»). That is the cost of the closed list and the reason the words are short and unlike each other.
+ * ⚠️ `extra` is what the MENU is showing right now (ADR-0194): saying the name of an item activates it, so those words join the
+ * grammar while that menu is open and leave with it — AS THE LANGUAGE WRITES THEM (§1, «as shown»), accents kept: stripped,
+ * «configurações» is not in the model's vocabulary and the name goes mute, the same defect «acao» was.
+ */
+export function voiceGrammar(language, extra = []) {
+    const all = new Set();
+    for (const words of Object.values(voiceWordsFor(language)))
+        for (const p of words)
+            all.add(p.toLowerCase());
+    for (const e of extra) {
+        const clean = spokenText(e);
+        if (clean)
+            all.add(clean);
+    }
+    return [...all];
+}
+/**
+ * The Dev's words and the open menu's names, READ BY `platform/speech-recognition.createCommandReader` — the one reader of what
+ * was heard (ADR-0194 §2–§3); this adds only what a word MEANS here, the position it presses.
+ *
+ * 🎯 A PARTIAL GROWS, AND ONLY WHAT IS NEW FIRES. «acima» then «acima abaixo» is a child who said two words, and the second
+ * press must be `down`, not `up` all over again — the reader counts what it already answered for in each utterance.
+ */
+export function createVoiceCommands(language) {
+    const actionOf = new Map();
+    for (const [action, spoken] of Object.entries(voiceWordsFor(language))) {
+        for (const phrase of spoken)
+            if (!actionOf.has(spokenText(phrase)))
+                actionOf.set(spokenText(phrase), action);
+    }
+    const reader = createCommandReader([...actionOf.keys()]);
+    let names = [];
+    let utterance = 0;
+    let previous = [];
+    const meaning = (heard) => heard.flatMap((h) => {
+        if (h.kind === 'palavra') {
+            const action = actionOf.get(h.word);
+            return action ? [{ kind: 'position', action }] : [];
+        }
+        const name = names.find((n) => spokenText(n) === h.name);
+        return name === undefined ? [] : [{ kind: 'item', name }];
+    });
+    return {
+        items(n) { names = [...n]; reader.items(names); },
+        partial(text) {
+            const heard = spokenText(text).split(' ').filter(Boolean);
+            /*
+             * 🔴 A NEW UTTERANCE IS ONE THAT DOES NOT CONTINUE THE LAST, and counting words is not enough to see it: a recogniser
+             * starts a new partial without saying so — and does whenever the grammar changes, because a new grammar is a new
+             * recogniser — and «abaixo» after «acima abaixo» is shorter than what was already answered. What a partial of the same
+             * utterance always is, is the previous one plus more.
+             */
+            if (!previous.every((p, i) => heard[i] === p))
+                utterance += 1;
+            previous = heard;
+            return meaning(reader.read(utterance, text, false));
+        },
+        final(text) {
+            const done = meaning(reader.read(utterance, text, true));
+            utterance += 1;
+            previous = [];
+            return done;
+        },
+    };
+}

package/dist-pkg/platform/audio-ambient.d.ts

@@ -1,21 +1,32 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Role, Spot } from '../core/contract.js';
 interface Vec2 {
     x: number;
     y: number;
 }
 export interface AudioAmbientCtx {
+    /**
+     * WHERE THE WATER IS, ASKED OF THE GAME through the contract's `roleAt` — never read off a tile number. "Water is
+     * tile 3" is true of ONE map (the platformer's), not of the engine: a game with another numbering would hear a river
+     * in its lava and silence in its lake, with no error and no red test (ADR-0027's no. 1 coupling, the one
+     * `render/high-contrast` shed by receiving `roleOf`). `roleAt` and not a bespoke `isWater`, because every cartridge
+     * already answers it (`GameDeclaration.roleAt` is required) and 'water' is already a contract `Role`: a second
+     * question would be a second table to drift from the one that paints high contrast and routes the sonar. Asked in
+     * world units, at the corner of each cell of the neighbourhood (`TILE` per cell).
+     * ⚠️ REQUIRED, by ADR-0224's precedent: an optional port would let a game forget it, and forgetting it would silence
+     * the water without a word.
+     */
+    roleAt: (at: Spot) => Role;
     ensureAC: () => AudioContext | null;
     getAudioCtx: () => AudioContext | null;
     catNode: (cat: string) => AudioNode | null;
     audioOut: () => AudioNode | null;
-    noiseBuffer: (ac: AudioContext) => AudioBuffer;
     getSoundOn: () => boolean;
     getVolume: () => number;
     getAudioCat: () => Record<string, {
         on: boolean;
     }> | null;
     getPlayers: () => Vec2[];
-    tileAt: (x: number, y: number) => number;
     TILE: number;
     getRainLevel: () => number;
 }

package/dist-pkg/platform/audio-ambient.js

@@ -1,12 +1,11 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// platform/audio-ambient — trilha de AMBIENTE sintetizada (loops de ruído filtrado) + trovão. Última rodada do Tier 2 de
-// áudio (r4). O clima VISUAL (updateWeather/drawWeather/chuva) fica no game.js e migra p/ render depois — aqui só o SOM.
-// Ponte com o clima: `_rainLevel` (0..1) é calculado por updateWeather (game.js) e LIDO aqui por getter → o volume da
-// chuva "segue o visual". Injeção por closure (padrão Tier 1).
-//   updateAmbient() — por frame: constrói a trilha 1x (lazy) e ajusta o ganho de ÁGUA (proximidade de tiles de água) e
-//                     de CHUVA (segue _rainLevel). Gated por audioCat.ambient.on.
-//   thunder(inten)  — rumor grave sintetizado (ruído passa-baixas), intensidade variável; chamado por updateWeather.
-// Extraído do game.js. Ver docs/5-Refactoring/plano-modularizacao-mapa.md (Tier 2, áudio rodada 4).
+// platform/audio-ambient — a synthesised AMBIENT track (loops of filtered noise) + thunder. Only the SOUND lives here;
+// the visual weather is the game's. The bridge to it: the rain level (0..1) is computed by the game's weather and READ
+// here through a getter, so the rain's volume "follows the picture". Injection by closure.
+//   updateAmbient() — per frame: builds the track once (lazily) and sets the WATER gain (nearness of what the game
+//                     calls 'water') and the RAIN gain (follows the rain level). Gated by audioCat.ambient.on.
+//   thunder(inten)  — a synthesised low rumble (low-passed noise) of variable intensity; called by the weather.
+import { noiseBuffer } from './audio.js';
 export function createAudioAmbient(ctx) {
     let _ambient = null;
     function buildAmbient(ac) {
@@ -19,7 +18,7 @@ export function createAudioAmbient(ctx) {
             const w = Math.random() * 2 - 1;
             last = (last + 0.02 * w) / 1.02;
             d[i] = last * 3.2;
-        } // ruído rosa em loop
+        } // looping pink noise
         const mk = (type, freq, q, vol) => {
             const s = ac.createBufferSource();
             s.buffer = buf;
@@ -38,7 +37,7 @@ export function createAudioAmbient(ctx) {
             catch (e) { /* noop */ }
             return g;
         };
-        // trânsito/rumor · folhas/vento · água (proximidade) · chuva (ciclo)
+        // traffic/rumble · leaves/wind · water (nearness) · rain (cycle)
         return { hum: mk('lowpass', 480, 0, 0.055), wind: mk('highpass', 3200, 0, 0.028), water: mk('bandpass', 820, 1.4, 0), rain: mk('highpass', 1700, 0, 0) };
     }
     function updateAmbient() {
@@ -54,11 +53,11 @@ export function createAudioAmbient(ctx) {
         let nearWater = 0;
         for (let dx = -3; dx <= 3; dx++)
             for (let dy = -3; dy <= 3; dy++) {
-                if (ctx.tileAt(px + dx, py + dy) === 3)
+                if (ctx.roleAt({ x: (px + dx) * ctx.TILE, y: (py + dy) * ctx.TILE }) === 'water')
                     nearWater = Math.max(nearWater, 1 - Math.hypot(dx, dy) / 4.2);
             }
         _ambient.water.gain.setTargetAtTime(0.15 * nearWater, ac.currentTime, 0.3);
-        _ambient.rain.gain.setTargetAtTime(0.09 * ctx.getRainLevel(), ac.currentTime, 0.5); // chuva segue _rainLevel; 0 = silêncio total
+        _ambient.rain.gain.setTargetAtTime(0.09 * ctx.getRainLevel(), ac.currentTime, 0.5); // the rain follows the rain level; 0 = full silence
     }
     function thunder(inten) {
         if (!ctx.getSoundOn() || ctx.getVolume() <= 0)
@@ -68,8 +67,9 @@ export function createAudioAmbient(ctx) {
             return;
         try {
             const vol = ctx.getVolume();
+            // the engine's own white noise (ADR-0258): a game could only ever hand back this same function
             const src = ac.createBufferSource();
-            src.buffer = ctx.noiseBuffer(ac);
+            src.buffer = noiseBuffer(ac);
             src.loop = true;
             const bq = ac.createBiquadFilter();
             bq.type = 'lowpass';
@@ -83,7 +83,7 @@ export function createAudioAmbient(ctx) {
             src.start(t);
             src.stop(t + dur + 0.1);
         }
-        catch (e) { /* Web Audio indisponível */ }
+        catch (e) { /* no Web Audio */ }
     }
     return { updateAmbient, thunder };
 }

package/dist-pkg/platform/audio-earcons.d.ts

@@ -1,39 +1,40 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 /**
- * A definição de UM earcon. A tabela é do JOGO (item 19); esta é a forma que a engine sabe tocar.
+ * The definition of ONE earcon. The table is the GAME's; this is the shape the engine knows how to play.
  *
- * ⚠️ EXPORTADA DESDE 2026-09-07 (#124), e a falta era um defeito de interface: o `game-platformer` declarava
- * a sua própria cópia deste tipo, palavra por palavra, porque não tinha como o nomear. Uma forma que cada
- * consumidor redescobre por cópia é uma forma que diverge — foi assim que cinco cópias de `Gfx` divergiram
- * nesta árvore, e está escrito noutro módulo.
+ * ⚠️ EXPORTED (#124), and its absence was an interface defect: a game declared its own copy of this type, word for word,
+ * because it had no way to name it. A shape each consumer rediscovers by copying is a shape that diverges.
  */
 export interface SfxDef {
-    /** O timbre. */
+    /** The timbre. */
     t: OscillatorType;
-    /** A frequência inicial, em hertz. */
+    /** The starting frequency, in hertz. */
     f: number;
-    /** A duração, em segundos. */
+    /** The duration, in seconds. */
     d: number;
-    /** A CHAVE de i18n da legenda (a11y surdez). Quem exibe resolve. */
+    /** The caption's i18n KEY (deaf accessibility). Whoever shows it resolves it. */
     cap?: string;
     /**
-     * A frequência FINAL, em hertz. Ausente = nota parada, que é o que sempre houve.
+     * The FINAL frequency, in hertz. Absent = a held note, which is what there always was.
      *
-     * ⚠️ ELE EXISTE PORQUE UM EARCON PRECISA DE PODER IR PARA ALGUM LADO (#124). Medido ao construir o
-     * `game-soccer`: marcar e sofrer golo têm de ser distinguíveis **só de ouvido** — uma criança cega ouve a
-     * sala reagir e precisa de saber para que lado antes de a narração chegar. O desenho óbvio é uma figura
-     * que SOBE para o golo dela e DESCE para o do outro, e a tabela não o sabia dizer. O que sobrava era
-     * agudo-e-longo contra grave-e-curto: distinguível, e menos informação do que o momento carrega.
+     * ⚠️ IT EXISTS BECAUSE AN EARCON HAS TO BE ABLE TO GO SOMEWHERE (#124). Measured building a football game: scoring and
+     * conceding must be told apart **by ear alone** — a blind child hears the room react and needs to know which way before
+     * the narration arrives. The obvious design is a figure that RISES for their goal and FALLS for the other's, and the
+     * table could not say it. What was left was high-and-long against low-and-short: distinguishable, and less information
+     * than the moment carries.
      *
-     * ⚠️ E A CAPACIDADE JÁ ESTAVA NESTE FICHEIRO, sem ser alcançável da tabela: o `doorSound` faz exatamente
-     * isto, com `frequency.exponentialRampToValueAtTime`. O conserto não é síntese nova — é abrir a porta.
+     * ⚠️ AND THE CAPABILITY WAS ALREADY IN THIS FILE, unreachable from the table: `doorSound` does exactly this with
+     * `frequency.exponentialRampToValueAtTime`. The fix was not new synthesis — it was opening the door.
      *
-     * A rampa é EXPONENCIAL e não linear porque a altura é percebida em razão e não em diferença: uma rampa
-     * linear de 200 a 800 sobe depressa no início e devagar no fim, e ouve-se torta.
+     * The ramp is EXPONENTIAL and not linear because pitch is perceived as a ratio, not a difference: a linear ramp from 200
+     * to 800 rises fast at the start and slowly at the end, and sounds crooked.
      */
     f2?: number;
 }
+import type { Translate } from '../core/i18n.js';
 export interface AudioEarconsCtx {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
     SFX: Record<string, SfxDef | undefined>;
     ensureAC: () => AudioContext | null;
     catNode: (cat: string) => AudioNode | null;