@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -1,59 +1,68 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// platform/audio-earcons — earcons (ícones sonoros) do jogo + a ponte com as LEGENDAS visuais (a11y surdez).
-// Tier 2 do áudio, rodada 2. Depende das primitivas de platform/audio (SFX/ensureAC/catNode/audioOut/noiseHit) e,
-// por injeção, do estado de legenda que VIVE no game.js (captionsOn é alternado pela UI; showCaption toca o #caption
-// e é reusado por win()). Injeção por closure (padrão Tier 1).
-//   sfx(name)      — toca o earcon da tabela SFX (oscilador) E, se as legendas estão ON e o earcon tem `.cap`, mostra a
-//                    legenda ANTES de checar o som → um jogador surdo "vê" o som mesmo com o áudio desligado.
-//   doorSound(mat) — porta: rangido (madeira, sawtooth) ou clangor (ferro, square) + baque de ruído (noiseHit).
-// Extraído do game.js. Ver docs/5-Refactoring/plano-modularizacao-mapa.md (Tier 2, áudio rodada 2).
-import { t } from '../core/i18n.js'; // item 19: `cap` guarda CHAVE, e quem exibe resolve
+// platform/audio-earcons — a game's earcons (sound icons) + the bridge to the visual CAPTIONS (deaf accessibility).
+// It depends on platform/audio's primitives and, by injection, on the host's caption state. Injection by closure.
+//   sfx(name)      — plays the earcon from the table (an oscillator) AND, when captions are ON and the earcon has a `.cap`,
+//                    shows the caption BEFORE checking the sound → a deaf player "sees" the sound even with audio off.
+//   doorSound(mat) — a door: a creak (wood, sawtooth) or a clang (iron, square) + a noise thud (noiseHit).
 export function createAudioEarcons(ctx) {
+    const { t } = ctx;
+    /** Whether a sound may play at all: the game's sound on, and a volume above zero. */
+    const audible = () => ctx.getSoundOn() && ctx.getVolume() > 0;
+    /** A category's bus; without one, the master; without that, the device itself. */
+    const busFor = (cat, ac) => ctx.catNode(cat) || ctx.audioOut() || ac.destination;
     function sfx(name) {
         const c = ctx.SFX[name];
         if (!c)
             return;
-        // LEGENDA primeiro (visual + aria-live via role=status) — e RESOLVIDA no ponto de uso: `cap` guarda a
-        // CHAVE desde o item 19, porque a tabela vive no jogo e uma tabela de `const` com texto congelaria no
-        // idioma do boot. Quem exibe resolve; é a mesma regra de `render/viz-modes`.
+        // The CAPTION first (visual + aria-live through role=status) — and RESOLVED where it is used: `cap` holds the KEY,
+        // because the table lives in the game and a `const` table of text would freeze in the boot's language.
         if (ctx.getCaptionsOn() && c.cap)
             ctx.showCaption(t(c.cap));
-        if (!ctx.getSoundOn() || ctx.getVolume() <= 0)
-            return; // ...só então o som — surdez: a legenda já saiu
+        if (!audible())
+            return; // ...only then the sound — for a deaf player the caption is already out
         try {
-            const ac = ctx.ensureAC();
-            if (!ac)
-                return;
-            const o = ac.createOscillator(), g = ac.createGain();
-            o.type = c.t;
-            o.frequency.value = c.f;
-            g.gain.value = 0.0001;
-            o.connect(g).connect(ctx.catNode('earcons') || ctx.audioOut() || ac.destination);
-            const t = ac.currentTime, vol = ctx.getVolume();
-            // A FIGURA, quando a tabela pede uma (#124). `setValueAtTime` antes da rampa como no `doorSound`: sem
-            // ele o ponto de partida da curva fica por conta da implementação, e o glissando começa onde calhar.
-            //
-            // ⚠️ AS DUAS GUARDAS SÃO NECESSÁRIAS E NÃO ZELO. `exponentialRampToValueAtTime` LANÇA com alvo zero ou
-            // negativo — uma tabela com `f2: 0` mataria o earcon inteiro pelo `catch`, em silêncio. E `f2 === f`
-            // não é rampa nenhuma: pedi-la ao navegador seria trabalho para produzir a nota parada que já havia.
-            if (typeof c.f2 === 'number' && c.f2 > 0 && c.f2 !== c.f) {
-                o.frequency.setValueAtTime(c.f, t);
-                o.frequency.exponentialRampToValueAtTime(c.f2, t + c.d);
-            }
-            g.gain.exponentialRampToValueAtTime(Math.max(0.02, 0.25 * vol), t + 0.01);
-            g.gain.exponentialRampToValueAtTime(0.0001, t + c.d);
-            o.start(t);
-            o.stop(t + c.d + 0.02);
+            play(c);
         }
-        catch (e) { /* Web Audio indisponível */ }
+        catch (e) { /* no Web Audio */ }
+    }
+    /** One earcon: its timbre, its figure when the table asks for one, a peak that follows the master volume, and its length. */
+    function play(c) {
+        const ac = ctx.ensureAC();
+        if (!ac)
+            return;
+        const o = ac.createOscillator(), g = ac.createGain();
+        o.type = c.t;
+        o.frequency.value = c.f;
+        g.gain.value = 0.0001;
+        o.connect(g).connect(busFor('earcons', ac));
+        const now = ac.currentTime, vol = ctx.getVolume();
+        glide(o, c, now);
+        g.gain.exponentialRampToValueAtTime(Math.max(0.02, 0.25 * vol), now + 0.01);
+        g.gain.exponentialRampToValueAtTime(0.0001, now + c.d);
+        o.start(now);
+        o.stop(now + c.d + 0.02);
+    }
+    /**
+     * THE FIGURE, when the table asks for one (#124). `setValueAtTime` before the ramp as in `doorSound`: without it the
+     * curve's starting point is up to the implementation, and the glissando starts wherever it happens to.
+     *
+     * ⚠️ THE TWO GUARDS ARE NEEDED, NOT FUSSINESS. `exponentialRampToValueAtTime` THROWS on a zero or negative target — a
+     * table with `f2: 0` would kill the whole earcon through the `catch`, in silence. And `f2 === f` is no ramp at all:
+     * asking the browser for it would be work to produce the held note that was already there.
+     */
+    function glide(o, c, now) {
+        if (typeof c.f2 !== 'number' || c.f2 <= 0 || c.f2 === c.f)
+            return;
+        o.frequency.setValueAtTime(c.f, now);
+        o.frequency.exponentialRampToValueAtTime(c.f2, now + c.d);
     }
     function doorSound(mat) {
-        if (!ctx.getSoundOn() || ctx.getVolume() <= 0)
+        if (!audible())
             return;
         const ac = ctx.ensureAC();
         if (!ac)
             return;
-        try { // porta: rangido (madeira) ou clangor (ferro) + baque
+        try { // a door: a creak (wood) or a clang (iron) + a thud
             const o = ac.createOscillator(), g = ac.createGain(), t = ac.currentTime, vol = ctx.getVolume();
             o.type = mat === 'ferro' ? 'square' : 'sawtooth';
             o.frequency.setValueAtTime(mat === 'ferro' ? 520 : 200, t);
@@ -61,12 +70,12 @@ export function createAudioEarcons(ctx) {
             g.gain.setValueAtTime(0.0001, t);
             g.gain.exponentialRampToValueAtTime(0.14 * vol, t + 0.03);
             g.gain.exponentialRampToValueAtTime(0.0001, t + 0.35);
-            o.connect(g).connect(ctx.catNode('interact') || ctx.audioOut() || ac.destination);
+            o.connect(g).connect(busFor('interact', ac));
             o.start(t);
             o.stop(t + 0.4);
             ctx.noiseHit(mat === 'ferro' ? 'ferro' : 'madeira');
         }
-        catch (e) { /* Web Audio indisponível */ }
+        catch (e) { /* no Web Audio */ }
     }
     return { sfx, doorSound };
 }

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

@@ -1,13 +1,12 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// platform/audio-jingles — recompensas sonoras (jingles) SEM estado de jogo: vitória, enigma resolvido e fogos.
-// Primeiro passo do Tier 2 (áudio): o cluster mais puro — só depende das primitivas de platform/audio (tone/ensureAC/
-// catNode/audioOut) + soundOn/volume vivos. Sem tiles, players, coins nem DOM. Injeção por closure (padrão Tier 1).
-//   playVictory      — jingle 8-bit ascendente (C5 E5 G5 C6 B5 E6) + 4 fogos de artifício.
-//   playPuzzleSolved — frase DOCE senoidal ascendente (E5 G5 B5 E6 + C6 de fundo), Zelda OoT; NUNCA agressiva (José).
-//   firework         — assobio subindo (sine 300→1200 Hz) + estouro/crepitar (5 osciladores square); usado por playVictory.
-// Extraído do game.js (linhas 625-633). Ver docs/5-Refactoring/plano-modularizacao-mapa.md (Tier 2, áudio rodada 1).
+// platform/audio-jingles — sound rewards (jingles) with NO game state: victory, puzzle solved and fireworks.
+// It depends only on the primitives of platform/audio (tone/ensureAC/catNode/audioOut) plus the live soundOn/volume — no
+// tiles, players, coins or DOM. Injection by closure.
+//   playVictory      — a rising 8-bit jingle (C5 E5 G5 C6 B5 E6) + 4 fireworks.
+//   playPuzzleSolved — a SWEET rising sine phrase (E5 G5 B5 E6 over a C6), Zelda OoT; NEVER aggressive (the Dev's call).
+//   firework         — a rising whistle (sine 300→1200 Hz) + burst/crackle (5 square oscillators); used by playVictory.
 export function createAudioJingles(ctx) {
-    // Fogos: só osciladores crus (não usam `tone`), então guardam soundOn/volume aqui e escalam o ganho pelo volume.
+    // Fireworks: raw oscillators only (no `tone`), so they check soundOn/volume here and scale the gain by the volume.
     function firework(when) {
         if (!ctx.getSoundOn() || ctx.getVolume() <= 0)
             return;
@@ -19,7 +18,7 @@ export function createAudioJingles(ctx) {
             const o = ac.createOscillator(), g = ac.createGain();
             o.type = 'sine';
             o.frequency.setValueAtTime(300, t);
-            o.frequency.exponentialRampToValueAtTime(1200, t + 0.35); // assobio subindo
+            o.frequency.exponentialRampToValueAtTime(1200, t + 0.35); // rising whistle
             const out = ctx.catNode('earcons') || ctx.audioOut() || ac.destination;
             g.gain.setValueAtTime(0.0001, t);
             g.gain.exponentialRampToValueAtTime(0.12 * vol, t + 0.05);
@@ -38,7 +37,7 @@ export function createAudioJingles(ctx) {
                 po.stop(tt + 0.11);
             });
         }
-        catch (e) { /* Web Audio indisponível */ }
+        catch (e) { /* no Web Audio */ }
     }
     function playVictory() {
         [[523, 0], [659, 0.12], [784, 0.24], [1047, 0.36], [988, 0.52], [1319, 0.64]]

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

@@ -1,4 +1,5 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Store } from './storage.js';
 type AudioCat = {
     k: string;
     lbl: string;
@@ -7,8 +8,19 @@ type AudioCatState = {
     on: boolean;
     vol: number;
 };
+/** What the mixer is read and written through: the page's store, built by the root (ADR-0232, issue #207). */
+export type AudioCatStore = Pick<Store, 'getJSON' | 'setJSON'>;
 export declare const AUDIO_CATS: AudioCat[];
+/**
+ * A category's FACTORY state. It has a name because two places need it: the boot's read (when nothing is stored) and
+ * the hearing menu's "restore defaults" (ADR-0028). Writing `k !== 'tts'` and `0.8` in both would be the ownerless copy
+ * this repository has seen diverge — and here the divergence would put the child in a third state, neither theirs nor
+ * the factory's.
+ *
+ * What is STORED overrides it, deliberately: a stored value means someone MOVED that control, and the child's choice is
+ * not mine to undo.
+ */
 export declare function defaultAudioCat(k: string): AudioCatState;
-export declare function loadAudioCat(): Record<string, AudioCatState>;
-export declare function saveAudioCat(k: string, obj: AudioCatState): void;
+export declare function loadAudioCat(store: AudioCatStore): Record<string, AudioCatState>;
+export declare function saveAudioCat(store: AudioCatStore, k: string, obj: AudioCatState): void;
 export {};

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

@@ -1,51 +1,43 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// platform/audio-mixer.ts — categorias do mixer de áudio (dados) + carga/persistência. Módulo-folha (storage).
-// O grafo de áudio (catNode/setCatGain/_catNodes/audioCtx) e o objeto audioCat VIVO ficam no game.js — aqui só
-// a lista das categorias, o estado inicial (com o default TTS-off) e o save por categoria. (Fase 2, áudio)
-import * as store from './storage.js';
+// 🔴 There is no `other` category (ADR-0151, erratum): «O que esta categoria controla? Nada. Então pra que?» (the Dev).
+// 📏 Measured: no sound was routed through it — a volume with nothing underneath, the dead button of ADR-0106 §5.
+// 🔴 `lbl` is an i18n KEY since 2026-09-12 (ADR-0158). The labels were raw Portuguese with examples in parentheses —
+// «Sons ambiente (água, rua, trânsito, folhas, chuva)» — and a page in English showed them as they were (measured in
+// dist). ⚠️ The examples are GONE, not moved to a hint: water, doors, coins are one game's sounds, and the engine does
+// not describe a game it does not know (the Dev: «Não se faz abstração sem precisar»).
 export const AUDIO_CATS = [
-    { k: 'music', lbl: 'Música' }, { k: 'ambient', lbl: 'Sons ambiente (água, rua, trânsito, folhas, chuva)' },
-    { k: 'interact', lbl: 'Efeitos de interação (passos, portas, escada)' }, { k: 'earcons', lbl: 'Earcons (pulo, moeda, dano…)' },
-    { k: 'other', lbl: 'Outros efeitos' }, { k: 'tts', lbl: 'Narração (TTS)' }, { k: 'sonar', lbl: 'Sonar' },
-    { k: 'guard', lbl: 'Guarda de beirada' }, { k: 'guide', lbl: 'Pista / guia auditivo' },
+    { k: 'music', lbl: 'audio.cat.music' },
+    { k: 'ambient', lbl: 'audio.cat.ambient' },
+    { k: 'interact', lbl: 'audio.cat.interact' },
+    { k: 'earcons', lbl: 'audio.cat.earcons' },
+    { k: 'tts', lbl: 'audio.cat.tts' },
+    { k: 'sonar', lbl: 'audio.cat.sonar' },
+    // 🔴 `guard` and `guide` LEFT (ADR-0258, the Dev: «Saem.»): the engine plays nothing in either since the guide moved to the
+    // platformer (ADR-0257); a level stored for them stays in the child's storage and is read by nobody.
 ];
-// Estado inicial por categoria. O que estiver SALVO sobrepõe o default — e isso é deliberado: um valor salvo
-// significa que alguém MEXEU naquele controle, e a escolha da criança não é minha para desfazer. Quem já
-// tinha ligado o guia continua com ele ligado.
 /**
- * O estado de FÁBRICA de uma categoria. Existe com nome porque dois lugares precisam dele: a leitura do boot
- * (quando nada foi salvo) e o "restaurar padrões" do menu auditivo (ADR-0028). Escrever `k !== 'tts'` e `0.8`
- * nos dois seria a mesma cópia sem dono que este repositório já viu divergir — e aqui a divergência colocaria
- * a criança num terceiro estado, nem o dela nem o de fábrica.
- */
-/**
- * As categorias que nascem DESLIGADAS, e o motivo de cada uma. Lista com razão escrita, e não um `k !== 'x'`
- * pendurado numa expressão — a próxima que entrar precisa dizer por quê.
- *
- *  · `tts` — voz robótica irrita e sobrecarrega pessoas com TEA. Quem precisa liga no menu. (O TTS do
- *    letramento é o `gameSay()`, independente disto e sempre ativo.)
+ * The categories born OFF, and the reason for each. A list with its reason written down, not a `k !== 'x'` hanging in an
+ * expression — the next one to join has to say why.
  *
- *  · `guide` — o BEACON do guia auditivo, DESLIGADO desde 2026-08-26 por decisão do Dev, e é uma medida
- *    PROVISÓRIA que não deve virar permanente sem alguém a rever.
+ *  · `tts` — a robotic voice irritates and overloads autistic people. Whoever needs it turns it on in the menu. (The
+ *    literacy voice is `gameSay()`, independent of this and always on.)
  *
- *    O que ele faz hoje: um `triangle` de 0,12 s apontado para o alvo mais próximo, a cada 0,8 s, PARA
- *    SEMPRE — sem depender de movimento, de tecla ou de nada ter mudado. No modo cego `needsAudioCues` é
- *    sempre verdadeiro, então a criança que mais precisa de pistas é a que ouve o bipe a partida inteira.
- *
- *    O veredito do Dev: "um ping é a pior escolha possível, tenebroso para quem tem TEA". Não é a FREQUÊNCIA
- *    que está errada — é o bipe. Reduzi-lo a "só andando" deixaria a mesma coisa doendo menos vezes.
+ * (`guide`, born off by the Dev's decision on the old beacon, left with its category — ADR-0258.)
+ */
+const BORN_OFF = new Set(['tts']);
+/**
+ * A category's FACTORY state. It has a name because two places need it: the boot's read (when nothing is stored) and
+ * the hearing menu's "restore defaults" (ADR-0028). Writing `k !== 'tts'` and `0.8` in both would be the ownerless copy
+ * this repository has seen diverge — and here the divergence would put the child in a third state, neither theirs nor
+ * the factory's.
  *
- *    O substituto que ele descreveu é maior que uma troca de som e por isso não entra junto: uma música que
- *    fica mais intensa conforme se aproxima, e ANTES dela é preciso MAPEAR A ROTA — preencher o mapa com as
- *    direções por onde há ar ou água, para que a pista siga um caminho navegável em vez de apontar em linha
- *    reta para dentro de uma parede. Está registrado como issue; até ela existir, o silêncio é melhor que o
- *    bipe, e a criança que quiser o bipe continua podendo ligá-lo no menu auditivo.
+ * What is STORED overrides it, deliberately: a stored value means someone MOVED that control, and the child's choice is
+ * not mine to undo.
  */
-const NASCEM_DESLIGADAS = new Set(['tts', 'guide']);
 export function defaultAudioCat(k) {
-    return { on: !NASCEM_DESLIGADAS.has(k), vol: 0.8 };
+    return { on: !BORN_OFF.has(k), vol: 0.8 };
 }
-export function loadAudioCat() {
+export function loadAudioCat(store) {
     const cat = {};
     AUDIO_CATS.forEach((c) => {
         const d = defaultAudioCat(c.k);
@@ -59,4 +51,4 @@ export function loadAudioCat() {
     });
     return cat;
 }
-export function saveAudioCat(k, obj) { store.setJSON('incl_audiocat_' + k, obj); }
+export function saveAudioCat(store, k, obj) { store.setJSON('incl_audiocat_' + k, obj); }

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

@@ -1,31 +1,31 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import { type Spot, type Topology, type Speakable, type Role } from '../core/contract.js';
+import { type Spot, type Topology, type Speakable } from '../core/contract.js';
+import type { Translate } from '../core/i18n.js';
 export type SinkAC = AudioContext & {
     setSinkId?: (id: string) => Promise<void>;
 };
 /**
- * Quantos PASSOS da métrica declarada saturam o estéreo. Além disto, "à direita" é só à direita.
+ * How many STEPS of the declared metric saturate the stereo. Beyond this, "to the right" is just to the right.
  *
- * ⚠️ ONZE NÃO É NÚMERO NOVO — é o que a plataforma sempre teve, relido na régua certa. O denominador antigo
- * era `LOGICAL_W * 0.55 = 320 × 0,55 = 176` pixels, e a plataforma declara `unit: TILE` = 16: são **exatamente
- * 11 tiles**. Reescrever em passos preserva o que essa criança já ouve, letra por letra, e passa a dizer o
- * mesmo em qualquer gênero — 11 casas num tabuleiro, 11 metros num campo.
+ * ⚠️ ELEVEN IS NOT A NEW NUMBER — it is what the platformer always had, reread on the right ruler. The old denominator was
+ * `LOGICAL_W * 0.55 = 320 × 0.55 = 176` pixels, and the platformer declares `unit: TILE` = 16: **exactly 11 tiles**.
+ * Rewriting it in steps keeps what that child already hears, and says the same in any genre — 11 squares on a board,
+ * 11 metres on a pitch.
  *
- * E encaixa na régua que o resto do módulo já usa: `chaveDeDistancia` corta "muito perto" em 4 passos e
- * "perto" em 9. O estéreo satura logo depois de a coisa passar a ser "longe", que é onde a direção deixa de
- * precisar de mais precisão.
+ * And it fits the ruler the rest of the module uses: `distanceKey` cuts "very near" at 4 steps and "near" at 9. The
+ * stereo saturates just after the thing becomes "far", which is where direction stops needing more precision.
  */
 export declare const PAN_PACES = 11;
 /**
- * Quanto vale UM passo, em unidades do mundo. Zero = este espaço não tem lado.
+ * What ONE step is worth, in world units. Zero = this space has no sides.
  *
- * Contínuo: o `unit` declarado. Grade: uma célula, por definição. Lista: nada — `hotspots` é uma ordem, não
- * uma geometria, e inventar-lhe uma largura de estéreo seria apontar para um lado que não existe.
+ * Continuous: the declared `unit`. Grid: one cell, by definition. List: nothing — `hotspots` is an order, not a geometry,
+ * and inventing a stereo width for it would point at a side that does not exist.
  */
-export declare function passoDoMundo(topo: Topology): number;
+export declare function worldStep(shape: Topology): number;
 /**
- * O jogador visto pela navegação sonora. É a fatia MÍNIMA, e ela encolheu com o corte: `facing` ficou com a
- * bengala (é ela que bate "à frente") e `wnT` com o nado. Sobrou identidade, posição, visão e o dispositivo.
+ * The player as navigation by sound sees them. The MINIMAL slice, which shrank with the cut: `facing` stayed with the cane
+ * (it is the cane that taps "ahead") and `wnT` with swimming. What remains is identity, position, sight and the device.
  */
 export interface SonarPlayer extends PlayerAudioOut {
     readonly i: number;
@@ -33,179 +33,76 @@ export interface SonarPlayer extends PlayerAudioOut {
     readonly y: number;
     readonly audioSink?: string | null;
 }
-/** O grafo contínuo do guia: oscilador → passa-baixo → ganho → panorâmica → categoria `guide`. */
-export interface GuiaVivo {
-    /** O contexto que o construiu — é dele que sai o `currentTime` de cada `setTargetAtTime`. */
-    readonly ac: AudioContext;
-    readonly osc: OscillatorNode;
-    readonly filtro: BiquadFilterNode;
-    readonly ganho: GainNode;
-    /** `null` em motor sem `createStereoPanner` — o guia fica mono em vez de não existir. */
-    readonly panner: StereoPannerNode | null;
-    /** Quadros desde a última vez que a ROTA foi recalculada. A rota é cara; o som não pode esperar por ela. */
-    desdeARota: number;
-    /** O último `passos` medido. É daqui que a intensidade sai a cada quadro. */
-    passos: number;
-    /** A última panorâmica medida, pelo mesmo motivo: ela vem do alvo, que só se procura com a rota. */
-    pan: number;
-}
-/**
- * ⚠️ O TIMBRE TEM DE TER HARMÓNICOS, e isto é requisito técnico, não gosto.
- *
- * O eixo do #84 item 2 é o BRILHO, e brilho é um passa-baixo a abrir e a fechar. **Um passa-baixo sobre uma
- * onda `sine` não faz absolutamente nada**: a senoide não tem nada acima da fundamental para o filtro cortar,
- * e o guia ficaria com um eixo morto e só o volume a trabalhar. A dente-de-serra é a mais rica das quatro
- * ondas do Web Audio — tem TODOS os harmónicos —, e é por isso que ela é a escolha.
- *
- * E ela resolve, de graça, a outra restrição do plano: o sonar e a bengala usam `sine`. Um timbre diferente
- * era exigência de não colidirem no mesmo canal; aqui o timbre diferente É o mecanismo.
- */
-export declare const GUIA_TIPO: OscillatorType;
-/**
- * A fundamental do guia, fixa.
- *
- * ⚠️ FIXA DE PROPÓSITO: a ALTURA já é a linguagem do sonar (`380 + 740 * near`, mais perto = mais agudo). Se o
- * guia também subisse de tom, os dois estariam a dizer a mesma coisa pelo mesmo meio, e quem ouve os dois ao
- * mesmo tempo não teria como separá-los. O guia diz distância por brilho; o sonar, por altura.
- */
-export declare const GUIA_HZ = 220;
-/**
- * Quantos quadros entre dois cálculos de rota.
- *
- * ⚠️ A ROTA É UMA BUSCA EM LARGURA, e o `__incl.update(dt)` conta QUADROS: correr uma BFS a cada quadro num
- * mapa de plataforma gasta o orçamento do quadro inteiro no aparelho-alvo (Positivo/Chromebook, pilar 1). Doze
- * quadros são ~0,2 s a 60 fps — mais depressa do que a criança anda um passo, e o som não espera por eles: a
- * intensidade é reescrita TODO quadro, com o `passos` que a última rota deixou.
- */
-export declare const QUADROS_ENTRE_ROTAS = 12;
-/**
- * O tecto de pontos da rota do guia. Bem abaixo dos 4096 do `core/route`, e o próprio módulo diz porquê:
- * «uma pista por quadro tolera muito menos do que um cálculo ao carregar a fase». Estourar devolve `null`, que
- * é «não sei» — e o guia cai na reta, que ainda soa.
- */
-export declare const ORCAMENTO_DA_ROTA = 1024;
-/**
- * O ganho de base do guia, antes de a intensidade e o volume mestre o multiplicarem.
- *
- * ⚠️ MAIS BAIXO DO QUE O BIPE QUE ELE SUBSTITUI (0,11), e não por engano: um som que **nunca para** é
- * percebido como mais alto do que um transiente do mesmo pico, e cansa por permanência em vez de por
- * intensidade — exactamente o que o modo TEA existe para não fazer.
- */
-export declare const GUIA_VOL = 0.06;
-/** Constante de tempo do `setTargetAtTime`. Curta o bastante para acompanhar o passo, longa o bastante para
- *  que a mudança seja um deslize e não um degrau — um degrau a cada rota seria um bipe outra vez. */
-export declare const TAU_DO_GUIA = 0.08;
 /**
- * A SAÍDA DEDICADA de um jogador, e este módulo é o DONO dela: é aqui que os dois campos NASCEM
- * (`new AC()` + `createGain()`, logo abaixo). Pelo ADR-0039 o dono declara onde o campo nasce, e o
- * `core/entity` não os menciona — eles não são da entidade da engine, são rascunho que o áudio pendura
- * no jogador.
+ * A player's DEDICATED OUTPUT, and this module OWNS it: it is here the two fields are BORN (`new AC()` + `createGain()`,
+ * below). By ADR-0039 the owner declares where a field is born, and `core/entity` does not mention them — they are not
+ * the engine entity's, they are scratch the audio hangs on the player.
  *
- * `_acOut` admite `null` porque `ui/settings-audio` escreve `null` nos dois ao trocar de dispositivo.
- * Enquanto o `core/entity` dizia `unknown`, essa escrita passava sem que ninguém visse que o dono
- * declarava `GainNode` sem nulo — as duas descrições discordavam e o `unknown` era o que as escondia.
+ * `_acOut` allows `null` because the audio panel writes `null` to both when the device changes; an `unknown` on the
+ * entity used to hide that the owner declared a non-null `GainNode`.
  */
 export interface PlayerAudioOut {
     _ac?: SinkAC | null;
     _acOut?: GainNode | null;
-    /**
-     * O GRAFO VIVO DO GUIA deste jogador, e mora AQUI, ao lado dos outros dois, pelo mesmo motivo que eles
-     * (ADR-0039: o dono declara onde o campo nasce; ADR-0033: a entidade da engine declara o que a ENGINE
-     * possui, e um oscilador não é dela). `null`/ausente = calado.
-     *
-     * ⚠️ ELE PRECISA DE SOBREVIVER AOS QUADROS, e é aí que ele difere de tudo o resto neste ficheiro. O sonar e
-     * o bipe antigo criavam um oscilador, tocavam-no e deitavam-no fora; uma presença CONTÍNUA (#84 item 2) é um
-     * oscilador que FICA, com o filtro e o ganho a mover-se por baixo dele. É por isso que ele tem de estar
-     * pendurado no jogador: não há outro lugar onde algo por jogador dure de um quadro para o outro.
-     *
-     * ⚠️ E É POR ISSO QUE `desligarGuia` EXISTE. Um campo que dura é um campo que vaza: sem alguém a pará-lo,
-     * desligar a categoria `guide` no mixer deixaria o som a tocar.
-     */
-    _guia?: GuiaVivo | null;
 }
 export interface PlayerCtxOut {
     ac: AudioContext;
     out: GainNode;
 }
 export interface SonarCtx {
-    /** Campo 1: a métrica. Função, porque um jogo com fases troca de topologia entre elas. */
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    /** Field 1: the metric. A function, because a game with stages changes topology between them. */
     topology: () => Topology;
-    /** Campo 5, metade "alvo": onde estão os alvos ainda válidos deste jogador. Vazio = nada a apontar. */
+    /** Field 5, the "target" half: where this player's still-valid targets are. Empty = nothing to point at. */
     targetsOf: (playerIndex: number) => readonly Spot[];
-    /** Campo 3: como se chama o que está ali. `null` = sem nome, e o anúncio cai no genérico. */
+    /** Field 3: what the thing there is called. `null` = no name, and the announcement falls back to the generic. */
     nameAt: (at: Spot) => Speakable | null;
-    /**
-     * Campo 2: o que há neste ponto. É o que o `core/route` atravessa (ou não) para achar o caminho.
-     *
-     * ⚠️ OPCIONAL AQUI, e obrigatório na `GameDeclaration` — a diferença não é descuido. Tornar um campo do
-     * `SonarCtx` obrigatório quebra todo o consumidor que já monta este ctx à mão, e o `create-game` (que é
-     * quem o monta de verdade) sempre o tem, porque o `validateDeclaration` o exige. Ausente aqui, o guia não
-     * fica calado: ele cai na distância em reta, que é o que ele já fazia antes desta mudança.
-     */
-    roleAt?: (at: Spot) => Role;
     tonePan: (freq: number, dur: number, cat: string, pan?: number | null, vol?: number, type?: OscillatorType, pc?: PlayerCtxOut | null) => void;
     srSay: (text: string) => void;
-    narrate: (text: string) => void;
     /**
-     * O barramento de uma categoria do mixer. A MESMA forma que `audio-ambient`, `audio-earcons`, `audio-jingles`
-     * e `tts` já recebem — o guia deixou de poder usar o `tonePan` porque `tonePan` toca e esquece, e uma
-     * presença contínua é um grafo que FICA.
-     *
-     * Opcional pelo mesmo motivo que o `roleAt`: quem não o injectar cai no `audioOut` e, na falta dele, no
-     * `destination`. O que se perde é o cursor da categoria `guide`, não o som.
+     * Speaks the sonar's words. `seat` is the player who pressed: a reading takes turns with the other players' and cuts that
+     * player's own (ADR-0234, errata 2026-09-26 — the root's narration does it; a ctx built by hand may ignore it).
      */
-    catNode?: (cat: string) => AudioNode | null;
-    /** O nó mestre, recuo do `catNode`. */
-    audioOut?: () => AudioNode | null;
+    narrate: (text: string, seat: number) => void;
     /**
-     * O volume mestre (0..1), que cada síntese multiplica por si — o `_masterGain` do `platform/audio` é o mudo
-     * da pausa, não o cursor. Ausente = 1: o guia soa, e ignora o cursor. Por isso o `create-game` injecta-o.
+     * WHAT IS ON THE SCREEN NOW, as text in reading order — `''` when there is none the engine can read (ADR-0234: «sonar do que
+     * está na tela»). With text, the sonar's WORDS are that text, read at the press; the tone still points at the nearest
+     * target. Without (a world drawn on a canvas, or no text), the words are the navigation sentence. Absent: always the latter.
      */
-    getVolume?: () => number;
+    screenText?: () => string;
     /**
-     * Esta criança tem a visão comprometida — cegueira simulada ou baixa visão?
+     * Is this child's sight impaired — simulated blindness or low vision?
      *
-     * ⚠️ SUBSTITUIU O `VIZ_BY_KEY` EM 2026-09-08 (#104), e a troca encolheu este módulo em vez de o migrar.
-     * Ele recebia a TABELA de modos de render e atravessava-a com `pl.viz`; agora recebe a RESPOSTA. Quem a dá
-     * é a raiz de composição, que conhece os dois eixos e pode importar de `render/` — o que este ficheiro,
-     * estando em `platform/`, não pode sem inverter uma aresta de camada.
+     * ⚠️ It replaced the table of render modes (#104), and the swap shrank this module instead of migrating it: it used to
+     * receive the TABLE and walk it with `pl.viz`; now it receives the ANSWER. The composition root gives it — it knows the
+     * two axes and may import `render/`, which this file, in `platform/`, cannot without inverting a layer edge.
      *
-     * O `pl` inteiro e não o índice: quem responde já tem o jogador em mão, e passar o índice obrigaria a raiz
-     * a procurá-lo outra vez numa lista que ela acabou de percorrer.
+     * The whole `pl` and not the index: whoever answers already has the player in hand.
      */
-    visaoComprometida: (pl: SonarPlayer) => boolean;
-    getModoCego: () => boolean;
-    /** Largura LÓGICA da tela. É do console, não do gênero — por isso ctx, e não campo de contrato. */
+    visionImpaired: (pl: SonarPlayer) => boolean;
+    getBlindMode: () => boolean;
     /**
-     * @deprecated ⚠️ SEM LEITOR DESDE 2026-09-07 (#121). Era o denominador do pan, e era o defeito: media a
-     * largura do estéreo em pixels de ecrã e dividia por ela uma distância de MUNDO. Agora a largura vem da
-     * topologia (`PAN_PACES * passoDoMundo`).
+     * @deprecated ⚠️ NO READER (#121). It was the pan's denominator, and it was the defect: it measured the stereo width in
+     * screen pixels and divided a WORLD distance by it. The width now comes from the topology (`PAN_PACES * worldStep`).
      *
-     * Ficou OPCIONAL em vez de removido — tornar um campo obrigatório em opcional é compatível para trás, e
-     * quem já o injecta continua a compilar. Removê-lo de vez é candidato ao próximo major.
+     * It stayed OPTIONAL instead of removed — making a required field optional is backward compatible. Removing it for good
+     * is a candidate for the next major.
      */
     LOGICAL_W?: number;
-    getPlayers: () => SonarPlayer[];
     getNumPlayers: () => number;
-    getAudioCtx: () => AudioContext | null;
-    getSoundOn: () => boolean;
-    getAudioCat: () => Record<string, {
-        on: boolean;
-    }> | null;
+    /**
+     * Makes a NEW AudioContext, or `null` where the host has none: each player with an audio device of their own gets one, so
+     * `setSinkId` can send that child's cues to that device. The root's maker, from `host.win` — the same one its `createAudio`
+     * receives. REQUIRED (ADR-0232 D4): a default would be the page's window reached from `platform/`.
+     */
+    newContext: () => AudioContext | null;
 }
 export interface AudioSonar {
     playerCtx: (pl: SonarPlayer) => PlayerCtxOut | null;
     panFor: (wx: number, pl: SonarPlayer) => number;
     needsAudioCues: (pl: SonarPlayer) => boolean;
     sonar: (pl: SonarPlayer) => void;
-    updateGuide: () => void;
     readonly sonarCount: number;
-    /**
-     * ⚠️ MUDOU DE SIGNIFICADO com o #84 item 2, e o número passa a ser muito maior. Contava BIPES (um a cada 48
-     * quadros); conta agora QUADROS EM QUE O GUIA SOA, porque não há mais nada discreto para contar — é essa a
-     * mudança. Quem o lê para dizer «o guia está a funcionar» continua certo; quem o lesse para dizer «tocou
-     * três vezes» estaria a perguntar por uma coisa que deixou de existir.
-     */
-    readonly guideCount: number;
 }
 export declare function createAudioSonar(ctx: SonarCtx): AudioSonar;