@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/ui/voice-control.d.ts

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+import type { VirtualController } from '../input/virtual-controller.js';
+import { type VoskDeps, type VoskLoad } from '../platform/vosk-runtime.js';
+import { type VoiceListener, type VoiceListenerDeps } from '../platform/voice-listener.js';
+import type { SwitchableControl } from './switchable-control.js';
+/** How long a spoken position stays pressed. The same pulse the scan uses: long enough for a game to see a press and a release. */
+export declare const VOICE_PULSE_MS = 400;
+export interface VoiceControlDeps {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    readonly base: string;
+    /** The child's language (`core/i18n.bcp47`): it chooses the model AND the words. */
+    readonly language: () => string;
+    readonly controller: VirtualController;
+    /** The names the open menu is showing right now, if any (ADR-0194). */
+    readonly menuWords: () => readonly string[];
+    readonly say: (text: string) => void;
+    readonly alert: (text: string) => void;
+    readonly report: (line: string) => void;
+    /** Puts the 👄 back to off when nothing could start. */
+    readonly turnOff: () => void;
+    readonly after: (fn: () => void, ms: number) => void;
+    readonly hasFile: VoskDeps['hasFile'];
+    readonly loadBundle: VoskDeps['loadBundle'];
+    readonly getUserMedia: VoiceListenerDeps['getUserMedia'];
+    readonly createContext: VoiceListenerDeps['createContext'];
+    readonly loadRuntime?: (deps: VoskDeps) => Promise<VoskLoad>;
+    readonly listen?: (deps: VoiceListenerDeps) => Promise<VoiceListener>;
+}
+/**
+ * 🎯 THE VOICE IS IN THE FAMILY AND NOT IN THE CAMERA'S CYCLE (ADR-0221 step 7f): it answers the 👄 and not the 📷, and has
+ * one more method. Declaring the family is what makes the compiler see it turns on and off like the other three.
+ */
+export interface VoiceControl extends SwitchableControl {
+    /** The open menu changed: the words it shows join the grammar, or leave it. */
+    refreshGrammar(): void;
+    /**
+     * THE CHILD'S LANGUAGE CHANGED (ADR-0225): the model, the vocabulary and the grammar are chosen again.
+     *
+     * 📌 A listening recogniser is restarted, which costs the model being opened once more; one that is off has nothing to do,
+     * because the next start already reads the new language.
+     */
+    languageChanged(): Promise<void>;
+}
+export declare function createVoiceControl(d: VoiceControlDeps): VoiceControl;

