@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-type CatState = {
+import { type AudioCatStore } from './audio-mixer.js';
+export type CatState = {
     on: boolean;
     vol: number;
 };
@@ -10,23 +11,65 @@ type PlayerCtx = {
 type ACWithCache = AudioContext & {
     _noiseBuf?: AudioBuffer;
 };
-export declare let soundOn: boolean;
-export declare function setSoundOn(v: boolean): void;
-export declare let volume: number;
-export declare function setVolume(v: number): void;
-export declare let audioCtx: AudioContext | null;
-export declare function ensureAC(): AudioContext | null;
-export declare let hearingLoss: boolean;
-export declare function audioOut(): GainNode | null;
-export declare function setHearingLossGraph(on: boolean): void;
-export declare function setMasterMuted(muted: boolean): void;
-export declare let audioCat: Record<string, CatState> | null;
-export declare function initAudioMixer(): void;
-export declare function catNode(cat: string): GainNode | null;
-export declare function setCatGain(cat: string): void;
-export declare function tone(freq: number, dur: number, type?: OscillatorType, when?: number, vol?: number): void;
-export declare function tonePan(freq: number, dur: number, cat: string, pan?: number | null, vol?: number, type?: OscillatorType, pc?: PlayerCtx | null): void;
-export declare let _footCount: number;
+export interface AudioDeps {
+    /**
+     * Makes the engine's AudioContext, or answers `null` where the host has none. Called at the FIRST sound and not before: a
+     * context made before the child's first gesture is born suspended, and the browser only lets it run from a gesture. The root
+     * builds it from `host.win` (ADR-0232 point 2); REQUIRED, because a default would be the page's window reached from here.
+     */
+    readonly newContext: () => AudioContext | null;
+    /** Where the mixer's categories are read from and kept: the page's store, built by the root. */
+    readonly store: AudioCatStore;
+}
+/**
+ * ONE ROOT'S SOUND. The reads are GETTERS, so `audio.soundOn` is the value of now; copying one into a local freezes it. The
+ * methods hold no `this` and can be destructured.
+ */
+export interface Audio {
+    /** The game's master switch. Session only (not stored). */
+    readonly soundOn: boolean;
+    setSoundOn(v: boolean): void;
+    /** The master volume, 0..1, which every synthesis multiplies by. Session only. */
+    readonly volume: number;
+    setVolume(v: number): void;
+    /** The engine's context, `null` until the first sound asks for one. */
+    readonly audioCtx: AudioContext | null;
+    /** The context, made on the first call and resumed if the browser suspended it; `null` where the host has none. */
+    ensureAC(): AudioContext | null;
+    /** The master node (master gain → optional hearing-loss filter → destination), made on the first call. */
+    audioOut(): GainNode | null;
+    /** Whether the hearing-loss empathy simulation is on the master node. */
+    readonly hearingLoss: boolean;
+    /** Switches the hearing-loss filter on the master node. Storing it and announcing it are the caller's. */
+    setHearingLossGraph(on: boolean): void;
+    /** The pause and title silence everything; playing brings it back. Acts only if the master exists — never makes one. */
+    setMasterMuted(muted: boolean): void;
+    /**
+     * The mixer's live state per category, loaded from the store when the audio is built. Written in place — `on`, `vol`, or the
+     * whole category — by the panels, the bar and any game, and EVERY write that changes a value is told to `onCatChange`.
+     */
+    readonly audioCat: Record<string, CatState>;
+    /**
+     * Listens to every change of a category — its `on` or its `vol` — WHOEVER made it: the engine's panels and bar, and a game
+     * writing `audio.audioCat.tts.on = false` itself (ADR-0247). Called with the category's key, after the value changed; a write
+     * of the value already there is no change. Answers the function that stops listening.
+     */
+    onCatChange(listener: (cat: string) => void): () => void;
+    /** A category's bus, hanging off the master node. */
+    catNode(cat: string): GainNode | null;
+    /** Moves a category's bus to its state now, and keeps that state in the store. */
+    setCatGain(cat: string): void;
+    tone(freq: number, dur: number, type?: OscillatorType, when?: number, vol?: number): void;
+    /** `pc` = a per-player audio context, passed to route the cue to that player's device. */
+    tonePan(freq: number, dur: number, cat: string, pan?: number | null, vol?: number, type?: OscillatorType, pc?: PlayerCtx | null): void;
+    noiseHit(mat: string, pan?: number | null, pc?: PlayerCtx | null): void;
+    /** A count of steps and taps (an accessibility statistic). */
+    readonly footCount: number;
+}
 export declare function noiseBuffer(ac: ACWithCache): AudioBuffer;
-export declare function noiseHit(mat: string, pan?: number | null, pc?: PlayerCtx | null): void;
+/**
+ * Builds one root's sound. The mixer's state is read from `store` HERE, so a voice built after it finds its categories — the
+ * order the second consumer once found by the silence (create-game, finding 3) is now the order of construction.
+ */
+export declare function createAudio(deps: AudioDeps): Audio;
 export {};

package/dist-pkg/platform/audio.js

@@ -1,40 +1,21 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// platform/audio.ts — base do áudio: ciclo do AudioContext (ensureAC) + definições de SFX (dados). Módulo-folha.
-// O grafo (master/mixer), soundOn/volume e as sínteses (tone/noiseHit/tonePan/sfx) ainda ficam no game.js —
-// migram numa rodada dedicada (injeção de dependência). audioCtx é binding vivo; só ensureAC o (re)cria. (Fase 2)
-import { loadAudioCat, saveAudioCat } from './audio-mixer.js'; // mixer por categoria (dados + persistência)
-// Som mestre: liga/desliga + volume (0..1). Sessão-only (sem persistência). Bindings vivos: as sínteses
-// (tone/noiseHit/…) e a narração leem soundOn/volume; o botão/slider mestre do game.js escreve pelos setters.
-export let soundOn = true;
-export function setSoundOn(v) { soundOn = v; }
-export let volume = 0.6;
-export function setVolume(v) { volume = v; }
-export let audioCtx = null;
-export function ensureAC() {
-    if (!audioCtx) {
-        const AC = window.AudioContext || window.webkitAudioContext;
-        if (AC)
-            audioCtx = new AC();
-    }
-    if (audioCtx && audioCtx.state === 'suspended')
-        audioCtx.resume();
-    return audioCtx;
-}
-// ===== Nó MESTRE: master gain → (filtro de perda auditiva opcional) → destino. =====
-export let hearingLoss = false;
-let _masterGain = null, _hlChain = null;
-export function audioOut() { const ac = ensureAC(); if (!ac)
-    return null; if (!_masterGain) {
-    _masterGain = ac.createGain();
-    wireMaster();
-} return _masterGain; }
+// platform/audio.ts — the audio base: the AudioContext's lifecycle (ensureAC), the master and mixer graph, and the
+// oscillator and noise syntheses every game's cues are made of. One per root (ADR-0232 D4, issue #207): `createAudio` holds
+// the context, the master, the mixer and the counters in its closure, and receives the host's context maker and store.
+import { loadAudioCat, saveAudioCat } from './audio-mixer.js'; // per-category mixer (data + persistence)
+export function noiseBuffer(ac) { if (ac._noiseBuf && ac._noiseBuf.length === ((ac.sampleRate * 0.2) | 0))
+    return ac._noiseBuf; const n = (ac.sampleRate * 0.2) | 0, b = ac.createBuffer(1, n, ac.sampleRate), d = b.getChannelData(0); for (let i = 0; i < n; i++)
+    d[i] = Math.random() * 2 - 1; return ac._noiseBuf = b; }
+const FOOT = { grama: { f: 'highpass', hz: 2000, d: 0.09, v: 0.10 }, piso: { f: 'bandpass', hz: 1200, d: 0.06, v: 0.15 }, pedra: { f: 'highpass', hz: 1600, d: 0.05, v: 0.19 },
+    areia: { f: 'lowpass', hz: 650, d: 0.13, v: 0.10 }, madeira: { f: 'bandpass', hz: 480, d: 0.08, v: 0.15 }, ferro: { f: 'bandpass', hz: 2600, d: 0.12, v: 0.16 }, parede: { f: 'highpass', hz: 3200, d: 0.10, v: 0.08 },
+    terra: { f: 'lowpass', hz: 520, d: 0.11, v: 0.12 }, agua: { f: 'lowpass', hz: 330, d: 0.15, v: 0.13 } };
 function buildHearingChain(ac) {
     const lp = ac.createBiquadFilter();
     lp.type = 'lowpass';
     lp.frequency.value = 1400;
-    lp.Q.value = 0.7; // agudos primeiro
+    lp.Q.value = 0.7; // the highs go first
     const sp = ac.createScriptProcessor(512, 1, 1);
-    const TH = 0.06, RED = 0.12; // frame < limiar → ×0.12 (contrário de aparelho auditivo)
+    const TH = 0.06, RED = 0.12; // a frame below the threshold → ×0.12 (a hearing aid in reverse)
     sp.onaudioprocess = (e) => { const inp = e.inputBuffer.getChannelData(0), out = e.outputBuffer.getChannelData(0); let s = 0; for (let i = 0; i < inp.length; i++)
         s += inp[i] * inp[i]; const g = Math.sqrt(s / inp.length) < TH ? RED : 1; for (let i = 0; i < inp.length; i++)
         out[i] = inp[i] * g; };
@@ -42,150 +23,194 @@ function buildHearingChain(ac) {
     sp.connect(ac.destination);
     return { input: lp };
 }
-function wireMaster() {
-    const ac = audioCtx;
-    if (!ac || !_masterGain)
-        return;
-    try {
-        _masterGain.disconnect();
+/**
+ * THE CATEGORIES AS THE MIXER HOLDS THEM, each write heard (ADR-0247). A game reaches the mixer itself (`Engine.audio`), and
+ * its door to a category is a plain property write — `audioCat.tts.on = false` — with no call after it that an event could
+ * hang on. So the write IS the door: `on` and `vol` are accessors that tell `changed`, and so is the category itself, whose
+ * replacement (`audioCat.tts = {…}`) is copied INTO the mixer's object — replaced, the object every surface reads would come
+ * apart from the one the engine and the game write, and no later write would be heard.
+ */
+function heardCategories(stored, changed) {
+    const cats = {};
+    for (const [k, first] of Object.entries(stored)) {
+        let on = first.on, vol = first.vol;
+        const live = {};
+        Object.defineProperties(live, {
+            on: { enumerable: true, get: () => on, set: (v) => { if (v !== on) {
+                    on = v;
+                    changed(k);
+                } } },
+            vol: { enumerable: true, get: () => vol, set: (v) => { if (v !== vol) {
+                    vol = v;
+                    changed(k);
+                } } },
+        });
+        Object.defineProperty(cats, k, { enumerable: true, get: () => live, set: (v) => { live.on = v.on; live.vol = v.vol; } });
     }
-    catch (e) { /* noop */ }
-    if (hearingLoss) {
-        if (!_hlChain)
-            _hlChain = buildHearingChain(ac);
-        _masterGain.connect(_hlChain.input);
-    }
-    else
-        _masterGain.connect(ac.destination);
+    return cats;
 }
-// Empatia de perda auditiva: liga/desliga o filtro no nó mestre. A persistência + srSay ficam no game.js.
-export function setHearingLossGraph(on) { hearingLoss = on; if (audioCtx) {
-    audioOut();
-    wireMaster();
-} }
-// Mute mestre (pausa/título silenciam tudo; volta ao jogar). Só age se o nó mestre já existe (não o cria à toa).
-export function setMasterMuted(muted) { if (!_masterGain || !audioCtx)
-    return; try {
-    _masterGain.gain.setTargetAtTime(muted ? 0 : 1, audioCtx.currentTime, 0.04);
+/** The last node before the output: a panner clamped to the two ears when a pan is asked, the gain itself when not. */
+function panned(ac, g, pan) {
+    if (pan == null || !ac.createStereoPanner)
+        return g;
+    const p = ac.createStereoPanner();
+    p.pan.value = Math.max(-1, Math.min(1, pan));
+    g.connect(p);
+    return p;
 }
-catch (e) { /* noop */ } }
-// ===== Mixer por categoria: cada categoria tem seu gain (liga/desliga + volume), pendurado no nó mestre. =====
-// audioCat é a fonte viva do estado do mixer (mutada pela UI/calmMode no game.js — objeto, nunca reatribuído
-// APÓS init). NULL até initAudioMixer(): o import fica PURO (não lê localStorage). initAudioMixer é chamado no
-// boot do game.js — todos os leitores de audioCat (mixer/ambiente/narração) rodam depois. (Fase 2.25)
-export let audioCat = null;
-// Carrega o estado do mixer (defaults do audio-mixer.js + o que estiver salvo). I/O EXPLÍCITO, idempotente.
-export function initAudioMixer() { if (!audioCat)
-    audioCat = loadAudioCat(); }
-const _catNodes = {};
-export function catNode(cat) { const ac = ensureAC(); if (!ac || !audioCat)
-    return null; const out = audioOut(); if (!out)
-    return null; if (!_catNodes[cat]) {
-    const g = ac.createGain();
-    g.gain.value = audioCat[cat].on ? audioCat[cat].vol : 0;
-    g.connect(out);
-    _catNodes[cat] = g;
-} return _catNodes[cat]; }
-export function setCatGain(cat) { if (!audioCat)
-    return; const g = _catNodes[cat]; if (g && audioCtx)
-    g.gain.setTargetAtTime(audioCat[cat].on ? audioCat[cat].vol : 0, audioCtx.currentTime, 0.02); saveAudioCat(cat, audioCat[cat]); }
-// ===== Sínteses de oscilador (earcons/melodias). Leem soundOn/volume; roteiam pelo mixer→mestre. =====
-// pc = contexto de áudio por-jogador (opcional; o game.js o passa p/ rotear a pista ao dispositivo do jogador).
-export function tone(freq, dur, type, when, vol) {
-    if (!soundOn || volume <= 0)
-        return;
-    try {
-        const ac = ensureAC();
-        if (!ac)
+/**
+ * Builds one root's sound. The mixer's state is read from `store` HERE, so a voice built after it finds its categories — the
+ * order the second consumer once found by the silence (create-game, finding 3) is now the order of construction.
+ */
+export function createAudio(deps) {
+    let soundOn = true, volume = 0.6;
+    let audioCtx = null;
+    let hearingLoss = false;
+    let masterGain = null, hlChain = null;
+    let footCount = 0;
+    const catListeners = new Set();
+    // a copy of the listeners, so one that stops listening while it is told does not skip the next
+    const audioCat = heardCategories(loadAudioCat(deps.store), (cat) => { for (const l of [...catListeners])
+        l(cat); });
+    const catNodes = {};
+    function onCatChange(listener) {
+        catListeners.add(listener);
+        return () => { catListeners.delete(listener); };
+    }
+    function ensureAC() {
+        if (!audioCtx)
+            audioCtx = deps.newContext();
+        if (audioCtx && audioCtx.state === 'suspended')
+            audioCtx.resume();
+        return audioCtx;
+    }
+    // ===== The MASTER node: master gain → (optional hearing-loss filter) → destination. =====
+    function audioOut() { const ac = ensureAC(); if (!ac)
+        return null; if (!masterGain) {
+        masterGain = ac.createGain();
+        wireMaster();
+    } return masterGain; }
+    function wireMaster() {
+        const ac = audioCtx;
+        if (!ac || !masterGain)
             return;
-        const o = ac.createOscillator(), g = ac.createGain(), t = ac.currentTime + (when || 0);
-        o.type = type || 'square';
-        o.frequency.setValueAtTime(freq, t);
-        g.gain.setValueAtTime(0.0001, t);
-        g.gain.exponentialRampToValueAtTime(Math.max(0.02, (vol || 0.22) * volume), t + 0.01);
-        g.gain.exponentialRampToValueAtTime(0.0001, t + dur);
-        o.connect(g).connect(catNode('earcons') || audioOut() || ac.destination);
-        o.start(t);
-        o.stop(t + dur + 0.02);
+        try {
+            masterGain.disconnect();
+        }
+        catch (e) { /* noop */ }
+        if (hearingLoss) {
+            if (!hlChain)
+                hlChain = buildHearingChain(ac);
+            masterGain.connect(hlChain.input);
+        }
+        else
+            masterGain.connect(ac.destination);
     }
-    catch (e) { /* noop */ }
-}
-export function tonePan(freq, dur, cat, pan, vol, type, pc) {
-    if (!soundOn || volume <= 0)
-        return;
-    const ac = pc ? pc.ac : ensureAC();
-    if (!ac)
-        return;
-    try {
-        const o = ac.createOscillator(), g = ac.createGain(), t = ac.currentTime;
-        o.type = type || 'sine';
-        o.frequency.value = freq;
-        g.gain.setValueAtTime(0.0001, t);
-        g.gain.exponentialRampToValueAtTime(Math.max(0.02, (vol || 0.2) * volume), t + 0.01);
-        g.gain.exponentialRampToValueAtTime(0.0001, t + dur);
-        let node = g;
-        if (pan != null && ac.createStereoPanner) {
-            const p = ac.createStereoPanner();
-            p.pan.value = Math.max(-1, Math.min(1, pan));
-            g.connect(p);
-            node = p;
+    function setHearingLossGraph(on) { hearingLoss = on; if (audioCtx) {
+        audioOut();
+        wireMaster();
+    } }
+    function setMasterMuted(muted) { if (!masterGain || !audioCtx)
+        return; try {
+        masterGain.gain.setTargetAtTime(muted ? 0 : 1, audioCtx.currentTime, 0.04);
+    }
+    catch (e) { /* noop */ } }
+    // ===== The per-category mixer: each category has its gain (on/off + volume), hanging off the master node. =====
+    /** A category's level: silence when it is switched off, its volume when on — asked the same way when its bus is made and when the slider moves. */
+    function catLevel(cat) { const c = audioCat[cat]; return c.on ? c.vol : 0; }
+    function catNode(cat) { const ac = ensureAC(); if (!ac)
+        return null; const out = audioOut(); if (!out)
+        return null; if (!catNodes[cat]) {
+        const g = ac.createGain();
+        g.gain.value = catLevel(cat);
+        g.connect(out);
+        catNodes[cat] = g;
+    } return catNodes[cat]; }
+    function setCatGain(cat) { const g = catNodes[cat]; if (g && audioCtx)
+        g.gain.setTargetAtTime(catLevel(cat), audioCtx.currentTime, 0.02); saveAudioCat(deps.store, cat, audioCat[cat]); }
+    // ===== The questions a cue asks before it sounds, the same for the tone and the noise. =====
+    /** Whether a sound may play at all: the game's sound on, and the master above zero. */
+    function audible() { return soundOn && volume > 0; }
+    /** The context a cue plays in: the player's own device when one is given, the engine's otherwise. */
+    function contextFor(pc) { return pc ? pc.ac : ensureAC(); }
+    /** Where a cue goes out: the player's own device; otherwise its category's bus, the master, or the device itself. */
+    function outFor(ac, cat, pc) { return pc ? pc.out : (catNode(cat) || audioOut() || ac.destination); }
+    // ===== Oscillator syntheses (earcons/melodies). They read soundOn/volume and route through mixer → master. =====
+    function tone(freq, dur, type, when, vol) {
+        if (!audible())
+            return;
+        try {
+            const ac = contextFor();
+            if (!ac)
+                return;
+            const o = ac.createOscillator(), g = ac.createGain(), t = ac.currentTime + (when || 0);
+            o.type = type || 'square';
+            o.frequency.setValueAtTime(freq, t);
+            g.gain.setValueAtTime(0.0001, t);
+            g.gain.exponentialRampToValueAtTime(Math.max(0.02, (vol || 0.22) * volume), t + 0.01);
+            g.gain.exponentialRampToValueAtTime(0.0001, t + dur);
+            o.connect(g).connect(outFor(ac, 'earcons'));
+            o.start(t);
+            o.stop(t + dur + 0.02);
         }
-        o.connect(g);
-        node.connect(pc ? pc.out : (catNode(cat) || audioOut() || ac.destination));
-        o.start(t);
-        o.stop(t + dur + 0.02);
+        catch (e) { /* noop */ }
     }
-    catch (e) { /* noop */ }
-}
-// ===== Synth de RUÍDO (passos por material, bengala). noiseBuffer cacheia por-contexto (suporta AC por jogador). =====
-export let _footCount = 0; // contador de passos/pancadas (estatística de a11y; o __incl do game.js lê via getter)
-export function noiseBuffer(ac) { if (ac._noiseBuf && ac._noiseBuf.length === ((ac.sampleRate * 0.2) | 0))
-    return ac._noiseBuf; const n = (ac.sampleRate * 0.2) | 0, b = ac.createBuffer(1, n, ac.sampleRate), d = b.getChannelData(0); for (let i = 0; i < n; i++)
-    d[i] = Math.random() * 2 - 1; return ac._noiseBuf = b; }
-const FOOT = { grama: { f: 'highpass', hz: 2000, d: 0.09, v: 0.10 }, piso: { f: 'bandpass', hz: 1200, d: 0.06, v: 0.15 }, pedra: { f: 'highpass', hz: 1600, d: 0.05, v: 0.19 },
-    areia: { f: 'lowpass', hz: 650, d: 0.13, v: 0.10 }, madeira: { f: 'bandpass', hz: 480, d: 0.08, v: 0.15 }, ferro: { f: 'bandpass', hz: 2600, d: 0.12, v: 0.16 }, parede: { f: 'highpass', hz: 3200, d: 0.10, v: 0.08 },
-    terra: { f: 'lowpass', hz: 520, d: 0.11, v: 0.12 }, agua: { f: 'lowpass', hz: 330, d: 0.15, v: 0.13 } };
-export function noiseHit(mat, pan, pc) {
-    if (!soundOn || volume <= 0)
-        return;
-    const ac = pc ? pc.ac : ensureAC();
-    if (!ac)
-        return;
-    const f = FOOT[mat] || FOOT.piso;
-    try {
-        const src = ac.createBufferSource();
-        src.buffer = noiseBuffer(ac);
-        const bq = ac.createBiquadFilter();
-        bq.type = f.f;
-        bq.frequency.value = f.hz;
-        bq.Q.value = 1.2;
-        const g = ac.createGain(), t = ac.currentTime;
-        g.gain.setValueAtTime(0.0001, t);
-        g.gain.exponentialRampToValueAtTime(Math.max(0.02, f.v * volume), t + 0.006);
-        g.gain.exponentialRampToValueAtTime(0.0001, t + f.d);
-        let node = g;
-        if (pan != null && ac.createStereoPanner) {
-            const p = ac.createStereoPanner();
-            p.pan.value = Math.max(-1, Math.min(1, pan));
-            g.connect(p);
-            node = p;
+    function tonePan(freq, dur, cat, pan, vol, type, pc) {
+        if (!audible())
+            return;
+        const ac = contextFor(pc);
+        if (!ac)
+            return;
+        try {
+            const o = ac.createOscillator(), g = ac.createGain(), t = ac.currentTime;
+            o.type = type || 'sine';
+            o.frequency.value = freq;
+            g.gain.setValueAtTime(0.0001, t);
+            g.gain.exponentialRampToValueAtTime(Math.max(0.02, (vol || 0.2) * volume), t + 0.01);
+            g.gain.exponentialRampToValueAtTime(0.0001, t + dur);
+            o.connect(g);
+            panned(ac, g, pan).connect(outFor(ac, cat, pc));
+            o.start(t);
+            o.stop(t + dur + 0.02);
+        }
+        catch (e) { /* noop */ }
+    }
+    // ===== The NOISE synth (footsteps by material, the cane). noiseBuffer caches per context (supports one per player). =====
+    function noiseHit(mat, pan, pc) {
+        if (!audible())
+            return;
+        const ac = contextFor(pc);
+        if (!ac)
+            return;
+        const f = FOOT[mat] || FOOT.piso;
+        try {
+            const src = ac.createBufferSource();
+            src.buffer = noiseBuffer(ac);
+            const bq = ac.createBiquadFilter();
+            bq.type = f.f;
+            bq.frequency.value = f.hz;
+            bq.Q.value = 1.2;
+            const g = ac.createGain(), t = ac.currentTime;
+            g.gain.setValueAtTime(0.0001, t);
+            g.gain.exponentialRampToValueAtTime(Math.max(0.02, f.v * volume), t + 0.006);
+            g.gain.exponentialRampToValueAtTime(0.0001, t + f.d);
+            src.connect(bq).connect(g);
+            panned(ac, g, pan).connect(outFor(ac, 'interact', pc));
+            src.start(t);
+            src.stop(t + f.d + 0.03);
+            footCount++;
         }
-        src.connect(bq).connect(g);
-        node.connect(pc ? pc.out : (catNode('interact') || audioOut() || ac.destination));
-        src.start(t);
-        src.stop(t + f.d + 0.03);
-        _footCount++;
+        catch (e) { /* noop */ }
     }
-    catch (e) { /* noop */ }
+    return {
+        get soundOn() { return soundOn; }, setSoundOn: (v) => { soundOn = v; },
+        get volume() { return volume; }, setVolume: (v) => { volume = v; },
+        get audioCtx() { return audioCtx; }, ensureAC, audioOut,
+        get hearingLoss() { return hearingLoss; }, setHearingLossGraph, setMasterMuted,
+        audioCat, onCatChange, catNode, setCatGain,
+        tone, tonePan, noiseHit,
+        get footCount() { return footCount; },
+    };
 }
-/* A TABELA DE EARCONS SAIU daqui em 2026-08-25 (item 19) — está em `game/earcons`.
- *
- * De dez earcons, sete eram deste jogo: `coin`/`key`/`gate`/`power` são objetos deste mundo e
- * `correct`/`wrong`/`place` são eventos da atividade. O gate acusava só a linha do `coin`, porque é a única
- * com palavra que o casador conhece — e a linha acusada era a menos interessante das dez.
- *
- * As legendas eram pt-BR CRU (`'🔊 Coletou'`, `'🔊 Portão abriu'`): nove frases dentro de um módulo de
- * plataforma, que o gate de i18n do `main.js` não alcança. Viraram CHAVES, e quem exibe resolve.
- *
- * O que ficou aqui é a SÍNTESE — oscilador, envelope, ruído, roteamento por categoria —, que serve a
- * qualquer jogo. O que é 880 Hz de triangular por 0,14 s ao pegar uma moeda, não. */
+/* What lives here is the SYNTHESIS — oscillator, envelope, noise, routing by category — which serves any game. A table of
+ * earcons does not: "880 Hz of triangle for 0.14 s when a coin is taken" is one game's world, and it lives with that game. */

package/dist-pkg/platform/choose-by-voice.d.ts

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type VoskDeps, type VoskLoad } from './vosk-runtime.js';
+import { type VoiceListenerDeps } from './voice-listener.js';
+/** What a choice gives back: the index of the option said, or `null`; what was heard; why it ended. */
+export interface ChoiceHeard {
+    readonly chosen: number | null;
+    readonly heard: string;
+    /** One option said · more than one said in one sentence · no option in time · asked to stop. */
+    readonly ended: 'chosen' | 'unclear' | 'timeout' | 'asked';
+}
+export interface ChooseSettings {
+    /** The language the options are in — the content's, when it is not the page's (ADR-0225). Default: the page's. */
+    readonly language?: string;
+    /** How long to wait for an option. Default 10 s: time to think, and a microphone that is never forgotten open. */
+    readonly maxMs?: number;
+    /**
+     * Called once, when the ear is OPEN and a word said now would be heard — at once when the 👄's ear is lent, after the model
+     * has loaded when one had to be opened. Before it, a game says «loading», not «say the answer»: the first choice in a language
+     * waits a few seconds for its model, and a child told to speak into that wait is not heard (the Dev, 2026-09-27).
+     */
+    readonly onListening?: () => void;
+}
+/** A recogniser listening with a grammar: it can be stopped, and it may say which words its model knows. */
+export interface OpenedChoice {
+    stop(): Promise<void>;
+    /** The words the language's model knows, when they can be read — an option with a word outside them can never be chosen. */
+    readonly vocabulary?: () => Promise<ReadonlySet<string> | null>;
+}
+export interface VoiceChooserDeps {
+    /** The page's language (`core/i18n.bcp47`). */
+    readonly language: () => string;
+    /**
+     * Opens the command recogniser for `language` with this grammar and the microphone, calling `onHeard` with every text it hears
+     * — `final` when the sentence ended. REJECTS, with the reason, when the model or the microphone cannot be had.
+     */
+    readonly open: (language: string, grammar: readonly string[], onHeard: (text: string, final: boolean) => void) => Promise<OpenedChoice>;
+    readonly after: (fn: () => void, ms: number) => unknown;
+    readonly cancel: (handle: unknown) => void;
+    /** A line for `problems`, written once per reason (ADR-0169). */
+    readonly report: (line: string) => void;
+    /**
+     * An ear ALREADY LISTENING in `language`, lent for this choice with the grammar given — the 👄's (`ui/voice-control.borrow`) — or
+     * `null`. Borrowed, nothing is opened and nothing paused: one model and one microphone, however many choices.
+     */
+    readonly borrow?: (language: string, grammar: readonly string[], onHeard: (text: string, final: boolean) => void) => OpenedChoice | null;
+    /** Called before an ear of its own is opened and after it is let go: the root pauses the 👄 in between (one ear per word). */
+    readonly pause?: () => void;
+    readonly resume?: () => void;
+}
+export interface VoiceChooser {
+    choose(options: readonly string[], settings?: ChooseSettings): Promise<ChoiceHeard>;
+    /** Ends the choice in hand now: it answers `null`, `ended: 'asked'`. */
+    stop(): void;
+}
+/** What opening the command recogniser for a choice uses of the delivery and the browser, lent by the root (ADR-0232 D4). */
+export type CommandRecogniserDeps = Omit<VoskDeps, 'language'> & Pick<VoiceListenerDeps, 'getUserMedia' | 'createContext'> & {
+    /** How a language's model is had — the root's `keepVoskModels(…).load`, so it is loaded once; default a fresh load. */
+    readonly load?: (d: VoskDeps) => Promise<VoskLoad>;
+};
+/**
+ * THE `open` A CHOOSER IS GIVEN WHERE THE COMMAND RECOGNISER IS THE EAR: the language's model from the delivery, then the
+ * microphone with the grammar. A model that opened for a microphone that did not is let go before the refusal travels.
+ */
+export declare function openWithCommandRecogniser(d: CommandRecogniserDeps): VoiceChooserDeps['open'];
+/**
+ * The options a sentence names, in the order said, each once: read word by word, the LONGEST option that starts at each word —
+ * so «cavalo marinho» is one option and not also «cavalo» — accents and case aside, whole words only.
+ */
+export declare function optionsNamed(options: readonly string[], sentence: string): number[];
+export declare function createVoiceChooser(d: VoiceChooserDeps): VoiceChooser;