@the-inclusionist/engine 9.0.0 → 10.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,48 @@
 // 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' },
+    { k: 'guard', lbl: 'audio.cat.guard' },
+    { k: 'guide', lbl: 'audio.cat.guide' },
 ];
-// 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` — the audio guide, off by the Dev's decision, a PROVISIONAL measure that should not become permanent
+ *    without someone reviewing it. The Dev's verdict on the old beacon: «um ping é a pior escolha possível, tenebroso
+ *    para quem tem TEA». It was not the FREQUENCY that was wrong — it was the beep, which the child who most needs cues
+ *    heard the whole game long. Its replacement, a sound that grows as one approaches along a walkable route (#84), is
+ *    the game's to decide; until someone reviews it, silence is the default, and a child who wants the guide can still
+ *    turn it on in the hearing menu.
+ */
+const BORN_OFF = new Set(['tts', 'guide']);
+/**
+ * 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 +56,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); }