package/dist-pkg/ui/voice-control.js

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/voice-control — PLAYING BY VOICE, PUT TOGETHER (ADR-0189, ADR-0193, ADR-0194, ADR-0204 erratum; issues #184, #190).
+//
+// The four pieces that existed separately, joined: the Dev's vocabulary and the firing rule (`input/voice-map`), the recogniser
+// opened from the delivery (`platform/vosk-runtime`), the microphone that stays open (`platform/voice-listener`), and the
+// presses on the virtual controller with the source `fala` (ADR-0111). The 👄 of the quick bar drives it; what cannot start is
+// SAID, written once in `problems`, and puts the icon back to off — a child must never meet a button that does nothing.
+//
+// 📌 THE GRAMMAR FOLLOWS THE MENU (ADR-0194): saying the name of an item activates it, so the words the open menu is showing
+// join the closed grammar while it is open and leave with it.
+//
+// ⚠️ A SPOKEN COMMAND IS A TAP, NOT A HOLD. The word arrives, the position is pressed and let go — and the latch (ADR-0211,
+// always on for speech) is what keeps a direction held afterwards. That division is the whole reason the latch is forced there:
+// a child who says «acima» cannot also say «and keep holding it».
+import { voiceGrammar, createVoiceCommands } from '../input/voice-map.js';
+import { loadVoskRuntime } from '../platform/vosk-runtime.js';
+import { startVoiceListening } from '../platform/voice-listener.js';
+/** How long a spoken position stays pressed. The same pulse the scan uses: long enough for a game to see a press and a release. */
+export const VOICE_PULSE_MS = 400;
+export function createVoiceControl(d) {
+    const { t } = d;
+    const loadRuntime = d.loadRuntime ?? loadVoskRuntime;
+    const listen = d.listen ?? startVoiceListening;
+    const said = new Set();
+    let on = false, starting = null;
+    let listener = null;
+    let commands = null;
+    const grammarNow = () => voiceGrammar(d.language(), d.menuWords());
+    const command = (action) => {
+        d.controller.press(action, 'fala');
+        d.after(() => d.controller.release(action, 'fala'), VOICE_PULSE_MS);
+    };
+    const stop = () => {
+        const going = listener;
+        listener = null;
+        commands = null;
+        void going?.stop();
+    };
+    /**
+     * Nothing started: the child hears why, the adult reads it once, and the icon goes back to off. A failure that arrives after
+     * the 👄 was turned off (or the root disposed, ADR-0220) has nobody waiting for it and says and writes nothing.
+     */
+    const failed = (kind, line, spoken) => {
+        if (!on)
+            return;
+        if (!said.has(kind)) {
+            said.add(kind);
+            d.report(line);
+        }
+        d.alert(spoken);
+        d.turnOff();
+    };
+    const start = async () => {
+        /*
+         * 🔴 THE LOAD IS INSIDE A `try` AND THIS WAS MEASURED, not foreseen: on 2026-09-21 the delivery's bundle turned out to be an
+         * ES module and the loader threw. Nothing here caught it, so the rejection died as an unhandled promise and the 👄 STAYED
+         * LIT over a microphone that had never opened — the exact defect this module exists to prevent, one layer above where it
+         * was being prevented. A failure that has no name is still a failure the child has to be told about.
+         */
+        let load;
+        const language = d.language();
+        try {
+            load = await loadRuntime({ base: d.base, language, hasFile: d.hasFile, loadBundle: d.loadBundle });
+        }
+        catch (e) {
+            failed('runtime', `voice control: the recogniser did not open (${e instanceof Error ? e.message : String(e)}) — the child `
+                + 'cannot play by speaking; check that the delivery carries the command files', t('sr.voice.failed'));
+            return;
+        }
+        if (!load.ok) {
+            /*
+             * 📌 ONE LINE PER LANGUAGE, NAMING THAT LANGUAGE'S FIX (ADR-0225, ADR-0169). The install fetches the command model of the
+             * BOOT language only, so a child who switches can ask for one the delivery never carried; «open it online» alone sends
+             * the adult after a download that cannot happen. The reading's line names `--reading <language>` the same way.
+             */
+            const lang = language.split('-')[0].toLowerCase();
+            failed(`files:${lang}`, `voice control: ${load.missing.join(', ')} not on this device for ${language} — the child cannot play `
+                + `by speaking in this language; build the delivery with \`npx inclusionist-heavy --commands ${lang}\` and open the game `
+                + 'once online in this language so the install fetches them', t('sr.voice.needsInternet'));
+            return;
+        }
+        commands = createVoiceCommands(d.language());
+        try {
+            listener = await listen({
+                model: load.model,
+                grammar: grammarNow(),
+                getUserMedia: d.getUserMedia,
+                createContext: d.createContext,
+                onPartial: (text) => { const a = commands?.partial(text); if (a)
+                    command(a); },
+                onFinal: () => commands?.reset(),
+            });
+        }
+        catch {
+            failed('microphone', 'voice control: the microphone did not open — the child cannot play by speaking; allow the microphone '
+                + 'for this page, or plug one in', t('sr.voice.noMicrophone'));
+            return;
+        }
+        // ⚠️ TURNED OFF WHILE IT WAS STARTING: the microphone opened after the child let go of the icon, and a listener nobody asked
+        // for would go on hearing her. The check is here and not only in `apply`, because starting is not instantaneous.
+        if (!on) {
+            stop();
+            return;
+        }
+        d.say(t('sr.voice.ready'));
+    };
+    const api = {
+        async apply(next) {
+            on = next;
+            if (!next) {
+                stop();
+                return;
+            }
+            if (listener || starting)
+                return;
+            starting = start().finally(() => { starting = null; });
+            await starting;
+        },
+        refreshGrammar() {
+            listener?.setGrammar(grammarNow());
+        },
+        async languageChanged() {
+            /*
+             * 🔴 THE RECOGNISER STOPS CHOOSING ITS LANGUAGE ONCE (ADR-0225). `start()` reads `d.language()` for the MODEL and for the
+             * vocabulary, and it used to read it only at the moment the 👄 was switched on — so a child who changed language while
+             * listening went on being heard in the old one.
+             * ⚠️ AND THAT IS WORSE THAN STOPPING, which is why this is not cosmetic: the grammar DOES follow, because it is rebuilt
+             * whenever a menu opens (ADR-0194). So after a change the new language's words were fed to the old language's model, and
+             * a closed grammar answers with the nearest candidate — measured in the lab on 2026-09-14, where «configurações de
+             * inclusão» came back as «quatro». A microphone that acts on a word the child did not say is the defect here.
+             * 📌 OFF IS ALREADY RIGHT: the next start reads the language then. This only has work to do while it is listening.
+             */
+            if (!on)
+                return;
+            // ⚠️ A START IN FLIGHT IS IN THE OLD LANGUAGE. Letting it finish and replacing it costs one opening; skipping it would
+            // leave `starting` to install the old model on top of the new one, which is the race the `if (!on)` in `start` exists for.
+            await starting;
+            stop();
+            await api.apply(true);
+        },
+    };
+    return api;
+}

package/dist-pkg/ui/voice-settings.d.ts

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translator } from '../core/i18n.js';
+import type { DomQuery } from '../core/dom-query.js';
+import { type AudioCatState } from './audio-choices.js';
+export interface TtsPanelEngine {
+    id: string;
+    speak: (text: string) => void;
+}
+/** Minimal shape of the injected `tts` (platform/tts.ts's createTts() instance) this section drives. */
+export interface TtsPanel {
+    getEngineSel: () => string;
+    setEngineSel: (v: string) => void;
+    getEngine: () => TtsPanelEngine | null;
+    getVoiceObj: () => SpeechSynthesisVoice | null;
+    setVoiceObj: (v: SpeechSynthesisVoice | null) => void;
+    loadTTS: () => void;
+    narrate: (text: string) => void;
+    /**
+     * Does this assembly have a neural engine (the game's Kokoro port, ADR-0198)? Optional, absent reads `true`: a panel test
+     * fake written before this field has no opinion on neural engines.
+     */
+    neuralAvailable?: boolean;
+    /** The voices of the language (ADR-0185). Optional: a panel driven without them offers no «Voz» list and locks nothing. */
+    voices?: () => readonly PanelVoice[];
+    currentVoice?: () => PanelVoice | null;
+    setVoice?: (id: string) => boolean;
+}
+/** A voice as this panel lists it: `webspeech:<name>` for the browser's, `xx_name` for Kokoro's. */
+export interface PanelVoice {
+    readonly voice: string;
+    readonly engine?: string;
+    readonly recommended?: boolean;
+}
+/**
+ * The browser, as four functions.
+ *
+ * 🔴 A module that reaches `document` or `window` undoes a decision (ADR-0178), and the health ratchet refuses a NEW one that
+ * does. These four are what the voice section actually needs from the browser, and naming them is what makes the section
+ * testable: hand it a fake `doc`, a list of voices and two no-ops, and every branch below runs without a speech engine.
+ */
+export interface VoicePorts {
+    /** Makes one <option> — the only element this section builds. A FUNCTION and not the document: a port read at wiring
+     *  time would make a panel unmountable where there is no document yet, and the node suite mounts exactly there. */
+    readonly newOption: () => HTMLOptionElement;
+    /** The system voices, or an empty list where the browser has none or throws. */
+    readonly systemVoices: () => readonly SpeechSynthesisVoice[];
+    /** Speak the sample through the BROWSER's own synthesiser — the neural engine speaks through `tts` instead. */
+    readonly speakSample: (text: string, chosen: SpeechSynthesisVoice | null) => void;
+    /** Called again whenever the browser finishes loading its voice list: they arrive late, and often empty first.
+     *  ⚠️ The parameter is gain and not
+  un, which is a GAME ACTION word this layer does not say (the boundary of 2026-09-06). */
+    readonly whenVoicesChange: (again: () => void) => void;
+}
+/**
+ * What this section needs from the panel's ctx.
+ *
+ * ⚠️ The store shape is written here and NOT imported from `ui/settings-audio`, which declares the same two methods: that
+ * module imports this one, and importing it back would be the cycle ADR-0173 forbids — for a type as much as for a value.
+ */
+/**
+ * THE SETTINGS THIS SECTION READS AND WRITES — the page's settings store, built by the root (ADR-0232 D2c, issue #207): the
+ * spoken index (ADR-0044 item 3) and the speech rate (ADR-0183). The names are `core/state`'s, so a root passes the store
+ * itself; the reads are LIVE, because the quick bar and a second screen change them too.
+ */
+export interface VoiceSettingsStore {
+    readonly menuIndexOn: boolean;
+    setMenuIndexOnValue(on: boolean): void;
+    readonly speechPpm: number;
+    setSpeechPpmValue(ppm: number): void;
+}
+export interface VoiceSettingsCtx {
+    /**
+     * The root's translator (ADR-0232 D3): its `t`, and the page's language as a BCP-47 tag, which picks the system voices the
+     * list offers. A Pick and not a bare `t`, because the voice list reads the language.
+     */
+    translator: Pick<Translator, 't' | 'bcp47'>;
+    /** The page's settings store (see `VoiceSettingsStore`). REQUIRED: a section reading from nowhere would show the defaults. */
+    settings: VoiceSettingsStore;
+    $: DomQuery;
+    srSay: (msg: string) => void;
+    toggleBtn: (btn: HTMLElement, on: boolean) => void;
+    store: {
+        get(key: string, fallback?: string | null): string | null;
+        set(key: string, value: string | number | boolean): boolean;
+    };
+    tts: TtsPanel;
+    getAudioCat: () => Record<string, AudioCatState> | null;
+    setCatGain: (k: string) => void;
+}
+export interface VoiceSettings {
+    /** Everything the section shows, refreshed from the stored state. Called by the panel's own render. */
+    render: () => void;
+    /** Just the narration switch and the chosen engine. Exported because the quick bar's icon reflects it from outside. */
+    reflectTts: () => void;
+}
+export declare function createVoiceSettings(ctx: VoiceSettingsCtx, ports: VoicePorts): VoiceSettings;

