@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/platform/tts.js

@@ -1,171 +1,491 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// platform/tts — narração por voz. Motor NEURAL pt-BR carregado LAZY pela PORTA que o jogo fornece (ADR-0094; modelo
-// em cache OPFS → a 2ª sessão fala offline), com FALLBACK imediato p/ a voz nativa do navegador (Web Speech) — que é
-// também o que se ouve quando não há porta nenhuma, e é por isso que a ausência dela não cala nada. narrate() é o
-// ponto de entrada, gated pelo toggle 'Narração (TTS)' do mixer (audioCat.tts.on) — independe das legendas. As funções de
-// PAINEL (populateTTSEngines/Voices/reflectTTS) ficam no game.js (→ ui/settings-audio, #38→#54) e usam get/setEngineSel +
-// get/setVoiceObj daqui. Injeção por closure. Ver docs/plano-tts-fase-f5.md + docs/5-Refactoring/plano-modularizacao-mapa.md.
-import * as store from './storage.js';
-import { t, bcp47 } from '../core/i18n.js';
-import { criarFalaInterrompivel } from './interruptible-speech.js';
-// ⚠️ MIGRAÇÃO PENDENTE (ADR-0022): a implementação neural de hoje é o @mintplex-labs/piper-tts-web e será SUBSTITUÍDA
-// por sherpa-onnx-wasm (loader universal, modelos VITS/Piper + Kokoro-multi-lang carregados de qq URL R2 em runtime via
-// FS.writeFile; lazy-fetch; eSpeak/Web Speech de fallback).
-// 🔴 O MOTIVO ESCRITO AQUI ERA «@mintplex-labs foi descontinuado e só carrega 2 vozes pt-BR», E AS DUAS METADES
-// FORAM MEDIDAS FALSAS EM 2026-09-09 — não pela leitura de um registo, que é como elas se propagaram por seis
-// sítios, mas pelo registo npm e pelo pacote instalado:
-//   · DESCONTINUADO: nenhuma versão tem campo `deprecated`, e a 1.0.5 foi publicada em 2026-08-11 — depois de
-//     o ADR-0022 (2026-07-06) a dar por morta. A frase é de Julho e está atribuída ao Dev; o registo não a nega
-//     no passado, nega-a HOJE.
-//   · DUAS VOZES pt-BR: o `VoiceId` da 1.0.4 instalada traz 118 vozes, e entre elas as QUATRO exactas do
-//     ADR-0110 — `pt_BR-faber-medium`, `en_US-ryan-medium`, `en_US-amy-medium`, `es_MX-claude-high`.
-// ⚠️ O QUE CONTINUA VERDADEIRO, e é mais afiado do que o motivo velho: o bundle prende `HF_BASE` a
-// `huggingface.co/diffusionstudio/piper-voices` COM UMA GUARDA (`if (!url.match("https://huggingface.co")) return`),
-// logo nenhum espelho de escola é alcançável por ele; e ele busca o PRÓPRIO runtime de cdnjs/jsDelivr por
-// omissão, que é o que o ADR-0114 retira. A montante, o Piper mudou para `OHF-Voice/piper1-gpl` e a Open Home
-// Foundation procura mantenedores — o risco existe, mas está noutro sítio.
-// 📌 A ESCOLHA CONTINUA A SER A #129, e este comentário não a toma: descreve o que foi medido para que o
-// próximo leitor não herde o motivo velho como se fosse medição.
-// ⚠️ E DESDE O ADR-0094 ESTE MÓDULO NÃO NOMEIA FORNECEDOR NENHUM — quem o nomeia é o JOGO, por `ctx.carregarVozNeural`.
-// O nome estava aqui num `import()` e o pacote em `devDependencies`, o que publicou uma engine que não compilava
-// (ADR-0093); pô-lo em `dependencies` consertava o build e obrigava todo consumidor a 135,4 MB de `onnxruntime-web`,
-// que o fornecedor traz como peer não-opcional. A porta é o que faz a troca do ADR-0022 não ser um segundo abalo.
-/**
- * Voz NEURAL por idioma, indexada pela etiqueta BCP-47 de core/i18n. Só o pt-BR tem uma hoje, e essa ausência
- * é agora CONSULTÁVEL em vez de presumida: `loadTTS` pergunta à tabela se existe voz para o idioma corrente,
- * em vez de carregar a portuguesa aconteça o que acontecer.
- *
- * Era `TTS_SOURCES['pt-BR']` escrito à mão no ponto de uso, o que fazia o jogo em inglês baixar 25,6 MB de
- * voz portuguesa para ler texto em inglês com fonética errada — pior que não ter voz neural nenhuma, porque
- * gasta a banda da escola para entregar algo ininteligível.
- */
-const TTS_SOURCES = {
-    'pt-BR': { engine: 'piper', voice: 'pt_BR-faber-medium' },
-};
+// platform/tts — spoken narration. The browser's voice speaks first (Web Speech, ADR-0200); the neural fallback is Kokoro, which
+// THE ENGINE ITSELF loads from the delivery (ADR-0216 §1) the first time a child picks it — the game only says it wants one; the
+// loader, the browser's speech, the clock and the `<audio>` maker are the root's, received here (ADR-0232 D4). narrate()
+// is the entry point, gated by the mixer's narration toggle (audioCat.tts.on) — independent of captions. The PANEL's side (the
+// engine and voice lists) lives in `ui/voice-settings` and reads and writes the choice through this module. Injection by closure.
+//
+// A SPOKEN TEXT CARRIES ITS LANGUAGE (ADR-0243): `narrate` takes a text, in the interface's language, or parts spoken in order —
+// the frame in the interface's voice, the content in a voice of its own language (`voice-plan.voiceOfLanguage`).
+import { KEYS } from './storage-keys.js';
+import { createInterruptibleSpeech } from './interruptible-speech.js';
+import { voicesForLocale, voiceOfLanguage, speaksLanguageOf, languageName } from './voice-plan.js';
+import { spokenWords, speechSeconds, speechPlaybackRate } from '../core/speech-rate.js';
+import { KOKORO_VOICES, tokenize, sentenceStyle, eFala, wavDe, } from './kokoro.js';
+// 📌 The only neural engine is Kokoro (ADR-0207): the engine's earlier neural engine left when the licence chain of its voices came
+// to light. 📌 And ADR-0094's fear — «a provider named here lands its runtime in every consumer's `node_modules`» — is answered by the
+// delivery and not by a port: the runtime is catalogued, fetched by the build and read from `heavy/`, never imported from npm.
+/** An engine the child may have stored before it left the engine (ADR-0207): read as no explicit choice, so the voice in use speaks. */
+const ENGINES_THAT_LEFT = ['piper'];
 export function createTts(ctx) {
-    let ttsEngine = null, ttsLoading = false, ttsFailed = false, _ttsPct = 0, _narrateCount = 0;
-    let _ttsVoiceObj = null; // voz do Web Speech selecionada
-    let ttsEngineSel = store.get(store.KEYS.ttsEngine, null) || 'webspeech'; // webspeech | piper | kokoro | kitten | espeak
+    const { t, bcp47 } = ctx.translator;
+    let ttsEngine = null, ttsLoading = false, ttsFailed = false, _narrateCount = 0;
+    let _ttsVoiceObj = null; // the selected Web Speech voice
+    // An engine set explicitly (stored, or by the panel) wins; otherwise the engine of the voice in use, which is the browser's when it
+    // offers one for the language (ADR-0200) — measured on the device at every call, since the browser lists its voices late.
+    const stored = ctx.store.get(KEYS.ttsEngine, null) || null; // webspeech | kokoro | kitten | espeak
+    let ttsEngineSelExplicito = stored && !ENGINES_THAT_LEFT.includes(stored) ? stored : null;
+    const engineSel = () => {
+        if (ttsEngineSelExplicito)
+            return ttsEngineSelExplicito;
+        const e = voiceInUse()?.engine;
+        // a fallback this game did not ask for is not the default: undeclared, the browser's voice (no «not bundled» alert)
+        return e === 'kokoro' && ctx.neuralVoice ? e : 'webspeech';
+    };
+    let kokoroBackend = null;
+    let loadedVoice = null; // the voice the loaded engine speaks; another choice reloads it
+    /** The loaded Kokoro model's speaker, any of its voices; null until the model loads. */
+    let neural = null;
+    /** A narration's number: a newer one ends the parts an older one has still to speak (ADR-0243 §1). */
+    let narrationTurn = 0;
+    // Each voice's words per minute, averaged over the utterances long enough to measure (`core/speech-rate`): what a short
+    // utterance («Voltar») is played against. Neural voices by id; browser voices by name.
+    const voiceAverage = new Map();
+    const media = (voiceName, ppm) => {
+        if (!ppm)
+            return;
+        const before = voiceAverage.get(voiceName);
+        voiceAverage.set(voiceName, before ? before * 0.7 + ppm * 0.3 : ppm);
+    };
+    /**
+     * WEB SPEECH FIRST (ADR-0200; issue #190): the browser's voices for the language lead the list, so where the device already speaks
+     * no neural voice is loaded; then Kokoro's where the game declared it speaks neurally (ADR-0216 §3) — the fallback.
+     */
+    /** Every voice the browser lists, in every language: what a part in another language is matched against (ADR-0243 §2). */
+    const deviceVoices = () => {
+        let list = [];
+        try {
+            list = ctx.speech.synth()?.getVoices() ?? [];
+        }
+        catch { /* no speech synthesis here */ }
+        return list.map((v) => ({ locale: v.lang.replace('_', '-'), engine: 'webspeech', voice: 'webspeech:' + v.name }));
+    };
+    const availableVoices = () => [...voicesForLocale(bcp47(), deviceVoices()), ...(ctx.neuralVoice ? voicesForLocale(bcp47(), KOKORO_VOICES) : [])];
+    /** The browser voice an entry names, or null. */
+    const browserVoice = (id) => {
+        if (!id?.startsWith('webspeech:'))
+            return null;
+        try {
+            return ctx.speech.synth()?.getVoices().find((v) => 'webspeech:' + v.name === id) ?? null;
+        }
+        catch {
+            return null;
+        }
+    };
+    /**
+     * The interface's voice (ADR-0243 §2 over the language of now): the stored choice, else `voice-plan`'s `VOICE_ORDER` — the exact
+     * tag before the region, a browser voice before a neural one.
+     */
+    function voiceInUse() {
+        return voiceOfLanguage(bcp47(), availableVoices(), [ctx.store.get(KEYS.ttsVoz, null)]);
+    }
+    function chooseVoice(id) {
+        if (!availableVoices().some((v) => v.voice === id))
+            return false;
+        ctx.store.set(KEYS.ttsVoz, id);
+        ttsEngineSelExplicito = availableVoices().find((v) => v.voice === id).engine;
+        _ttsVoiceObj = browserVoice(id);
+        return true;
+    }
+    /**
+     * NARRATION FOLLOWS THE LANGUAGE OF NOW (ADR-0243 §5): the page's voice object when it speaks the language of now; one picked in
+     * another language is dropped at the first utterance after the switch, and the voice in use for the new language speaks instead.
+     */
+    function voiceObjectOfNow() {
+        if (_ttsVoiceObj && !speaksLanguageOf(_ttsVoiceObj.lang.replace('_', '-'), bcp47()))
+            _ttsVoiceObj = null;
+        return _ttsVoiceObj;
+    }
+    /**
+     * One browser utterance: `lang` is the tag the text is in and `voice` a voice of it, or null for the browser to choose by the tag.
+     * ADR-0183 §1: the browser's `rate` is a multiplier. The voice's words a minute at rate 1 is measured on its own utterances (start
+     * to end, so the silent ends count — an approximation the neural path does not need); until one is measured, 1.
+     */
+    function browserUtterance(text, lang, voice) {
+        const u = ctx.speech.utterance(text);
+        u.lang = lang;
+        if (voice)
+            u.voice = voice;
+        u.volume = Math.min(1, ctx.getVolume() * 1.4);
+        const voiceIdOf = 'webspeech:' + (voice?.name ?? lang);
+        const words = spokenWords(text);
+        const voiceBase = voiceAverage.get(voiceIdOf) ?? null;
+        u.rate = ctx.getSpeechPpm && voiceBase ? speechPlaybackRate(0, 0, ctx.getSpeechPpm(), voiceBase).rate : 1;
+        let startAt = 0;
+        u.onstart = () => { startAt = ctx.now(); };
+        u.onend = () => {
+            const seconds = startAt ? (ctx.now() - startAt) / 1000 : 0;
+            const measured = speechPlaybackRate(words, seconds, 150, null).voiceWpm;
+            if (measured)
+                media(voiceIdOf, measured / u.rate);
+        };
+        return u;
+    }
+    /**
+     * An utterance in the interface's language. `u.lang` follows the game's language: fixed at pt-BR, a game in English or Spanish
+     * would ask the browser for a PORTUGUESE voice for a text that is not Portuguese — and the result is not an accent, it is
+     * unintelligible: the wrong phonetics applied to the wrong letters.
+     */
+    const interfaceUtterance = (text) => browserUtterance(text, bcp47(), voiceObjectOfNow() ?? browserVoice(voiceInUse()?.voice));
     function speakWebSpeech(text) {
         try {
-            const ss = window.speechSynthesis;
+            const ss = ctx.speech.synth();
             if (!ss)
                 return false;
             ss.cancel();
-            // `u.lang` era 'pt-BR' fixo. Com o jogo em inglês ou espanhol isso pedia ao navegador uma voz
-            // PORTUGUESA para um texto que não é português — e o resultado não é sotaque, é ininteligível: a
-            // fonética errada aplicada às letras erradas. Segue o idioma do jogo.
-            const u = new SpeechSynthesisUtterance(text);
-            u.lang = bcp47();
-            if (_ttsVoiceObj)
-                u.voice = _ttsVoiceObj;
-            u.rate = 1;
-            u.volume = Math.min(1, ctx.getVolume() * 1.4);
-            ss.speak(u);
+            ss.speak(interfaceUtterance(text));
             return true;
         }
         catch (e) {
             return false;
         }
     }
+    /**
+     * A neural voice's utterances, whatever made the WAV (ADR-0183 §1): every utterance is measured — its words over its speech time,
+     * silent ends trimmed — and played at the child's rate over the voice's, through a media element that keeps the pitch. Each
+     * request names its voice, so one loaded model reads the parts of every language it has a voice for (ADR-0243 §2).
+     */
+    function speakByWav(produce) {
+        return createInterruptibleSpeech({
+            synthesize: async (request) => {
+                const { text } = request, voiceId = request.voice.voice;
+                const bytes = await produce(request);
+                const ac = ctx.ensureAC();
+                if (!ac)
+                    throw new Error('AudioContext unavailable'); // the `catch` there handles it: this item is silent, the engine lives
+                let speedRatio = 1;
+                if (ctx.getSpeechPpm) {
+                    const buf = await ac.decodeAudioData(bytes.slice(0));
+                    const measure = speechPlaybackRate(spokenWords(text), speechSeconds(buf.getChannelData(0), buf.sampleRate), ctx.getSpeechPpm(), voiceAverage.get(voiceId) ?? null);
+                    media(voiceId, measure.voiceWpm);
+                    speedRatio = measure.rate;
+                }
+                return { url: URL.createObjectURL(new Blob([bytes], { type: 'audio/wav' })), rate: speedRatio };
+            },
+            play: (sound, onFinish) => {
+                const ac = ctx.ensureAC();
+                if (!ac) {
+                    URL.revokeObjectURL(sound.url);
+                    return null;
+                }
+                const el = ctx.createAudio();
+                el.preservesPitch = true;
+                el.src = sound.url;
+                el.playbackRate = sound.rate;
+                try {
+                    ac.createMediaElementSource(el).connect(ctx.catNode('tts') || ctx.audioOut() || ac.destination);
+                }
+                catch { /* already routed */ }
+                el.onended = () => { URL.revokeObjectURL(sound.url); onFinish(); };
+                void el.play().catch(() => { URL.revokeObjectURL(sound.url); onFinish(); });
+                return el;
+            },
+            stop: (el) => { el.pause(); URL.revokeObjectURL(el.src); },
+        });
+    }
+    /**
+     * KOKORO (ADR-0186, ADR-0216; issues #181, #200): the voice's text becomes espeak-ng phonemes in its language, then the model's
+     * ids and a waveform. WebGPU only where a short test synthesis is speech — measured, WebGPU can run and return noise — and WASM
+     * with threads otherwise (ADR-0192).
+     */
+    function loadKokoroEngine(forVoice) {
+        const load = ctx.loadKokoro;
+        const kv = KOKORO_VOICES.find((v) => v.voice === forVoice.voice);
+        if (!kv) {
+            ttsFailed = true;
+            ctx.srAlert(t('sr.tts.neuralNotBundled'));
+            return;
+        }
+        ttsLoading = true;
+        loadedVoice = forVoice.voice;
+        const t0 = ctx.now();
+        ctx.srSay(t('sr.tts.downloading'));
+        load().then(async (mod) => {
+            const [symbolIds, table] = await Promise.all([mod.vocabulary(), mod.voice(kv.voice)]);
+            // Each voice's style table, fetched the first time an utterance asks for that voice; a failed fetch is tried again.
+            const tables = new Map([[kv.voice, Promise.resolve(table)]]);
+            const tableOf = (voice) => {
+                let styles = tables.get(voice.voice);
+                if (!styles) {
+                    styles = mod.voice(voice.voice);
+                    tables.set(voice.voice, styles);
+                    styles.catch(() => tables.delete(voice.voice));
+                }
+                return styles;
+            };
+            const synthesiseWith = async (kokoroSession, text, voice) => {
+                const ids = tokenize(await mod.phonemize(text, voice.espeak), symbolIds);
+                return kokoroSession.synthesize(ids, sentenceStyle(await tableOf(voice), ids.length - 2));
+            };
+            let kokoroSession = null;
+            try {
+                const gpu = await mod.session('webgpu');
+                if (eFala(await synthesiseWith(gpu, t('tts.kokoro.teste'), kv))) {
+                    kokoroSession = gpu;
+                    kokoroBackend = 'webgpu';
+                }
+            }
+            catch { /* no WebGPU here: WASM below */ }
+            if (!kokoroSession) {
+                kokoroSession = await mod.session('wasm');
+                kokoroBackend = 'wasm';
+            }
+            const used = kokoroSession;
+            const speaker = speakByWav(async (request) => wavDe(await synthesiseWith(used, request.text, request.voice)));
+            neural = speaker;
+            ttsEngine = { id: 'kokoro', speak: (text, finished) => { speaker.speak({ text, voice: kv }, finished); } };
+            ttsLoading = false;
+            try {
+                ctx.speech.synth()?.cancel();
+            }
+            catch (e) { /* noop */ }
+            narrate(t('sr.tts.ready', { s: ((ctx.now() - t0) / 1000).toFixed(0) }));
+        }).catch(() => { ttsLoading = false; ttsFailed = true; ctx.srAlert(t('sr.tts.loadFailed')); });
+    }
     function loadTTS() {
         if (ttsEngine || ttsLoading || ttsFailed)
             return;
-        if (ttsEngineSel !== 'piper') { // Kokoro/Kitten/eSpeak NG ainda não entraram
-            if (ttsEngineSel !== 'webspeech')
+        const sel = engineSel();
+        if (sel !== 'kokoro') { // Kitten and eSpeak NG are not built
+            if (sel !== 'webspeech')
                 ctx.srAlert(t('sr.tts.engineNoLanguage'));
             return;
         }
-        // ESTA MONTAGEM NÃO TRAZ MOTOR NEURAL (ADR-0094). Vem ANTES da pergunta do idioma de propósito: sem
-        // porta, não há voz neural em idioma nenhum, e dizer «não há voz para o teu idioma» faria a criança
-        // pensar que trocar de idioma resolveria. `ttsFailed` para não repetir a pergunta a cada fala.
-        const carregar = ctx.carregarVozNeural;
-        if (!carregar) {
+        // THIS GAME DID NOT ASK FOR A NEURAL VOICE (ADR-0216 §3). It comes BEFORE the language question on purpose: without
+        // the declaration there is no neural voice in any language — the delivery does not carry the model — and saying "there
+        // is no voice for your language" would make the child think switching language would fix it. `ttsFailed` so it is not
+        // repeated on every utterance.
+        if (!ctx.neuralVoice) {
             ttsFailed = true;
             ctx.srAlert(t('sr.tts.neuralNotBundled'));
             return;
         }
-        // O Piper só tem voz para os idiomas em TTS_SOURCES. Sem voz para o idioma corrente, NÃO se baixa a de
-        // outro idioma: avisa e segue na voz do navegador, que fala a língua certa.
-        const fonte = TTS_SOURCES[bcp47()];
-        if (!fonte) {
+        // The voice in use for the current language (ADR-0185); a browser voice in use with Kokoro set explicitly gives way to the
+        // language's first Kokoro voice. None: another language's voice is NOT fetched — it would read this text with the wrong phonetics.
+        const current = voiceInUse();
+        const forVoice = current?.engine === 'kokoro' ? current : voicesForLocale(bcp47(), KOKORO_VOICES)[0] ?? null;
+        if (!forVoice) {
             ctx.srAlert(t('sr.tts.noNeuralForLanguage'));
             return;
         }
-        ttsLoading = true;
-        const t0 = performance.now();
-        ctx.srSay(t('sr.tts.downloading'));
-        carregar().then(async (mod) => {
-            const session = await mod.TtsSession.create({ voiceId: fonte.voice,
-                progress: (p) => { if (!p || !p.total)
-                    return; const pct = Math.round(p.loaded * 100 / p.total); if (pct >= _ttsPct + 25 && pct < 100) {
-                    _ttsPct = pct;
-                    ctx.srSay(t('sr.tts.progress', { pct }));
-                } },
-                logger: () => { } });
-            // A FILA DE UM SAIU (ADR-0044, item 2). Ela era `if (busy) next = text; else speakNow(text)`, e o
-            // efeito, varrendo cinco itens de menu, era ouvir o PRIMEIRO inteiro e depois o ÚLTIMO — os três do
-            // meio sumiam, porque cada pedido sobrescrevia o `next`. Lento e lacunar, e quem não enxerga navega
-            // POR ESCUTA: a escuta ficava vários itens atrás do foco.
-            //
-            // A política agora mora em `platform/interruptible-speech`, pura e testada com falsos. Aqui só se
-            // diz COMO sintetizar, tocar e parar — o quando é lá, com a guarda de geração que impede uma síntese
-            // lenta de atropelar a mais nova.
-            const fala = criarFalaInterrompivel({
-                sintetizar: async (texto) => {
-                    const wav = await session.predict(texto);
-                    const ac = ctx.ensureAC();
-                    if (!ac)
-                        throw new Error('AudioContext unavailable'); // o `catch` de lá trata: silêncio deste item, motor vivo
-                    return ac.decodeAudioData(await wav.arrayBuffer());
-                },
-                tocar: (buf, aoTerminar) => {
-                    const ac = ctx.ensureAC();
-                    if (!ac)
-                        return null;
-                    const src = ac.createBufferSource();
-                    src.buffer = buf;
-                    src.connect(ctx.catNode('tts') || ctx.audioOut() || ac.destination);
-                    src.onended = aoTerminar;
-                    src.start();
-                    return src;
-                },
-                parar: (src) => { src.stop(); },
-            });
-            ttsEngine = { id: 'piper', speak: (text) => { fala.falar(text); } };
-            ttsLoading = false;
+        loadKokoroEngine(forVoice);
+    }
+    /** The loaded neural engine when the interface speaks neurally; else it starts loading, and the browser speaks meanwhile. */
+    function interfaceEngine() {
+        if (engineSel() === 'webspeech')
+            return null;
+        // another voice picked, or the language changed, since the engine loaded: load the voice in use
+        const inUse = voiceInUse();
+        if (ttsEngine && inUse?.engine !== 'webspeech' && loadedVoice !== inUse?.voice) {
+            ttsEngine = null;
+            ttsFailed = false;
+        }
+        if (!ttsEngine)
+            loadTTS(); // the neural engine is downloading or unavailable → falls back
+        return ttsEngine;
+    }
+    function ttsSpeak(text) {
+        const engine = interfaceEngine();
+        if (engine) {
             try {
-                window.speechSynthesis && window.speechSynthesis.cancel();
+                engine.speak(text);
             }
             catch (e) { /* noop */ }
-            narrate(t('sr.tts.ready', { s: ((performance.now() - t0) / 1000).toFixed(0) })); // já sai NA voz nova
-        }).catch(() => { ttsLoading = false; ttsFailed = true; ctx.srAlert(t('sr.tts.loadFailed')); });
+            return true;
+        }
+        neural?.silence(); // a neural part still speaking gives way: the latest narration is the one that counts
+        return speakWebSpeech(text); // immediate fallback: Web Speech, in the game's language
     }
-    function ttsSpeak(text) {
-        if (ttsEngineSel !== 'webspeech') {
-            if (ttsEngine && ttsEngine.id === ttsEngineSel && ttsEngine.speak) {
-                try {
-                    ttsEngine.speak(text);
-                }
-                catch (e) { /* noop */ }
-                return true;
+    /** A FRAME part (ADR-0243 §1): the interface's voice, as a text narrated alone; none while narration is locked (ADR-0185 §4). */
+    function frameSegment(text) {
+        if (availableVoices().length === 0)
+            return null;
+        const engine = interfaceEngine();
+        if (engine)
+            return { neural: (finished) => { engine.speak(text, finished); } };
+        return { browser: () => interfaceUtterance(text) };
+    }
+    /**
+     * A CONTENT part (ADR-0243 §2): a voice of its language in `voice-plan`'s `VOICE_ORDER` — the exact tag before the region, a
+     * browser voice before the neural ones this game asked for, which read only once the model is loaded; while it loads, the part starts the load and a browser voice of the language reads it if
+     * the device has one. `null`: the device has no voice for the language, and no voice of another language reads it instead.
+     */
+    function contentSegment(text, language) {
+        const chosen = chosenVoices();
+        const neuralVoices = ctx.neuralVoice && !ttsFailed ? KOKORO_VOICES : [];
+        const best = voiceOfLanguage(language, [...deviceVoices(), ...neuralVoices], chosen);
+        if (!best)
+            return noVoiceSegment(language);
+        const kokoro = KOKORO_VOICES.find((v) => v.voice === best.voice);
+        return kokoro ? neuralSegment(text, language, kokoro, chosen) : browserSegment(text, language, best);
+    }
+    /** The languages this root has already said it has no voice for, by primary language (ADR-0243 §3). */
+    const toldNoVoice = new Set();
+    /**
+     * NO VOICE FOR IT, NO WRONG VOICE (ADR-0243 §3): the part is not spoken — the text stays on the screen. Once per language, the
+     * interface's voice says so in its place, and `problems` gets one line naming the language and the fix.
+     */
+    function noVoiceSegment(language) {
+        const english = languageName(language, 'en');
+        const code = language.split('-')[0].toLowerCase();
+        if (toldNoVoice.has(code))
+            return null;
+        toldNoVoice.add(code);
+        ctx.report?.(`narration: the device lacks a voice for ${english} (${code}), so a part a game gave in ${english} is not read aloud `
+            + `and a child who listens does not hear it (the text stays on the screen) — install a voice for ${english} on the device, `
+            + `in its text-to-speech settings`);
+        return frameSegment(t('sr.tts.noVoiceForLanguage', { language: languageName(language, bcp47()) }));
+    }
+    /** The voices the child chose, in order of precedence: the page's voice object, then the stored choice (ADR-0243 §2). */
+    const chosenVoices = () => [_ttsVoiceObj ? 'webspeech:' + _ttsVoiceObj.name : null, ctx.store.get(KEYS.ttsVoz, null)];
+    const browserSegment = (text, language, voice) => ({ browser: () => browserUtterance(text, language, browserVoice(voice.voice)) });
+    /** A part a Kokoro voice reads; while the model loads, a browser voice of the language reads it if the device has one. */
+    function neuralSegment(text, language, voice, chosen) {
+        const speaker = neural;
+        if (speaker)
+            return { neural: (finished) => { speaker.speak({ text, voice }, finished); } };
+        if (!ttsLoading)
+            loadKokoroEngine(voice);
+        const meanwhile = voiceOfLanguage(language, deviceVoices(), chosen);
+        return meanwhile ? browserSegment(text, language, meanwhile) : null;
+    }
+    /**
+     * The utterances a narration waits on, held until their end is heard: an utterance nothing holds may be collected by the
+     * browser before it ends, and then its end is never heard — and a player's sonar would wait behind it forever (ADR-0234).
+     */
+    const heldUntilOver = new Set();
+    /** Resolves when an utterance is over, however it ends — set before it is queued. */
+    const utteranceOver = (u) => new Promise((over) => {
+        heldUntilOver.add(u);
+        const done = () => { heldUntilOver.delete(u); over(); };
+        const measure = u.onend;
+        u.onend = function (e) { measure?.call(this, e); done(); };
+        u.onerror = done;
+    });
+    /**
+     * Queues the browser parts from `from` on at once; `over` resolves when the last is over, when a part follows them or the
+     * caller waits for the end (`untilOver`). A device that refuses to speak has nothing to wait for: the rest goes on.
+     */
+    function queueBrowserParts(ss, segments, from, untilOver) {
+        const queued = [];
+        let i = from;
+        for (let s = segments[i]; s && 'browser' in s; s = segments[++i])
+            queued.push(s.browser());
+        const last = queued.at(-1);
+        const over = ss && last && (i < segments.length || untilOver) ? utteranceOver(last) : null;
+        try {
+            for (const u of queued)
+                ss?.speak(u);
+        }
+        catch (e) {
+            return { next: i, over: null };
+        }
+        return { next: i, over };
+    }
+    /**
+     * THE PARTS, IN ORDER (ADR-0243 §1). Browser utterances go into the browser's own queue at once, each with its tag and voice; a
+     * neural part waits for what is before it to end, and what follows waits for it. A newer narration ends the rest. `untilOver`:
+     * resolves only when the last part is over, for a narration waiting its turn behind this one.
+     */
+    async function speakInOrder(segments, turn, untilOver = false) {
+        const ss = ctx.speech.synth();
+        try {
+            ss?.cancel();
+        }
+        catch (e) { /* noop */ }
+        neural?.silence();
+        let i = 0;
+        while (i < segments.length && turn === narrationTurn) {
+            const first = segments[i];
+            if ('neural' in first) {
+                await new Promise((over) => { first.neural(over); });
+                i++;
+                continue;
             }
-            loadTTS(); // motor neural (baixando/indisponível) → cai no fallback
+            const queuedParts = queueBrowserParts(ss, segments, i, untilOver);
+            i = queuedParts.next;
+            if (queuedParts.over)
+                await queuedParts.over;
+        }
+    }
+    /** The players' narrations waiting behind the one being spoken (ADR-0234), at most one per player, in the order they asked. */
+    const waiting = [];
+    /** The `narrationTurn` of the player's narration being spoken, and whose it is; any narration since has taken the turn. */
+    let turnSpeaking = -1, seatSpeaking = -1;
+    /**
+     * A PLAYER'S NARRATION TAKES TURNS (ADR-0234, errata 2026-09-26): behind ANOTHER player's still being spoken it waits — replacing
+     * that player's own waiting one, in its place — and is spoken when the line reaches it. With the SAME player's being spoken, or
+     * none, it starts at once and cuts what is spoken now, as every narration does; the others waiting keep waiting behind it. A
+     * narration that names no player takes the turn, so the next player's finds none being spoken and nobody waiting.
+     */
+    function narrateInTurn(seat, segments) {
+        _narrateCount++;
+        const speakingNow = turnSpeaking === narrationTurn;
+        if (speakingNow && seat !== seatSpeaking) {
+            const own = waiting.find((w) => w.seat === seat);
+            if (own)
+                own.segments = segments;
+            else
+                waiting.push({ seat, segments });
+            return;
         }
-        return speakWebSpeech(text); // fallback imediato: Web Speech, no idioma do jogo
+        if (!speakingNow)
+            waiting.length = 0; // their turn was ended by a narration that named no player
+        void speakInTurn({ seat, segments }, ++narrationTurn);
     }
-    function narrate(text) {
+    async function speakInTurn(first, turn) {
+        turnSpeaking = turn;
+        for (let next = first; next; next = waiting.shift()) {
+            seatSpeaking = next.seat;
+            await speakInOrder(next.segments, turn, true);
+            if (turn !== narrationTurn)
+                return; // cut: the line is the newer narration's now
+        }
+        turnSpeaking = -1;
+        seatSpeaking = -1;
+    }
+    function narrate(text, how = {}) {
         const cat = ctx.getAudioCat();
-        if (!ctx.getSoundOn() || !cat || !cat.tts || !cat.tts.on || !text)
+        if (!ctx.getSoundOn() || !cat || !cat.tts || !cat.tts.on)
+            return;
+        if (typeof text !== 'string') {
+            narrateParts(text, how);
             return;
+        }
+        if (!text)
+            return;
+        if (availableVoices().length === 0)
+            return; // no voice speaks this language: narration is locked (ADR-0185 §4)
+        if (how.seat !== undefined) {
+            const frame = frameSegment(text);
+            if (frame)
+                narrateInTurn(how.seat, [frame]);
+            return;
+        }
+        narrationTurn++;
         _narrateCount++;
         ttsSpeak(text);
     }
+    function narrateParts(parts, how) {
+        const segments = parts.filter((p) => p.text)
+            .map((p) => (p.language ? contentSegment(p.text, p.language) : frameSegment(p.text)))
+            .filter((s) => s !== null);
+        if (!segments.length)
+            return;
+        if (how.seat !== undefined) {
+            narrateInTurn(how.seat, segments);
+            return;
+        }
+        _narrateCount++;
+        void speakInOrder(segments, ++narrationTurn);
+    }
     return {
         narrate, ttsSpeak, loadTTS, speakWebSpeech,
-        getEngineSel: () => ttsEngineSel, setEngineSel: (v) => { ttsEngineSel = v; },
+        getEngineSel: engineSel, setEngineSel: (v) => { ttsEngineSelExplicito = v; },
         getEngine: () => ttsEngine, getVoiceObj: () => _ttsVoiceObj, setVoiceObj: (v) => { _ttsVoiceObj = v; },
         get loading() { return ttsLoading; }, get failed() { return ttsFailed; }, get narrateCount() { return _narrateCount; },
-        get neuralDisponivel() { return !!ctx.carregarVozNeural; },
+        get neuralAvailable() { return !!ctx.neuralVoice; },
+        get kokoroDevice() { return kokoroBackend; },
+        voices: availableVoices, currentVoice: voiceInUse, setVoice: chooseVoice,
     };
 }