@the-inclusionist/engine 10.0.0 → 11.0.0

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

@@ -2,12 +2,36 @@
 import type { Store } from './storage.js';
 import type { Translator } from '../core/i18n.js';
 import { type NeuralVoice } from './voice-plan.js';
-import { type LoadKokoro, type KokoroModule, type KokoroSession } from './kokoro.js';
+import { type LoadKokoro } from './kokoro.js';
 import type { SpeechPort } from './speech.js';
-export type { LoadKokoro, KokoroModule, KokoroSession };
+export type { LoadKokoro };
+/**
+ * A PART OF A SPOKEN TEXT (ADR-0243 §1). Without `language` it is FRAME, read by the interface's voice; with a BCP-47 `language`
+ * it is CONTENT, read by a voice of that language and never by a voice of another one (§2) — an English word in a Portuguese
+ * activity is read by an English voice. A game already keeps the frame in keys and the content in `{params}`; this says which is which.
+ */
+export interface SpokenPart {
+    readonly text: string;
+    readonly language?: string;
+}
+/** What narration speaks: a text in the interface's language, or parts spoken in order, each in its own language. */
+export type SpokenText = string | readonly SpokenPart[];
+/** How a narration meets the one being spoken. Absent: it cuts it, as every narration always has. */
+export interface NarrateOptions {
+    /**
+     * THE PLAYER WHO ASKED, and then the narration takes turns with the other players' (ADR-0234, errata 2026-09-26 — the Dev: «em
+     * fila, não junto ao mesmo tempo com outro sonar em andamento», and «outro jogador não corta, mas um jogador corta a si
+     * mesmo»). Behind another player's narration still being spoken it waits, and is spoken when that one and each one waiting
+     * before it are over; a player's newer narration cuts that player's own being spoken, and replaces that player's own
+     * waiting, in its place in the line. The sonar's readings are spoken so. A narration that names no player still cuts
+     * whatever is being spoken, and ends the ones waiting too.
+     */
+    readonly seat?: number;
+}
+/** `finished` is called once the utterance is over, however it ends: what lets parts be spoken in order. */
 interface TtsEngine {
     id: string;
-    speak: (text: string) => void;
+    speak: (text: string, finished?: () => void) => void;
 }
 export interface TtsCtx {
     /**
@@ -55,9 +79,18 @@ export interface TtsCtx {
     speech: SpeechPort;
     /** The clock a browser utterance and a neural load are timed with: the root's `performance.now`. REQUIRED (ADR-0232 D4). */
     now: () => number;
+    /**
+     * Where a line of `problems` goes (ADR-0169): the root's list. Written once per language a part asked for and the device has no
+     * voice for (ADR-0243 §3). Absent, nothing is reported — a `tts` built outside a root has no `problems` to write to.
+     */
+    report?: (line: string) => void;
 }
 export interface Tts {
-    narrate: (text: string) => void;
+    /**
+     * The entry point, gated by the mixer: a text in the interface's language, or parts in order (ADR-0243 §1). It cuts what is
+     * being spoken, unless `how` names the player who asked — then it takes turns with the other players' (the sonar, ADR-0234).
+     */
+    narrate: (text: SpokenText, how?: NarrateOptions) => void;
     ttsSpeak: (text: string) => boolean;
     loadTTS: () => void;
     speakWebSpeech: (text: string) => boolean;

package/dist-pkg/platform/tts.js

@@ -4,9 +4,12 @@
 // 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 } from './voice-plan.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
@@ -31,6 +34,10 @@ export function createTts(ctx) {
     };
     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();
@@ -44,15 +51,16 @@ export function createTts(ctx) {
      * 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.
      */
-    const browserVoices = () => {
+    /** 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 voicesForLocale(bcp47(), list.map((v) => ({ locale: v.lang.replace('_', '-'), engine: 'webspeech', voice: 'webspeech:' + v.name })));
+        return list.map((v) => ({ locale: v.lang.replace('_', '-'), engine: 'webspeech', voice: 'webspeech:' + v.name }));
     };
-    const availableVoices = () => [...browserVoices(), ...(ctx.neuralVoice ? voicesForLocale(bcp47(), KOKORO_VOICES) : [])];
+    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:'))
@@ -64,10 +72,12 @@ export function createTts(ctx) {
             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() {
-        const list = availableVoices();
-        const storedVoiceId = ctx.store.get(KEYS.ttsVoz, null);
-        return list.find((v) => v.voice === storedVoiceId) ?? list[0] ?? null;
+        return voiceOfLanguage(bcp47(), availableVoices(), [ctx.store.get(KEYS.ttsVoz, null)]);
     }
     function chooseVoice(id) {
         if (!availableVoices().some((v) => v.voice === id))
@@ -77,36 +87,53 @@ export function createTts(ctx) {
         _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 = ctx.speech.synth();
             if (!ss)
                 return false;
             ss.cancel();
-            // `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 voiceName = _ttsVoiceObj ?? browserVoice(voiceInUse()?.voice);
-            const u = ctx.speech.utterance(text);
-            u.lang = bcp47();
-            if (voiceName)
-                u.voice = voiceName;
-            u.volume = Math.min(1, ctx.getVolume() * 1.4);
-            // 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.
-            const voiceIdOf = 'webspeech:' + (voiceName?.name ?? bcp47());
-            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);
-            };
-            ss.speak(u);
+            ss.speak(interfaceUtterance(text));
             return true;
         }
         catch (e) {
@@ -115,12 +142,14 @@ export function createTts(ctx) {
     }
     /**
      * 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.
+     * 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(voiceId, produce) {
+    function speakByWav(produce) {
         return createInterruptibleSpeech({
-            synthesize: async (text) => {
-                const bytes = await produce(text);
+            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
@@ -173,14 +202,25 @@ export function createTts(ctx) {
         ctx.srSay(t('sr.tts.downloading'));
         load().then(async (mod) => {
             const [symbolIds, table] = await Promise.all([mod.vocabulary(), mod.voice(kv.voice)]);
-            const synthesiseWith = async (kokoroSession, text) => {
-                const ids = tokenize(await mod.phonemize(text, kv.espeak), symbolIds);
-                return kokoroSession.synthesize(ids, sentenceStyle(table, ids.length - 2));
+            // 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')))) {
+                if (eFala(await synthesiseWith(gpu, t('tts.kokoro.teste'), kv))) {
                     kokoroSession = gpu;
                     kokoroBackend = 'webgpu';
                 }
@@ -191,8 +231,9 @@ export function createTts(ctx) {
                 kokoroBackend = 'wasm';
             }
             const used = kokoroSession;
-            const fala = speakByWav(kv.voice, async (text) => wavDe(await synthesiseWith(used, text)));
-            ttsEngine = { id: 'kokoro', speak: (text) => { fala.speak(text); } };
+            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();
@@ -229,34 +270,215 @@ export function createTts(ctx) {
         }
         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) {
-        if (engineSel() !== 'webspeech') {
-            // 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 && ttsEngine.speak) {
-                try {
-                    ttsEngine.speak(text);
-                }
-                catch (e) { /* noop */ }
-                return true;
+        const engine = interfaceEngine();
+        if (engine) {
+            try {
+                engine.speak(text);
             }
-            loadTTS(); // the neural engine is downloading or unavailable → falls back
+            catch (e) { /* noop */ }
+            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 narrate(text) {
+    /** 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;
+            }
+            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;
+        }
+        if (!speakingNow)
+            waiting.length = 0; // their turn was ended by a narration that named no player
+        void speakInTurn({ seat, segments }, ++narrationTurn);
+    }
+    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: engineSel, setEngineSel: (v) => { ttsEngineSelExplicito = v; },

package/dist-pkg/platform/voice-listener.d.ts

@@ -18,8 +18,12 @@ export interface VoiceListenerDeps {
     readonly createContext: () => AudioContextLike;
     /** What the recogniser has heard so far in this utterance. */
     readonly onPartial: (text: string) => void;
-    /** The utterance ended: whoever counts what was already answered for starts a new sentence. */
-    readonly onFinal?: () => void;
+    /**
+     * The utterance ended, with the recogniser's last word on it: a name the partials held back because another item's name
+     * continued it («voltar» while «voltar ao jogo» could follow) is decided HERE (ADR-0194 §3), and whoever counts what was
+     * already answered for starts a new sentence. `''` when the recogniser heard nothing it knows.
+     */
+    readonly onFinal?: (text: string) => void;
 }
 export interface VoiceListener {
     /** The words the recogniser may answer with, from now on. A new grammar is a new recogniser; the microphone stays open. */

package/dist-pkg/platform/voice-listener.js

@@ -31,7 +31,7 @@ export async function startVoiceListening(d) {
     const listen = (r) => {
         r.on('partialresult', (heard) => { const t = heard.result.partial; if (t)
             d.onPartial(t); });
-        r.on('result', () => { d.onFinal?.(); });
+        r.on('result', (heard) => { d.onFinal?.(heard.result.text ?? ''); });
     };
     listen(recognizer);
     const stream = await getUserMedia({ audio: { echoCancellation: true, noiseSuppression: true, channelCount: 1 } });

package/dist-pkg/platform/voice-plan.d.ts

@@ -11,3 +11,16 @@ export interface NeuralVoice {
  * is not offered: Portuguese text through English phonemes is noise.
  */
 export declare function voicesForLocale(tag: string, catalogue: readonly NeuralVoice[]): readonly NeuralVoice[];
+/**
+ * A language's name, written in another language: `languageName('en-GB', 'pt-BR')` is «inglês» — the primary language, because a
+ * voice of the same language would have read the part (ADR-0243 §3). Where the platform cannot name it, the tag's language code.
+ */
+export declare function languageName(tag: string, inLanguage: string): string;
+/** Does a voice tagged `locale` speak the language of `tag`? By the primary language, as `voicesForLocale` matches. */
+export declare function speaksLanguageOf(locale: string, tag: string): boolean;
+/**
+ * THE VOICE OF A LANGUAGE (ADR-0243 §2): the child's chosen voice when it speaks that language; else the first voice `VOICE_ORDER`
+ * reaches — the exact tag before the region, a browser voice before a neural one. `chosen` comes in order of precedence.
+ * 🔴 No voice of another language is ever returned: `null` means the list has none for it, and the part is not spoken (§3).
+ */
+export declare function voiceOfLanguage(tag: string, voices: readonly NeuralVoice[], chosen?: readonly (string | null | undefined)[]): NeuralVoice | null;

package/dist-pkg/platform/voice-plan.js

@@ -9,6 +9,61 @@
  * is not offered: Portuguese text through English phonemes is noise.
  */
 export function voicesForLocale(tag, catalogue) {
-    const language = (tag.split('-')[0] ?? '').toLowerCase();
-    return catalogue.filter((v) => (v.locale.split('-')[0] ?? '').toLowerCase() === language);
+    return catalogue.filter((v) => speaksLanguageOf(v.locale, tag));
+}
+/** The primary language of a BCP-47 tag, lower case: `pt` of `pt-BR`. A browser's `en_US` is normalised by whoever reads it. */
+const primaryLanguage = (tag) => (tag.split('-')[0] ?? '').toLowerCase();
+/**
+ * A language's name, written in another language: `languageName('en-GB', 'pt-BR')` is «inglês» — the primary language, because a
+ * voice of the same language would have read the part (ADR-0243 §3). Where the platform cannot name it, the tag's language code.
+ */
+export function languageName(tag, inLanguage) {
+    const code = primaryLanguage(tag);
+    try {
+        return new Intl.DisplayNames([inLanguage], { type: 'language' }).of(code) ?? code;
+    }
+    catch {
+        return code;
+    }
+}
+/** Does a voice tagged `locale` speak the language of `tag`? By the primary language, as `voicesForLocale` matches. */
+export function speaksLanguageOf(locale, tag) {
+    return primaryLanguage(locale) === primaryLanguage(tag);
+}
+/** The engine of a browser (Web Speech) voice in a list; every other engine is neural (ADR-0200). */
+const BROWSER_ENGINE = 'webspeech';
+const browser = (v) => v.engine === BROWSER_ENGINE;
+const exactTag = (v, tag) => v.locale.toLowerCase() === tag.toLowerCase();
+/**
+ * THE VOICE ORDER (ADR-0243 §2, the two errata of 2026-09-26), after the child's chosen voice. A BROWSER voice before a NEURAL one
+ * (the Dev: «Se a do navegador (mais leve) pode ser usada, a do navegador, senão ganha a voz neural (backup)»), but the exact tag
+ * before the region: asked whether a pt-PT browser voice reads a pt-BR part or the neural pt-BR voice does, the Dev: «Rede neural
+ * pt-BR.» So a voice of the same language and another region reads only where no voice of the exact tag exists, browser first.
+ * Every step is tried over the whole list, in order; within a step the list's own order decides. The interface's own voice
+ * follows the same order (`platform/tts`'s `voiceInUse`).
+ */
+const VOICE_ORDER = [
+    (v, tag) => browser(v) && exactTag(v, tag),
+    (v, tag) => !browser(v) && exactTag(v, tag),
+    (v) => browser(v),
+    (v) => !browser(v),
+];
+/**
+ * THE VOICE OF A LANGUAGE (ADR-0243 §2): the child's chosen voice when it speaks that language; else the first voice `VOICE_ORDER`
+ * reaches — the exact tag before the region, a browser voice before a neural one. `chosen` comes in order of precedence.
+ * 🔴 No voice of another language is ever returned: `null` means the list has none for it, and the part is not spoken (§3).
+ */
+export function voiceOfLanguage(tag, voices, chosen = []) {
+    const own = voicesForLocale(tag, voices);
+    for (const id of chosen) {
+        const picked = id ? own.find((v) => v.voice === id) : undefined;
+        if (picked)
+            return picked;
+    }
+    for (const step of VOICE_ORDER) {
+        const found = own.find((v) => step(v, tag));
+        if (found)
+            return found;
+    }
+    return null;
 }

package/dist-pkg/platform/vosk-runtime.d.ts

@@ -42,10 +42,24 @@ export interface VoskDeps {
      * put in the page once per address. REQUIRED, and injected so a gate never imports 3 MiB of wasm loader.
      */
     readonly loadBundle: (absoluteUrl: string) => Promise<VoskApi>;
+    /**
+     * The host's `fetch`, lent by the root, to read the MODEL'S VOCABULARY from the archive the recogniser opens
+     * (`platform/vosk-vocabulary`, ADR-0194 §4): the runtime keeps it inside its worker and tells the page nothing. Optional; without
+     * it the load carries no `vocabulary`, and a name with a word the model lacks goes unreported.
+     */
+    readonly fetch?: (absoluteUrl: string) => Promise<{
+        readonly ok: boolean;
+        readonly body: ReadableStream<BufferSource> | null;
+    }>;
 }
 export type VoskLoad = {
     readonly ok: true;
     readonly model: VoskModel;
+    /**
+     * The words the loaded model knows, read from its archive once asked — `null` when they cannot be read. Present only when the
+     * deps lent a `fetch`.
+     */
+    readonly vocabulary?: () => Promise<ReadonlySet<string> | null>;
 }
 /** The catalogue ids that are not in the checked cache — `language` when the project has no model for it. */
  | {
@@ -62,6 +76,17 @@ export type VoskLoad = {
  * memo at module level was one per PAGE, shared by roots that share nothing else. `load` is the root's `import(url)`.
  */
 export declare function createBundleLoader(load: (absoluteUrl: string) => Promise<unknown>): (absoluteUrl: string) => Promise<VoskApi>;
+/**
+ * ONE MODEL PER LANGUAGE, LOADED ONCE AND KEPT (ADR-0256): the 👄 and a choice by voice ask the same `load`, and a listener that
+ * stops no longer ends the model — the one handed out has a `terminate` that does nothing; the real one is ended when it is
+ * pushed out (more than `keep` languages, the oldest first) or by `closeAll()`, the root's end.
+ * 📏 Why: every start used to spawn a worker and unpack ~40 MiB of model, and every choice started two — the Dev's machine froze
+ * on 2026-09-27. A load that failed is forgotten, so a model that comes down later is found.
+ */
+export declare function keepVoskModels(load: (d: VoskDeps) => Promise<VoskLoad>, keep?: number): {
+    load(d: VoskDeps): Promise<VoskLoad>;
+    closeAll(): void;
+};
 /**
  * Opens the recogniser for the child's language, or says what is missing.
  *