package/dist-pkg/ui/voice-settings.js

@@ -0,0 +1,302 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/voice-settings — THE VOICE SECTION of the hearing panel: the narration switch, the engine, the voice, the rate, the
+// spoken index and the sample button (ADR-0221; issue #203).
+//
+// 🔴 WHY IT LEFT `ui/settings-audio`: that module was the third largest in the engine, and half of it was about SPEECH while
+// the other half was about sound categories, the cane, blind mode and the audio outputs. The two halves never needed each
+// other. What binds these seven pieces is one question — «what does the child hear when the engine talks, and what does she
+// change to hear it differently».
+//
+// ⚠️ AND IT RECEIVES THE BROWSER INSTEAD OF REACHING IT, which the ratchet of ADR-0221 step 7d made compulsory rather than
+// tasteful: a module born today that reaches a global is refused, because there the ceiling is ZERO and not a p90. So
+// `document.createElement`, `speechSynthesis.getVoices`, the sample utterance and the `onvoiceschanged` subscription arrive
+// as four ports. What that buys beyond the gate: the whole section can be exercised without a browser's speech engine.
+//
+// 📌 THE SPOKEN INDEX («6 of 10») LIVES HERE and not in a visual panel, by the decision of ADR-0044 item 3: it changes the
+// NARRATION, and whoever turns it off is shortening what she hears at every step. She comes here when what she hears bothers
+// her.
+import { toggleLabel } from './dom.js';
+import { SPEECH_RATES } from '../core/speech-rate.js';
+import { volPercent, voiceEngineOptions, pickVoicesFor, voiceLabel, } from './audio-choices.js';
+/** The name a child sees for a voice: the browser's name, or the name inside a Kokoro identifier — `pf_dora` is «Dora». */
+function voiceName(v) {
+    // a browser voice is named by the browser (ADR-0200); Kokoro ids read `xx_name` (`pf_dora`)
+    // («Microsoft Maria - Portuguese (Brazil)» is «Microsoft Maria»: the language is already the list's, and no parentheses, ADR-0158)
+    if (v.voice.startsWith('webspeech:'))
+        return v.voice.slice('webspeech:'.length).replace(/\s*\([^)]*\)/g, '').split(' - ')[0].trim();
+    const name = v.voice.split('_')[1] ?? v.voice;
+    return name.charAt(0).toUpperCase() + name.slice(1);
+}
+/**
+ * What the list SHOWS: Kokoro's two good voices, Heart and Bella, carry a heart (ADR-0198 §3). Only SHOWN: what is said is
+ * the name alone (ADR-0159 rule 12, no glyph inside a spoken name).
+ */
+function panelVoiceLabel(v) {
+    return (v.recommended ? '❤️ ' : '') + voiceName(v);
+}
+/** The rows a missing voice locks (ADR-0185 §4): narration, its volume and rate, the spoken index, and the voice. */
+const SPEECH_ROWS = ['#opt-tts', '#tts-vol', '#tts-ppm', '#opt-menuindex', '#tts-voz'];
+export function createVoiceSettings(ctx, ports) {
+    const { t, bcp47 } = ctx.translator;
+    function reflectTts() {
+        const b = ctx.$('#opt-tts');
+        const cat = ctx.getAudioCat();
+        const on = !!(cat && cat.tts && cat.tts.on);
+        if (b) {
+            ctx.toggleBtn(b, on);
+            b.textContent = toggleLabel(t, on);
+        }
+        const e = ctx.$('#tts-engine');
+        if (e)
+            e.value = ctx.tts.getEngineSel();
+    }
+    function reflectMenuIndex() {
+        const b = ctx.$('#opt-menuindex');
+        if (b) {
+            ctx.toggleBtn(b, ctx.settings.menuIndexOn);
+            b.textContent = toggleLabel(t, ctx.settings.menuIndexOn);
+        }
+    }
+    function populateTtsEngines() {
+        const sel = ctx.$('#tts-engine');
+        if (!sel || sel.dataset.filled)
+            return;
+        sel.dataset.filled = '1';
+        voiceEngineOptions(ctx.tts.neuralAvailable !== false).forEach(([v, l]) => {
+            const o = ports.newOption();
+            o.value = v;
+            o.textContent = t(l);
+            sel.appendChild(o);
+        });
+        sel.value = ctx.tts.getEngineSel();
+    }
+    function populateTtsVoices() {
+        const sel = ctx.$('#tts-voice');
+        if (!sel)
+            return;
+        const list = pickVoicesFor(ports.systemVoices(), bcp47());
+        sel.innerHTML = '';
+        if (!list.length) {
+            const o = ports.newOption();
+            o.textContent = t('audio.noSystemVoices');
+            sel.appendChild(o);
+            ctx.tts.setVoiceObj(null);
+            return;
+        }
+        list.forEach((v) => {
+            const o = ports.newOption();
+            o.value = v.name;
+            o.textContent = voiceLabel(v);
+            sel.appendChild(o);
+        });
+        const saved = ctx.store.get('incl_tts_voice', null);
+        const pick = list.find((v) => v.name === saved) || list[0];
+        sel.value = pick.name;
+        ctx.tts.setVoiceObj(pick);
+    }
+    const noVoice = () => !!ctx.tts.voices && ctx.tts.voices().length === 0;
+    /** The speech rate list: each step «N PPM», the stored one selected (ADR-0183 §1, ADR-0196). */
+    function renderRate() {
+        const sel = ctx.$('#tts-ppm');
+        if (!sel)
+            return;
+        while (sel.firstChild)
+            sel.removeChild(sel.firstChild);
+        for (const ppm of SPEECH_RATES) {
+            const o = ports.newOption();
+            o.value = String(ppm);
+            o.textContent = t('visual.legenda.ppm', { n: ppm });
+            sel.appendChild(o);
+        }
+        sel.value = String(ctx.settings.speechPpm);
+    }
+    function renderVoiceList() {
+        const sel = ctx.$('#tts-voz');
+        if (!sel || !ctx.tts.voices)
+            return;
+        const list = ctx.tts.voices();
+        sel.replaceChildren(); // options built node by node: no markup sink
+        if (!list.length) {
+            const o = ports.newOption();
+            o.textContent = t('audio.voz.nenhuma');
+            sel.appendChild(o);
+            return;
+        }
+        for (const v of list) {
+            const o = ports.newOption();
+            o.value = v.voice;
+            o.textContent = panelVoiceLabel(v);
+            sel.appendChild(o);
+        }
+        sel.value = ctx.tts.currentVoice?.()?.voice ?? list[0].voice;
+    }
+    /**
+     * No voice speaks the language (ADR-0185 §4): the five speech rows are LOCKED with the reason, never hidden (ADR-0161).
+     * `aria-disabled` and not `disabled`, so the keyboard still reaches the row and hears why.
+     */
+    function lockSpeechRows() {
+        const lock = noVoice();
+        for (const id of SPEECH_ROWS) {
+            const el = ctx.$(id);
+            if (!el)
+                continue;
+            if (lock) {
+                el.setAttribute('aria-disabled', 'true');
+                el.dataset.motivo = t('audio.semVoz');
+            }
+            else {
+                el.removeAttribute('aria-disabled');
+                delete el.dataset.motivo;
+            }
+        }
+    }
+    /*
+     * A LOCKED SPEECH ROW DOES NOTHING AND SAYS WHY (ADR-0185 §4). In the CAPTURE phase on the control itself, so it runs
+     * before the row's own listener and stops it; a moved range goes back to the stored volume, a changed list to the voice in
+     * use. The footer shows the reason when the row takes focus: the card hears `focusin` after the row's own explanation.
+     */
+    /**
+     * What a refused control puts back, by row: the moved volume to the stored one, the picked voice and rate to the ones in use.
+     * A row not here has nothing to undo (a switch was never flipped). A table, as the other «which row does what» answers here.
+     */
+    const UNDO_ON_REFUSAL = {
+        '#tts-vol': (el) => { const cat = ctx.getAudioCat(); if (cat?.tts)
+            el.value = String(volPercent(cat.tts.vol)); },
+        '#tts-voz': () => renderVoiceList(),
+        '#tts-ppm': () => renderRate(),
+    };
+    function refuseWhileLocked() {
+        for (const id of SPEECH_ROWS) {
+            const el = ctx.$(id);
+            if (!el)
+                continue;
+            const refuse = (e) => {
+                if (el.getAttribute('aria-disabled') !== 'true')
+                    return;
+                e.stopImmediatePropagation();
+                e.preventDefault();
+                UNDO_ON_REFUSAL[id]?.(el);
+                ctx.srSay(el.dataset.motivo ?? t('audio.semVoz'));
+            };
+            for (const kind of ['click', 'input', 'change'])
+                el.addEventListener(kind, refuse, true);
+            el.closest('.overlay__card')?.addEventListener('focusin', (e) => {
+                if (e.target !== el || el.getAttribute('aria-disabled') !== 'true')
+                    return;
+                const footer = el.closest('.overlay__card')?.querySelector('.opt-explain');
+                if (footer)
+                    footer.textContent = el.dataset.motivo ?? '';
+            });
+        }
+    }
+    refuseWhileLocked();
+    /**
+     * THE SEVEN CONTROLS, wired where the page carries them: the voice list, the rate, the narration switch, the spoken
+     * index, and the three the engine never builds but a page may (the engine selector, the system voice, the sample).
+     * A page that lacks one simply has that row missing.
+     */
+    function wireControls() {
+        const voiceSel = ctx.$('#tts-voz');
+        if (voiceSel)
+            voiceSel.addEventListener('change', () => {
+                if (!ctx.tts.setVoice?.(voiceSel.value)) {
+                    renderVoiceList();
+                    return;
+                }
+                const v = ctx.tts.currentVoice?.();
+                if (v)
+                    ctx.srSay(t('sr.audio.voz', { nome: voiceName(v) }));
+            });
+        const rateSel = ctx.$('#tts-ppm');
+        if (rateSel)
+            rateSel.addEventListener('change', () => {
+                ctx.settings.setSpeechPpmValue(Number(rateSel.value));
+                renderRate();
+                ctx.srSay(`${t('audio.ttsPpm')}: ${t('visual.legenda.ppm', { n: ctx.settings.speechPpm })}`);
+            });
+        const ttsBtn = ctx.$('#opt-tts');
+        if (ttsBtn)
+            ttsBtn.addEventListener('click', () => {
+                const cat = ctx.getAudioCat();
+                if (!cat)
+                    return;
+                cat.tts.on = !cat.tts.on;
+                ctx.setCatGain('tts');
+                reflectTts();
+                ctx.srSay(t(cat.tts.on ? 'sr.audio.ttsOn' : 'sr.audio.ttsOff'));
+                if (cat.tts.on)
+                    ctx.tts.narrate(t('sr.audio.ttsOnSpoken'));
+            });
+        const idxBtn = ctx.$('#opt-menuindex');
+        if (idxBtn)
+            idxBtn.addEventListener('click', () => {
+                ctx.settings.setMenuIndexOnValue(!ctx.settings.menuIndexOn);
+                reflectMenuIndex();
+                // The announcement of the change carries NO index: it is not an item of any list, and a «1 of 1» here would be noise at
+                // exactly the moment the child is judging whether the noise bothers her.
+                ctx.srSay(t(ctx.settings.menuIndexOn ? 'sr.menu.indexOn' : 'sr.menu.indexOff'));
+            });
+        const ttsEngSel = ctx.$('#tts-engine');
+        if (ttsEngSel)
+            ttsEngSel.addEventListener('change', () => {
+                ctx.tts.setEngineSel(ttsEngSel.value);
+                ctx.store.set('incl_tts_engine', ttsEngSel.value);
+                if (ttsEngSel.value !== 'webspeech')
+                    ctx.tts.loadTTS();
+                const opt = ttsEngSel.options[ttsEngSel.selectedIndex];
+                ctx.tts.narrate(t('sr.audio.engineSet', { motor: opt ? opt.text : '' }));
+            });
+        const ttsVoiceSel = ctx.$('#tts-voice');
+        if (ttsVoiceSel)
+            ttsVoiceSel.addEventListener('change', () => {
+                ctx.tts.setVoiceObj(ports.systemVoices().find((v) => v.name === ttsVoiceSel.value) || null);
+                ctx.store.set('incl_tts_voice', ttsVoiceSel.value);
+                ctx.tts.narrate(t('sr.audio.voicePicked'));
+            });
+        const ttsTestBtn = ctx.$('#opt-tts-test');
+        if (ttsTestBtn)
+            ttsTestBtn.addEventListener('click', () => {
+                const sample = t('audio.voiceSample');
+                const engine = ctx.tts.getEngine();
+                if (ctx.tts.getEngineSel() !== 'webspeech' && engine && engine.speak) {
+                    try {
+                        engine.speak(sample);
+                    }
+                    catch (e) { /* noop */ } // the neural engine is already loaded
+                }
+                else {
+                    ports.speakSample(sample, ctx.tts.getVoiceObj()); // audible fallback (volume 1) + starts the neural download
+                    if (ctx.tts.getEngineSel() !== 'webspeech')
+                        ctx.tts.loadTTS();
+                }
+                ctx.srSay(t('sr.audio.testingVoice'));
+            });
+        const ttsVolEl = ctx.$('#tts-vol');
+        if (ttsVolEl)
+            ttsVolEl.addEventListener('input', () => {
+                const cat = ctx.getAudioCat();
+                if (!cat)
+                    return;
+                cat.tts.vol = (+ttsVolEl.value) / 100;
+                cat.tts.on = true;
+                ctx.setCatGain('tts');
+                reflectTts();
+            });
+    }
+    wireControls();
+    ports.whenVoicesChange(populateTtsVoices);
+    return {
+        render: () => {
+            reflectTts();
+            // 🔴 THIS ONE WAS MISSING, and only the case for the engine-mounted panel saw it (2026-09-12): the index is born ON, the
+            // button was born with no state, and the panel opened saying «off» — the control lying to the screen reader again.
+            reflectMenuIndex();
+            populateTtsEngines();
+            populateTtsVoices();
+            renderVoiceList();
+            renderRate();
+            lockSpeechRows();
+        },
+        reflectTts,
+    };
+}

