@the-inclusionist/engine 6.36.1

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

@@ -0,0 +1,544 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/settings-audio — Audio panel (Estágio 4, #audio overlay): extracted from game.js's renderAudio()/
+// renderAudioSinks()/catRowHTML/wireCatControls/renderNavSound/reflectAudioMaster + the TTS-panel functions that
+// platform/tts.ts already documents as belonging here (reflectTTS/populateTTSEngines/populateTTSVoices). Pure
+// logic (category markup, volume->percent, sink option/label, cane-div validation, pt-BR voice filtering) is
+// separated from the thin DOM-touching render/wire functions. DI via initSettingsAudio(ctx): `$`, `srSay`,
+// `store` (narrow get/set), the live sound/mixer primitives from platform/audio.ts (getSoundOn/setSoundOn/
+// getVolume/setVolume/getAudioCat/setCatGain), the injected `tts` panel API (platform/tts.ts), and the SHARED
+// game.js helpers other panels also use (`toggleBtn`, `getNumPlayers`/`getPlayers`) or that live outside audio
+// entirely (`getModoCego`/`setModoCego`, `getCaneBlockDiv`/`setCaneBlockDiv` — core collision state; the widgets
+// live in this overlay, the state does not). Overlay open/close plumbing (#audio hidden toggle, frontOverlay,
+// focus management, Escape, `ensureAC()`) is the shared infra every settings panel uses and stays in game.js,
+// which calls `renderAudio()` from its `openAudio()`. `reflectModoCego`/`reflectTts` are also exported because
+// game.js's own `setModoCego()` and the pause-menu icon bar (`iconAct('tts'|'blind', …)`) call them directly.
+/** Minimal DOM-selector shape (matches ui/dom.ts's `$`). */
+import { toggleLabel } from './dom.js';
+import { t, bcp47 } from '../core/i18n.js';
+import { DEFAULTS } from '../core/state.js';
+// O módulo INTEIRO, e não os nomes soltos: `menuIndexOn` é ligação viva e `setMenuIndexOnValue` a muda — ler
+// pelo namespace deixa isso à vista em cada uso, em vez de parecer uma constante importada.
+import * as state from '../core/state.js';
+import { markChanged, markMenuChanged } from './changed-mark.js';
+import { defaultAudioCat } from '../platform/audio-mixer.js';
+// ---------------------------------------------------------------------------------------------
+// Pure logic (no `document`, testable in node)
+// ---------------------------------------------------------------------------------------------
+/** Categorias de NAVEGAÇÃO SONORA (bengala/sonar/guarda/guia) — volume geral separado do som do jogo. */
+export const NAV_CATS = ['sonar', 'guard', 'guide'];
+/** Categorias GERAIS do jogo (TTS fica na seção Voz, fora desta lista). */
+export const GEN_CATS = ['music', 'ambient', 'interact', 'earcons', 'other'];
+/** 0..1 -> 0..100 rounded (slider display value). */
+export function volPercent(v) {
+    return Math.round(v * 100);
+}
+/** One category row's markup (volume slider + on/off switch). Pure — resolves label/state from the given data,
+ *  never from a global. Returns '' for an unknown/missing category (defensive; never hit with real catalogs). */
+export function catRowHTML(k, cats, state) {
+    const c = cats.find((x) => x.k === k);
+    const a = state[k];
+    if (!c || !a)
+        return '';
+    return `<div class="ctrl-row"><span>${c.lbl}</span><span style="display:flex;gap:.5rem;align-items:center;flex-shrink:0">` +
+        `<input class="vol" type="range" min="0" max="100" step="5" value="${volPercent(a.vol)}" data-avol="${k}" aria-label="Volume de ${c.lbl}">` +
+        `<button class="mode-btn switch${a.on ? ' is-on' : ''}" data-acat="${k}" type="button" aria-pressed="${a.on}" aria-label="${c.lbl}"></button></span></div>`;
+}
+/** Full innerHTML for a category list (#audio-list or #navsound-list). Pure string building — no DOM. */
+export function catsListHTML(keys, cats, state) {
+    return keys.map((k) => catRowHTML(k, cats, state)).join('');
+}
+/** #navsound-master's value: the loudest of the nav categories, as a 0..100 slider value. */
+export function navMasterVolume(state, navCats = NAV_CATS) {
+    return volPercent(Math.max(...navCats.map((k) => state[k].vol)));
+}
+/** Cane-hit spacing select -> validated int (garbage/empty -> 1, "a batida por bloco"). */
+export function parseCaneDiv(raw) {
+    return (+raw) || 1;
+}
+/** srSay text for a cane-hit spacing choice. The two halves are ONE sentence per case, not a shared prefix
+ *  plus a tail: a language that renders this as "One tap per block (cane)" needs to move the word "cane". */
+export function caneDivMessage(div) {
+    return t(div === 2 ? 'sr.audio.caneHalfBlock' : 'sr.audio.canePerBlock');
+}
+/** #tts-engine's option catalog: (value, i18n KEY of the label). The engine NAMES are proper nouns and stay
+ *  put; what translates is the parenthetical that explains each one. Keys, not text — see input/devices. */
+export const TTS_ENGINE_OPTIONS = [
+    ['webspeech', 'tts.engine.webspeech'],
+    ['piper', 'tts.engine.piper'],
+    ['kokoro', 'tts.engine.kokoro'],
+    ['kitten', 'tts.engine.kitten'],
+    ['espeak', 'tts.engine.espeak'],
+];
+/**
+ * As vozes do sistema no idioma pedido; sem nenhuma, a lista inteira.
+ *
+ * Chamava-se `pickPtVoices` e filtrava `/^pt/i` fixo, de modo que o jogo em inglês oferecia à pessoa uma
+ * lista de vozes PORTUGUESAS para ler texto em inglês. O nome dizia a verdade sobre o que fazia e mentia
+ * sobre o que devia fazer.
+ *
+ * A comparação é pelo PREFIXO de idioma, não pela etiqueta inteira: quem joga em pt-BR também deve poder
+ * escolher uma voz pt-PT se for a única instalada, e o navegador de uma escola raramente tem a variante
+ * exata. O recuo para a lista inteira fica: uma lista vazia seria pior que uma lista no idioma errado, que
+ * ao menos a pessoa pode ouvir e rejeitar.
+ */
+export function pickVoicesFor(voices, lang) {
+    const pref = lang.slice(0, 2).toLowerCase();
+    const iguais = voices.filter((v) => v.lang.slice(0, 2).toLowerCase() === pref);
+    return iguais.length ? iguais : voices;
+}
+/** "<name> (<lang>)" option label. */
+export function voiceLabel(v) {
+    return v.name + ' (' + v.lang + ')';
+}
+/** Whether the browser can list/switch audio outputs at all (gates the #audio-sinks hint copy). */
+export function sinksSupported(hasEnumerateDevices, hasAudioContextCtor) {
+    return hasEnumerateDevices && hasAudioContextCtor;
+}
+/** A device's option label, falling back to a 1-based "Saída N" when the browser withholds the real label
+ *  (no getUserMedia permission granted yet). */
+export function sinkOptionLabel(d, index) {
+    return d.label || t('audio.sinkFallback', { n: index + 1 });
+}
+/** A player's current sink select value ('' = default/shared). */
+export function sinkSelectValue(p) {
+    return (p && p.audioSink) || '';
+}
+// ---------------------------------------------------------------------------------------------
+// DOM-facing (thin) — requires `document`/injected ctx
+// ---------------------------------------------------------------------------------------------
+export function initSettingsAudio(ctx) {
+    let audioDevices = [];
+    function reflectMaster() {
+        const b = ctx.$('#audio-master');
+        if (b) {
+            b.classList.toggle('is-on', ctx.getSoundOn());
+            b.setAttribute('aria-pressed', String(ctx.getSoundOn()));
+            b.textContent = ctx.getSoundOn() ? '🔊 Ligado' : '🔇 Desligado';
+        }
+        const v = ctx.$('#audio-master-vol');
+        if (v)
+            v.value = String(volPercent(ctx.getVolume()));
+        const sb = ctx.$('#opt-sound');
+        if (sb)
+            ctx.toggleBtn(sb, ctx.getSoundOn());
+    }
+    function wireCatControls(el) {
+        el.querySelectorAll('button[data-acat]').forEach((b) => {
+            b.addEventListener('click', () => {
+                const k = b.dataset.acat;
+                if (!k)
+                    return;
+                const state = ctx.getAudioCat();
+                if (!state || !state[k])
+                    return;
+                state[k].on = !state[k].on;
+                ctx.setCatGain(k);
+                b.classList.toggle('is-on', state[k].on);
+                b.setAttribute('aria-pressed', String(state[k].on));
+                refreshMarks(); // a marca acompanha a MUDANÇA, não só o redesenho — ver a nota em refreshMarks
+            });
+        });
+        el.querySelectorAll('input[data-avol]').forEach((s) => {
+            s.addEventListener('input', () => {
+                const k = s.dataset.avol;
+                if (!k)
+                    return;
+                const state = ctx.getAudioCat();
+                if (!state || !state[k])
+                    return;
+                state[k].vol = (+s.value) / 100;
+                state[k].on = true;
+                ctx.setCatGain(k);
+                const bb = el.querySelector('button[data-acat="' + k + '"]');
+                if (bb) {
+                    bb.classList.add('is-on');
+                    bb.setAttribute('aria-pressed', 'true');
+                }
+                refreshMarks();
+            });
+        });
+    }
+    function renderCategoryList(sel, keys) {
+        const el = ctx.$(sel);
+        const state = ctx.getAudioCat();
+        if (!el || !state)
+            return;
+        el.innerHTML = catsListHTML(keys, ctx.audioCats, state);
+        wireCatControls(el);
+    }
+    function renderNavSound() {
+        renderCategoryList('#navsound-list', NAV_CATS);
+        const m = ctx.$('#navsound-master');
+        const state = ctx.getAudioCat();
+        if (m && state)
+            m.value = String(navMasterVolume(state, NAV_CATS));
+    }
+    function reflectTts() {
+        const b = ctx.$('#opt-tts');
+        const state = ctx.getAudioCat();
+        const on = !!(state && state.tts && state.tts.on);
+        if (b) {
+            ctx.toggleBtn(b, on);
+            b.textContent = toggleLabel(on);
+        }
+        const e = ctx.$('#tts-engine');
+        if (e)
+            e.value = ctx.tts.getEngineSel();
+    }
+    /**
+     * O alternador do ÍNDICE "6 de 10" (ADR-0044, item 3).
+     *
+     * Ele mora ao lado da narração por voz e não num painel de visual, porque é a NARRAÇÃO que ele muda: quem
+     * desliga o índice está encurtando o que ouve a cada passo, e é aqui que essa pessoa vem quando o que ouve
+     * incomoda.
+     */
+    function reflectMenuIndex() {
+        const b = ctx.$('#opt-menuindex');
+        if (b) {
+            ctx.toggleBtn(b, state.menuIndexOn);
+            b.textContent = toggleLabel(state.menuIndexOn);
+        }
+    }
+    function populateTtsEngines() {
+        const sel = ctx.$('#tts-engine');
+        if (!sel || sel.dataset.filled)
+            return;
+        sel.dataset.filled = '1';
+        TTS_ENGINE_OPTIONS.forEach(([v, l]) => {
+            const o = document.createElement('option');
+            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;
+        let voices = [];
+        try {
+            voices = (window.speechSynthesis && window.speechSynthesis.getVoices()) || [];
+        }
+        catch (e) { /* noop */ }
+        const list = pickVoicesFor(voices, bcp47());
+        sel.innerHTML = '';
+        if (!list.length) {
+            const o = document.createElement('option');
+            o.textContent = t('audio.noSystemVoices');
+            sel.appendChild(o);
+            ctx.tts.setVoiceObj(null);
+            return;
+        }
+        list.forEach((v) => {
+            const o = document.createElement('option');
+            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);
+    }
+    function hasEnumerateDevices() {
+        return !!(navigator.mediaDevices && navigator.mediaDevices.enumerateDevices);
+    }
+    function hasAudioContextCtor() {
+        const w = window;
+        return typeof (w.AudioContext || w.webkitAudioContext) !== 'undefined';
+    }
+    function renderSinks(devices) {
+        const el = ctx.$('#audio-sinks');
+        if (!el)
+            return;
+        el.innerHTML = '';
+        if (!devices.length) {
+            const supported = sinksSupported(hasEnumerateDevices(), hasAudioContextCtor());
+            el.innerHTML = '<p class="opt-hint">' +
+                t(supported ? 'audio.sinksHint' : 'audio.sinksUnsupported') +
+                '</p>';
+            return;
+        }
+        const players = ctx.getPlayers();
+        const n = Math.max(1, ctx.getNumPlayers());
+        for (let i = 0; i < n; i++) {
+            const p = players[i];
+            const row = document.createElement('div');
+            row.className = 'ctrl-row';
+            const lbl = document.createElement('label');
+            lbl.textContent = t('audio.playerN', { n: i + 1 });
+            lbl.setAttribute('for', 'sink-p' + i);
+            const sel = document.createElement('select');
+            sel.className = 'vol';
+            sel.id = 'sink-p' + i;
+            const o0 = document.createElement('option');
+            o0.value = '';
+            o0.textContent = t('audio.sinkShared');
+            sel.appendChild(o0);
+            devices.forEach((d, k) => {
+                const o = document.createElement('option');
+                o.value = d.deviceId;
+                o.textContent = sinkOptionLabel(d, k);
+                sel.appendChild(o);
+            });
+            sel.value = sinkSelectValue(p);
+            sel.addEventListener('change', () => {
+                if (!p)
+                    return;
+                p.audioSink = sel.value || null;
+                ctx.store.set('incl_sink_p' + i, p.audioSink || '');
+                if (p._ac) {
+                    try {
+                        p._ac.close();
+                    }
+                    catch (e) { /* noop */ }
+                    p._ac = null;
+                    p._acOut = null;
+                }
+                ctx.srSay(t(p.audioSink ? 'sr.audio.sinkChanged' : 'sr.audio.sinkDefault', { n: i + 1 }));
+            });
+            row.appendChild(lbl);
+            row.appendChild(sel);
+            el.appendChild(row);
+        }
+    }
+    async function enumerateSinks() {
+        try {
+            if (navigator.mediaDevices && navigator.mediaDevices.enumerateDevices) {
+                const devs = await navigator.mediaDevices.enumerateDevices();
+                audioDevices = devs.filter((d) => d.kind === 'audiooutput');
+            }
+        }
+        catch (e) { /* sem pedir permissão: só lista as saídas já conhecidas */ }
+        renderSinks(audioDevices);
+    }
+    async function detectAudioDevices() {
+        try {
+            await navigator.mediaDevices.getUserMedia({ audio: true }).then((s) => s.getTracks().forEach((t) => t.stop())).catch(() => { });
+            const devs = await navigator.mediaDevices.enumerateDevices();
+            audioDevices = devs.filter((d) => d.kind === 'audiooutput');
+        }
+        catch (e) {
+            audioDevices = [];
+        }
+        renderSinks(audioDevices);
+    }
+    function reflectModoCego() {
+        const b = ctx.$('#opt-modocego');
+        if (b) {
+            ctx.toggleBtn(b, ctx.getModoCego());
+            b.textContent = toggleLabel(ctx.getModoCego());
+        }
+    }
+    function renderAudio() {
+        reflectMaster();
+        renderCategoryList('#audio-list', GEN_CATS);
+        renderNavSound();
+        reflectModoCego();
+        reflectTts();
+        populateTtsEngines();
+        populateTtsVoices();
+        const cd = ctx.$('#cane-div');
+        if (cd)
+            cd.value = String(ctx.getCaneBlockDiv());
+        void enumerateSinks(); // sem await no original: dispara e segue (lista assíncrona atualiza sozinha)
+        refreshMarks();
+    }
+    /**
+     * A marca de "saiu do padrão" (ADR-0029).
+     *
+     * Chamada de dentro dos HANDLERS de mudança, e não só do `renderAudio()`. Pendurei-a primeiro no render, e
+     * no jogo a marca não aparecia: mexer numa categoria atualiza aquela linha sozinha, sem redesenhar o painel.
+     * O ADR-0029 já avisava disso — "pode envelhecer na tela se um painel esquecer de atualizar depois de uma
+     * mudança" — e eu escrevi o aviso e caí nele na mesma tarde. A regra que sobra: a marca anda com quem
+     * ESCREVE o valor, nunca com quem desenha.
+     *
+     * O recorte é o MESMO do reset deste menu, e isso não é economia —
+     * é a regra: só pode ser marcado o que tem padrão em DEFAULTS/`defaultAudioCat`. O motor de voz e a saída
+     * de áudio por jogador não têm, porque são escolha de DISPOSITIVO e não preferência restaurável; marcá-los
+     * exigiria inventar uma segunda opinião sobre o que é "padrão" para um fone.
+     */
+    function refreshMarks() {
+        const state = ctx.getAudioCat();
+        const mudou = [];
+        const marcar = (sel, changed) => {
+            mudou.push(changed);
+            markChanged(ctx.$(sel)?.closest('.ctrl-row') ?? null, changed);
+        };
+        marcar('#opt-modocego', ctx.getModoCego() !== DEFAULTS.modoCego);
+        marcar('#cane-div', ctx.getCaneBlockDiv() !== DEFAULTS.caneBlockDiv);
+        for (const c of ctx.audioCats) {
+            const d = defaultAudioCat(c.k);
+            const a = state?.[c.k];
+            marcar(`[data-acat="${c.k}"]`, !!a && (a.on !== d.on || a.vol !== d.vol));
+        }
+        markMenuChanged(ctx.$('[data-act="audio"]'), mudou);
+    }
+    // ----- widgets estáticos (existem sempre no #audio; fiados UMA vez, nunca recriados por renderAudio) -----
+    const audioMasterBtn = ctx.$('#audio-master');
+    if (audioMasterBtn)
+        audioMasterBtn.addEventListener('click', () => {
+            const next = !ctx.getSoundOn();
+            ctx.setSoundOn(next);
+            reflectMaster();
+            ctx.srSay(t(next ? 'sr.audio.soundOn' : 'sr.audio.soundOff'));
+        });
+    const audioMasterVol = ctx.$('#audio-master-vol');
+    if (audioMasterVol)
+        audioMasterVol.addEventListener('input', () => {
+            const v = (+audioMasterVol.value) / 100;
+            ctx.setVolume(v);
+            if (v > 0 && !ctx.getSoundOn()) {
+                ctx.setSoundOn(true);
+                reflectMaster();
+            }
+        });
+    const navMasterEl = ctx.$('#navsound-master');
+    if (navMasterEl)
+        navMasterEl.addEventListener('input', () => {
+            const v = (+navMasterEl.value) / 100;
+            const state = ctx.getAudioCat();
+            if (state)
+                NAV_CATS.forEach((k) => { state[k].vol = v; state[k].on = true; ctx.setCatGain(k); });
+            renderNavSound();
+        });
+    const mcBtn = ctx.$('#opt-modocego');
+    if (mcBtn)
+        mcBtn.addEventListener('click', () => { ctx.setModoCego(!ctx.getModoCego()); reflectModoCego(); });
+    const caneDivSel = ctx.$('#cane-div');
+    if (caneDivSel) {
+        caneDivSel.value = String(ctx.getCaneBlockDiv());
+        caneDivSel.addEventListener('change', () => {
+            const div = parseCaneDiv(caneDivSel.value);
+            ctx.setCaneBlockDiv(div);
+            ctx.srSay(caneDivMessage(div));
+        });
+    }
+    const ttsBtn = ctx.$('#opt-tts');
+    if (ttsBtn)
+        ttsBtn.addEventListener('click', () => {
+            const state = ctx.getAudioCat();
+            if (!state)
+                return;
+            state.tts.on = !state.tts.on;
+            ctx.setCatGain('tts');
+            reflectTts();
+            ctx.srSay(t(state.tts.on ? 'sr.audio.ttsOn' : 'sr.audio.ttsOff'));
+            if (state.tts.on)
+                ctx.tts.narrate(t('sr.audio.ttsOnSpoken'));
+        });
+    const idxBtn = ctx.$('#opt-menuindex');
+    if (idxBtn)
+        idxBtn.addEventListener('click', () => {
+            state.setMenuIndexOnValue(!state.menuIndexOn);
+            reflectMenuIndex();
+            // O anúncio da troca NÃO leva índice: ele não é item de lista nenhuma, e um "1 de 1" aqui seria ruído
+            // justamente no momento em que a criança está julgando se o ruído incomoda.
+            ctx.srSay(t(state.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', () => {
+            try {
+                const vs = window.speechSynthesis.getVoices();
+                ctx.tts.setVoiceObj(vs.find((v) => v.name === ttsVoiceSel.value) || null);
+                ctx.store.set('incl_tts_voice', ttsVoiceSel.value);
+            }
+            catch (e) { /* noop */ }
+            ctx.tts.narrate(t('sr.audio.voicePicked'));
+        });
+    const ttsTestBtn = ctx.$('#opt-tts-test');
+    if (ttsTestBtn)
+        ttsTestBtn.addEventListener('click', () => {
+            const txt = t('audio.voiceSample');
+            const engine = ctx.tts.getEngine();
+            if (ctx.tts.getEngineSel() !== 'webspeech' && engine && engine.speak) {
+                try {
+                    engine.speak(txt);
+                }
+                catch (e) { /* noop */ } // motor neural já carregado
+            }
+            else {
+                try {
+                    const ss = window.speechSynthesis;
+                    if (ss) {
+                        ss.cancel();
+                        const u = new SpeechSynthesisUtterance(txt);
+                        u.lang = 'pt-BR';
+                        const vo = ctx.tts.getVoiceObj();
+                        if (vo)
+                            u.voice = vo;
+                        u.rate = 1;
+                        u.volume = 1;
+                        ss.speak(u);
+                    }
+                }
+                catch (e) { /* noop */ } // fallback audível (volume 1) + dispara download do neural
+                if (ctx.tts.getEngineSel() !== 'webspeech')
+                    ctx.tts.loadTTS();
+            }
+            ctx.srSay(t('sr.audio.testingVoice'));
+        });
+    // ---- restaurar os padrões DESTE menu (ADR-0028) ----
+    //
+    // A regra dura é o escopo: este botão restaura o que o menu AUDITIVO contém e nada mais. Um reset que
+    // alcançasse fora de si seria pior que a armadilha que ele existe para desfazer — a criança que desfaz um
+    // ajuste de som e perde de quebra a configuração motora fica sem conseguir jogar, e sem entender por quê.
+    //
+    // O que é deste menu: o modo cego, o espaçamento da bengala e as nove categorias do mixer. O motor de voz
+    // e a saída de áudio por jogador NÃO entram — são escolha de dispositivo, não preferência restaurável, e
+    // zerá-las tiraria da criança o fone que é dela numa sala compartilhada.
+    const resetBtn = ctx.$('#audio-reset');
+    if (resetBtn)
+        resetBtn.addEventListener('click', () => {
+            ctx.setModoCego(DEFAULTS.modoCego);
+            ctx.setCaneBlockDiv(DEFAULTS.caneBlockDiv);
+            const state = ctx.getAudioCat();
+            if (state)
+                for (const c of ctx.audioCats) {
+                    const d = defaultAudioCat(c.k);
+                    if (!state[c.k])
+                        continue;
+                    state[c.k].on = d.on;
+                    state[c.k].vol = d.vol;
+                    ctx.setCatGain(c.k);
+                }
+            renderAudio();
+            reflectModoCego();
+            reflectTts();
+            reflectMenuIndex();
+            ctx.srSay(t('sr.audio.reset'));
+        });
+    try {
+        if (window.speechSynthesis)
+            window.speechSynthesis.onvoiceschanged = populateTtsVoices;
+    }
+    catch (e) { /* noop */ }
+    const ttsVolEl = ctx.$('#tts-vol');
+    if (ttsVolEl)
+        ttsVolEl.addEventListener('input', () => {
+            const state = ctx.getAudioCat();
+            if (!state)
+                return;
+            state.tts.vol = (+ttsVolEl.value) / 100;
+            state.tts.on = true;
+            ctx.setCatGain('tts');
+            reflectTts();
+        });
+    const audioDetectBtn = ctx.$('#audio-detect');
+    if (audioDetectBtn)
+        audioDetectBtn.addEventListener('click', () => { void detectAudioDevices(); });
+    reflectMaster(); // estado inicial do botão/slider mestre, antes de qualquer abertura do painel
+    return { renderAudio, reflectModoCego, reflectTts };
+}

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

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { LetterCase } from '../core/state.js';
+import { type CaaSet } from './caa-sets.js';
+/**
+ * A linha das LETRAS é um INTERRUPTOR, não duas opções (decisão do Dev). Ligado = só maiúsculas; desligado =
+ * maiúsculas e minúsculas. Uma pergunta binária apresentada como duas linhas obriga a criança a comparar as
+ * duas para descobrir que são a mesma pergunta.
+ */
+export declare function caixaAltaLigada(caso: LetterCase): boolean;
+/** O interruptor das letras. Sempre disponível: é o piso offline, e nunca dependeu de arquivo nenhum. */
+export declare function letrasRowHtml(ligado: boolean): string;
+/**
+ * Uma linha do menu: RÓTULO CURTO e nada mais à vista.
+ *
+ * Tudo o que explica — nota, licença, situação — entra num único `.opt-hint`, que é o que a casca
+ * (`fillExplain`) reconhece e MOVE para o rodapé. A primeira versão pendurava três blocos de prosa dentro da
+ * linha, e o Dev viu o resultado: o menu virou um manual, mais parecido com um arquivo de configuração do que
+ * com um menu de videogame. A explicação já tinha um lugar; eu é que não a pus lá.
+ *
+ * O `disabled` fica: a situação some do TEXTO, não do controle. E o `aria-label` guarda o motivo, para quem
+ * navega por teclado ouvir por que a linha não responde sem precisar caçar o rodapé.
+ */
+export declare function caaRowHtml(s: CaaSet, selecionada: boolean): string;
+/** O corpo do menu, em três seções — a seção diz de quem é a vez de agir. */
+export declare function caaListHtml(caso: LetterCase): string;
+export interface SettingsCaaCtx {
+    $: <T extends Element = Element>(sel: string) => T | null;
+    srSay: (msg: string) => void;
+    /** Leitura viva de core/state `letterCase` (o binding é reatribuído pelo setter). */
+    getLetterCase: () => LetterCase;
+    /** `setLetterCaseValue` de core/state MAIS a reflexão que o jogo precisa (re-render do quiz, rótulos). */
+    setLetterCase: (c: LetterCase) => void;
+    frontOverlay: (el: HTMLElement | null) => void;
+    /** Move a prosa das linhas para o rodapé (ui/settings-panel `fillExplain`). Chamado a CADA render, e não só
+     *  ao abrir: `render()` reconstrói as linhas, e sem esta chamada a explicação volta para dentro delas — foi
+     *  exatamente o que aconteceu, e o menu virou manual de novo ao primeiro clique. */
+    fillExplain: (card: HTMLElement | null) => void;
+    restoreFocus?: (id: string) => boolean;
+}
+export interface SettingsCaaApi {
+    render: () => void;
+    open: () => void;
+    close: () => void;
+}
+export declare function initSettingsCaa(ctx: SettingsCaaCtx): SettingsCaaApi;