package/dist-pkg/ui/where-the-child-is.d.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+export interface WhereTheChildIsCtx {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    /** The overlay on top, if any — the same one the focus trap and the menu navigation treat as «the open menu». */
+    readonly topVisibleOverlay: () => HTMLElement | null;
+    /** The pause card, when it is showing. */
+    readonly pauseCard: () => HTMLElement | null;
+    /** Who has the focus right now: it decides WHICH item of a panel is named. */
+    readonly focused: () => Element | null;
+    /**
+     * Does this cartridge want «N of M» spoken (ADR-0167)? It is only ever SPOKEN — never drawn — and a cartridge may
+     * silence it.
+     */
+    readonly withIndex: () => boolean;
+}
+/** Where the child is: a key to compare, and the sentence to say when it changed. */
+export interface Place {
+    /** What «did she move?» is decided on. It names the panel or the card's open list, never just «a panel». */
+    readonly key: string;
+    /** What to say on arriving here — `null` in play, which is announced by the caller in its own words. */
+    readonly sentence: string | null;
+}
+/**
+ * The place, in the order the screen reads: a panel sits over the card, the card sits over the game.
+ *
+ * 📌 PLAY HAS NO SENTENCE HERE and that is deliberate: «back to the game» is the caller's word for its own world, and
+ * this module has no business naming a game it does not know.
+ */
+export declare function whereTheChildIs(ctx: WhereTheChildIsCtx): Place;