@the-inclusionist/engine 10.0.0 → 11.0.0

package/dist-pkg/ui/vlibras.js

@@ -1,64 +1,136 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 /**
- * Builds a deaf mode. The PERSON's choice, persisted — not an inference about a third-party widget — read from the store
- * here, at build, never at import (ADR-0232).
+ * Why a delivery that carries no Libras player cannot sign, and the fix — the ONE reason both `NO_INTERPRETER` and the free
+ * player give for it, so `problems` says the same thing whichever of them answered.
  */
-export function createLibras({ doc, win, store, now }) {
-    let open = store.getBool('incl_libras', false);
-    let vlOpen = false, node = null, busyUntil = 0, next = null;
+export const LIBRAS_NOT_INSTALLED = 'a Libras player is not installed in this delivery — build it with `inclusionist-heavy <folder> --libras`';
+/** The interpreter of a delivery that carries no Libras player (ADR-0234): it signs nothing and says why, and how to fix it. */
+export const NO_INTERPRETER = {
+    sign: () => Promise.resolve({ signed: false, reason: LIBRAS_NOT_INSTALLED }),
+    hide: () => { },
+    dispose: () => { },
+};
+/** The line `problems` gets when the interpreter cannot sign: the subject, the child's cost and the fix (ADR-0169). */
+export function signingUnavailableLine(reason) {
+    return `deaf mode's sign-language interpreter could not sign: ${reason}. A deaf child keeps the captions and the written `
+        + 'text, but nothing is signed when she presses the sonar — give deaf mode a Libras player that can sign here (ADR-0234)';
+}
+/** The line `problems` gets when the interpreter signed a text but left part of it out: what, the child's cost, the fix. */
+export function signedInPartLine(unsigned) {
+    return `deaf mode's sign-language interpreter signed only part of what the sonar found: ${unsigned}. A deaf child reads `
+        + 'those words in the captions and is not signed them — give the player the signs or the letters it lacks (ADR-0234)';
+}
+/** Builds a deaf mode. The stored choice is read here, at build, never at import (ADR-0232). */
+export function createDeafMode({ store, captionsSetting, t, interpreter, speak, caption, tell, report }) {
+    let on = store.getBool('incl_libras', false);
+    let disposed = false;
+    /** Whether the child has been told, since the mode last came on, that signing is unavailable — told once, not per press. */
+    let told = false;
+    /** The lines already in `problems`: a child pressing the sonar twenty times is one diagnosis, not twenty. */
+    const reported = new Set();
     const changeListeners = new Set();
-    const say = (text) => {
-        if (!vlOpen || !text)
+    /**
+     * The answer to one request, heard only while the mode that asked is still on and the root still alive. The first «no»
+     * is told through the announcer AND written after the sonar's text: she is deaf, and the announcer alone is heard.
+     */
+    const reportOnce = (line) => { if (!reported.has(line)) {
+        reported.add(line);
+        report(line);
+    } };
+    /** Signed, perhaps in part: what was left out is a diagnosis, not a notice — the child saw the rest signed. */
+    const signedPart = (unsigned) => { if (unsigned)
+        reportOnce(signedInPartLine(unsigned)); };
+    const heard = (text, result) => {
+        if (disposed || !on)
             return;
-        const at = now();
-        if (at < busyUntil) {
-            next = text;
+        if (result.signed) {
+            signedPart(result.unsigned);
             return;
         }
-        busyUntil = at + 4000;
-        if (!node) {
-            node = doc.createElement('span');
-            node.setAttribute('aria-hidden', 'true');
-            node.style.cssText = 'position:fixed;left:0;top:0;width:1px;height:1px;overflow:hidden;opacity:.01;z-index:1;pointer-events:auto';
-            doc.body.appendChild(node);
-        }
-        node.textContent = text;
+        reportOnce(signingUnavailableLine(result.reason));
+        if (told)
+            return;
+        told = true;
+        const notice = t('sr.deaf.noSigning');
+        tell(notice);
+        caption(`${text} ${notice}`);
+    };
+    /** One request signed: captioned when its turn comes, so the caption and the hands say the same thing; ends when it is heard. */
+    const signOne = (text) => {
+        caption(text);
+        let answer;
         try {
-            node.click();
+            answer = interpreter.sign(text);
+        }
+        catch (failure) {
+            answer = Promise.reject(failure);
         }
-        catch (e) { /* noop */ }
-        win.setTimeout(() => { const nx = next; next = null; busyUntil = 0; if (nx)
-            say(nx); }, 4100);
+        return answer.then((result) => { heard(text, result); }, (failure) => {
+            heard(text, { signed: false, reason: failure instanceof Error ? failure.message : String(failure) });
+        });
     };
-    const toggle = (t) => {
-        open = !open;
-        vlOpen = open;
-        store.setBool('incl_libras', open);
-        // A BEST-EFFORT attempt to wake the VLibras widget, if it is loaded. Failing here must not stop the mode from
-        // turning on: the state is the person's choice, and the widget is only one possible translator for them.
-        const b = doc.querySelector('[vw-access-button]');
-        if (open && b) {
-            try {
-                b.click();
-            }
-            catch (e) { /* noop */ }
+    /** The players' requests waiting behind the one being signed, at most one per player, in the order they asked. */
+    const waiting = [];
+    /** Whose request is being signed, when it is a player's; `null` when none is, or when the one being signed named no player. */
+    let seatSigning = null;
+    /** Bumped by every request that takes the line, so one that ends after being overtaken does not sign the next in line. */
+    let line = 0;
+    /** Ends the line: nothing waits and nobody is being signed (the mode went off, or the root went away). */
+    const endLine = () => { line++; waiting.length = 0; seatSigning = null; };
+    const signInTurn = async (seat, text) => {
+        const mine = ++line;
+        for (let next = { seat, text }; next; next = waiting.shift()) {
+            seatSigning = next.seat;
+            await signOne(next.text);
+            if (mine !== line)
+                return; // overtaken: the line is the newer request's now
         }
-        else if (!open) {
-            try {
-                win.dispatchEvent(new CustomEvent('vp-widget-close'));
-            }
-            catch (e) { /* noop */ }
+        seatSigning = null;
+    };
+    const toggle = () => {
+        on = !on;
+        store.setBool('incl_libras', on);
+        if (on)
+            told = false;
+        else {
+            endLine();
+            interpreter.hide();
         }
         for (const fn of [...changeListeners])
             fn();
-        if (open)
-            say(t('sr.libras.on'));
+    };
+    /**
+     * THE INTERPRETER TAKES TURNS, as the narration does (ADR-0234, errata 2026-09-26 — the Dev: «Sim»): a request from ANOTHER
+     * player waits until the one being signed ends — replacing that player's own waiting one, in its place — and a player's newer
+     * request replaces that player's own, at once, the others waiting behind it. A request that names no player takes the line.
+     */
+    const sonar = (text, seat) => {
+        if (!on) {
+            speak(text, seat);
+            return;
+        }
+        if (seat !== undefined && seatSigning !== null && seat !== seatSigning) {
+            const own = waiting.find((w) => w.seat === seat);
+            if (own)
+                own.text = text;
+            else
+                waiting.push({ seat, text });
+            return;
+        }
+        if (seat === undefined || seatSigning === null)
+            waiting.length = 0;
+        void signInTurn(seat ?? null, text);
     };
     return {
-        isOpen: () => open,
+        isOn: () => on,
         toggle,
-        say,
-        tick: () => { vlOpen = open; },
+        captionsOn: () => on || captionsSetting(),
+        sonar,
         onChange: (fn) => { changeListeners.add(fn); return () => { changeListeners.delete(fn); }; },
+        dispose: () => {
+            disposed = true;
+            endLine();
+            interpreter.dispose();
+        },
     };
 }

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

@@ -13,8 +13,18 @@ export interface VoiceControlDeps {
     /** The child's language (`core/i18n.bcp47`): it chooses the model AND the words. */
     readonly language: () => string;
     readonly controller: VirtualController;
-    /** The names the open menu is showing right now, if any (ADR-0194). */
+    /** The names the open menu is showing right now, if any (ADR-0194) — `ui/menu-nav.itemNames`. */
     readonly menuWords: () => readonly string[];
+    /**
+     * Puts the open menu's cursor on the item with this name, WITHOUT activating it — `ui/menu-nav.pointAt`. REQUIRED: it is
+     * what makes a name heard reach its item. `false` when that item is no longer there; then nothing is confirmed.
+     */
+    readonly pointAt: (name: string) => boolean;
+    /**
+     * ONE BUTTON ONLY is on (ADR-0218 §4): whatever the child says is her switch, one press the controller takes as «take the one
+     * shown» — so a name heard is not a place and nothing is pointed at. REQUIRED: without it a name is a cursor move AND a take.
+     */
+    readonly oneButtonOnly: () => boolean;
     readonly say: (text: string) => void;
     readonly alert: (text: string) => void;
     readonly report: (line: string) => void;
@@ -23,6 +33,8 @@ export interface VoiceControlDeps {
     readonly after: (fn: () => void, ms: number) => void;
     readonly hasFile: VoskDeps['hasFile'];
     readonly loadBundle: VoskDeps['loadBundle'];
+    /** The host's `fetch`, handed on to read the loaded model's vocabulary (ADR-0194 §4). Without it an unsayable name goes unreported. */
+    readonly fetch?: VoskDeps['fetch'];
     readonly getUserMedia: VoiceListenerDeps['getUserMedia'];
     readonly createContext: VoiceListenerDeps['createContext'];
     readonly loadRuntime?: (deps: VoskDeps) => Promise<VoskLoad>;
@@ -42,5 +54,15 @@ export interface VoiceControl extends SwitchableControl {
      * because the next start already reads the new language.
      */
     languageChanged(): Promise<void>;
+    /**
+     * LENDS THIS EAR TO A CHOICE AMONG THE GAME'S OPTIONS (ADR-0256): while it is listening in `language`, the grammar becomes
+     * `grammar` and every text heard goes to `onHeard` instead of being obeyed; `stop()` gives the menu's grammar back. `null` when
+     * it is not listening, or listens in another language — then the choice opens an ear of its own.
+     * 📏 Without it every choice paused this recogniser and opened another: two workers and two microphones per press, 40 MiB of
+     * model unpacked each time, measured on 2026-09-27 — and the Dev's machine froze.
+     */
+    borrow(language: string, grammar: readonly string[], onHeard: (text: string, final: boolean) => void): {
+        stop(): Promise<void>;
+    } | null;
 }
 export declare function createVoiceControl(d: VoiceControlDeps): VoiceControl;

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

@@ -9,14 +9,29 @@
 // 📌 THE GRAMMAR FOLLOWS THE MENU (ADR-0194): saying the name of an item activates it, so the words the open menu is showing
 // join the closed grammar while it is open and leave with it.
 //
-// ⚠️ A SPOKEN COMMAND IS A TAP, NOT A HOLD. The word arrives, the position is pressed and let go — and the latch (ADR-0211,
-// always on for speech) is what keeps a direction held afterwards. That division is the whole reason the latch is forced there:
-// a child who says «acima» cannot also say «and keep holding it».
+// 🎯 A NAME HEARD IS A CURSOR AND A CONFIRM, NOT A CLICK (ADR-0194 §2): the root's menu navigation puts the cursor on the
+// named item (`pointAt`), and the confirm position is pressed on the virtual controller like any other spoken word — so the
+// item is activated by the same path, with the same spoken feedback, as a child confirming it with the cursor on it. WHEN a
+// name fires is the reader's (`input/voice-map` over `platform/speech-recognition`): at once, unless another item's name
+// continues it («voltar» / «voltar ao jogo»), which waits for the end of the utterance (§3). A LOCKED item's name is heard
+// too and takes the same path: the confirm reaches the item's own press, which says its reason and does nothing (§5, ADR-0161).
+// A name with a word the loaded model lacks cannot be heard at all, and is a line of `problems` (§4).
+// ⚠️ EXCEPT WITH ONE BUTTON ONLY ON (ADR-0218 §4): then every word heard, a name included, is the child's switch and nothing more
+// — one press, which the controller takes as «take the one shown», and no cursor put anywhere first.
+//
+// ⚠️ A SPOKEN COMMAND IS A TAP, NOT A HOLD. The word arrives, the position is pressed and let go — one press, one release.
+// Whether that tap keeps a direction going is the latch's, and on speech the latch starts as the GAME answers `holdsKeys()`
+// (ADR-0249, resolved by the root when the press arrives): a platform game keeps walking on «direita», a quiz moves once on
+// «abaixo», and the child may change either for her voice.
 import { voiceGrammar, createVoiceCommands } from '../input/voice-map.js';
 import { loadVoskRuntime } from '../platform/vosk-runtime.js';
 import { startVoiceListening } from '../platform/voice-listener.js';
+import { spokenText } from '../platform/speech-recognition.js';
+import { MENU_CONFIRM } from './menu-intent.js';
 /** How long a spoken position stays pressed. The same pulse the scan uses: long enough for a game to see a press and a release. */
 export const VOICE_PULSE_MS = 400;
+/** The base of a language tag: `en-US` and `en` are the same model. */
+const baseOf = (tag) => tag.split('-')[0].toLowerCase();
 export function createVoiceControl(d) {
     const { t } = d;
     const loadRuntime = d.loadRuntime ?? loadVoskRuntime;
@@ -25,15 +40,77 @@ export function createVoiceControl(d) {
     let on = false, starting = null;
     let listener = null;
     let commands = null;
-    const grammarNow = () => voiceGrammar(d.language(), d.menuWords());
+    let grammarGiven = '';
+    /** The words the model now listening knows, once read (`platform/vosk-vocabulary`); `null` while unknown. */
+    let vocabulary = null;
+    /** Bumped by every stop, so a vocabulary that arrives for a recogniser already replaced is dropped. */
+    let generation = 0;
+    /**
+     * 🔴 THE LANGUAGE THE LISTENING STARTED IN, read ONCE. The model and the grammar must come from the same reading: `start()` used
+     * to read the language again after the model had loaded, and a page booting in English (pt-BR until its stored language
+     * applies) opened the Portuguese model with the English grammar — 15 «missing in vocabulary», measured on 2026-09-27.
+     */
+    let listeningLanguage = '';
+    /** A choice among the game's options borrowing this ear (ADR-0256): what is heard goes to it, and no command is obeyed. */
+    let lent = null;
+    /** The open menu's names that can enter the grammar. A one-letter name stays out: in a closed grammar every short noise lands on it. */
+    const sayableNames = () => d.menuWords().filter((n) => spokenText(n).length > 1);
+    /**
+     * 🔴 A NAME THE MODEL CANNOT HEAR IS SAID TO THE ADULT (ADR-0194 §4, ADR-0169): Kaldi drops a grammar word its vocabulary lacks,
+     * in silence, and the item goes mute for the child — she can still walk to it with the direction words. One line per item and
+     * language, naming the words, the cost and the fix. Nothing is said while the vocabulary is unknown: no line beats a false one.
+     */
+    const reportUnsayable = (names) => {
+        const known = vocabulary;
+        if (!known)
+            return;
+        const language = listeningLanguage;
+        for (const name of names) {
+            const lacking = [...new Set(spokenText(name).split(' '))].filter((w) => w && !known.has(w));
+            const kind = `unsayable:${language}:${name}`;
+            if (!lacking.length || said.has(kind))
+                continue;
+            said.add(kind);
+            d.report(`voice control: the menu item "${name}" has ${lacking.length === 1 ? 'a word' : 'words'} the ${language} speech `
+                + `model does not know (${lacking.map((w) => `"${w}"`).join(', ')}) — the child cannot choose this item by saying its name, `
+                + `only by walking to it with the direction words; reword the item's label in the ${language} dictionary with words the `
+                + 'model knows (ADR-0194 §4)');
+        }
+    };
+    /** The open menu's names, handed to the reader and checked against the model, and the grammar with them. */
+    const followMenu = () => {
+        const names = sayableNames();
+        commands?.items(names);
+        reportUnsayable(names);
+        return voiceGrammar(listeningLanguage, names);
+    };
     const command = (action) => {
         d.controller.press(action, 'fala');
         d.after(() => d.controller.release(action, 'fala'), VOICE_PULSE_MS);
     };
+    /*
+     * 🔴 ONE WORD HEARD IS ONE ACTION (ADR-0111 errata, ADR-0218 §4). With one button only on, the controller takes every press as
+     * «take the one shown», so a word may do nothing BESIDES its press: asked here, first, for every word — a position, a name, any
+     * kind a later reader adds. 📏 Before, a name was still pointed at: with the chip on «próximo» the cursor jumped to the named
+     * item and then stepped on from it; on «cancelar» the press meant nothing and the cursor had moved anyway.
+     */
+    const obey = (heard) => {
+        for (const c of heard ?? []) {
+            if (d.oneButtonOnly())
+                command(c.kind === 'position' ? c.action : MENU_CONFIRM);
+            else if (c.kind === 'position')
+                command(c.action);
+            else if (d.pointAt(c.name))
+                command(MENU_CONFIRM);
+        }
+    };
     const stop = () => {
         const going = listener;
         listener = null;
         commands = null;
+        lent = null;
+        vocabulary = null;
+        generation += 1;
         void going?.stop();
     };
     /**
@@ -60,7 +137,9 @@ export function createVoiceControl(d) {
         let load;
         const language = d.language();
         try {
-            load = await loadRuntime({ base: d.base, language, hasFile: d.hasFile, loadBundle: d.loadBundle });
+            load = await loadRuntime({
+                base: d.base, language, hasFile: d.hasFile, loadBundle: d.loadBundle, ...(d.fetch ? { fetch: d.fetch } : {}),
+            });
         }
         catch (e) {
             failed('runtime', `voice control: the recogniser did not open (${e instanceof Error ? e.message : String(e)}) — the child `
@@ -69,26 +148,40 @@ export function createVoiceControl(d) {
         }
         if (!load.ok) {
             /*
-             * 📌 ONE LINE PER LANGUAGE, NAMING THAT LANGUAGE'S FIX (ADR-0225, ADR-0169). The install fetches the command model of the
-             * BOOT language only, so a child who switches can ask for one the delivery never carried; «open it online» alone sends
-             * the adult after a download that cannot happen. The reading's line names `--reading <language>` the same way.
+             * 📌 ONE LINE PER LANGUAGE, NAMING THAT LANGUAGE'S FIX (ADR-0225 and its erratum, ADR-0169). The delivery carries every
+             * language unless its `--commands` list narrowed it, and the install fetches every one the delivery carries — so a model
+             * missing here was left out of the delivery or has not come down yet, and «open it online» alone sends the adult after a
+             * download that cannot happen in the first case. The reading's line names its two fixes the same way.
              */
             const lang = language.split('-')[0].toLowerCase();
             failed(`files:${lang}`, `voice control: ${load.missing.join(', ')} not on this device for ${language} — the child cannot play `
-                + `by speaking in this language; build the delivery with \`npx inclusionist-heavy --commands ${lang}\` and open the game `
-                + 'once online in this language so the install fetches them', t('sr.voice.needsInternet'));
+                + `by speaking in this language; build the delivery with \`npx inclusionist-heavy\` without \`--commands\` (it carries every `
+                + `language) or with \`--commands ${lang}\` in its list, and open the game once online so the install fetches them`, t('sr.voice.needsInternet'));
+            return;
+        }
+        // the language changed while the model loaded (a page booting before its stored language applies): start again in it
+        if (baseOf(d.language()) !== baseOf(language)) {
+            await start();
             return;
         }
-        commands = createVoiceCommands(d.language());
+        listeningLanguage = language;
+        commands = createVoiceCommands(language);
+        const grammar = followMenu();
+        grammarGiven = grammar.join('\n');
         try {
             listener = await listen({
                 model: load.model,
-                grammar: grammarNow(),
+                grammar,
                 getUserMedia: d.getUserMedia,
                 createContext: d.createContext,
-                onPartial: (text) => { const a = commands?.partial(text); if (a)
-                    command(a); },
-                onFinal: () => commands?.reset(),
+                onPartial: (text) => { if (lent)
+                    lent(text, false);
+                else
+                    obey(commands?.partial(text)); },
+                onFinal: (text) => { if (lent)
+                    lent(text, true);
+                else
+                    obey(commands?.final(text)); },
             });
         }
         catch {
@@ -102,7 +195,18 @@ export function createVoiceControl(d) {
             stop();
             return;
         }
+        // a menu that opened or closed while the microphone was opening changed the names after the grammar above was built
+        api.refreshGrammar();
         d.say(t('sr.voice.ready'));
+        // 📌 THE VOCABULARY IS READ AFTER THE CHILD CAN SPEAK, never before: it is a report for the adult, and reading the model's
+        // archive a second time must not delay the first command. It checks the names showing when it arrives and every later menu.
+        const mine = generation;
+        void load.vocabulary?.().then((words) => {
+            if (mine !== generation || !listener)
+                return;
+            vocabulary = words;
+            reportUnsayable(sayableNames());
+        });
     };
     const api = {
         async apply(next) {
@@ -117,7 +221,17 @@ export function createVoiceControl(d) {
             await starting;
         },
         refreshGrammar() {
-            listener?.setGrammar(grammarNow());
+            // lent to a choice: the options are the grammar until it gives the ear back
+            if (!listener || lent)
+                return;
+            // 📌 A new grammar is a new recogniser (`platform/voice-listener`), and the root asks on every menu change it sees —
+            // most of which change no name. Only a grammar that differs is handed on.
+            const grammar = followMenu();
+            const given = grammar.join('\n');
+            if (given === grammarGiven)
+                return;
+            grammarGiven = given;
+            listener.setGrammar(grammar);
         },
         async languageChanged() {
             /*
@@ -135,9 +249,28 @@ export function createVoiceControl(d) {
             // ⚠️ A START IN FLIGHT IS IN THE OLD LANGUAGE. Letting it finish and replacing it costs one opening; skipping it would
             // leave `starting` to install the old model on top of the new one, which is the race the `if (!on)` in `start` exists for.
             await starting;
+            // a start that noticed the change itself is already listening in the new language: nothing to redo
+            if (listener && baseOf(listeningLanguage) === baseOf(d.language()))
+                return;
             stop();
             await api.apply(true);
         },
+        borrow(language, grammar, onHeard) {
+            if (!listener || lent || baseOf(language) !== baseOf(listeningLanguage))
+                return null;
+            const held = listener;
+            lent = onHeard;
+            held.setGrammar(grammar);
+            grammarGiven = '';
+            return {
+                async stop() {
+                    if (lent !== onHeard)
+                        return;
+                    lent = null;
+                    api.refreshGrammar(); // the menu's grammar back
+                },
+            };
+        },
     };
     return api;
 }

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

@@ -47,8 +47,7 @@ export interface VoicePorts {
     /** Speak the sample through the BROWSER's own synthesiser — the neural engine speaks through `tts` instead. */
     readonly speakSample: (text: string, chosen: SpeechSynthesisVoice | null) => void;
     /** Called again whenever the browser finishes loading its voice list: they arrive late, and often empty first.
-     *  ⚠️ The parameter is gain and not
-  un, which is a GAME ACTION word this layer does not say (the boundary of 2026-09-06). */
+     *  ⚠️ The parameter is `again` and not `run`, which is a GAME ACTION word this layer does not say (the boundary of 2026-09-06). */
     readonly whenVoicesChange: (again: () => void) => void;
 }
 /**
@@ -90,7 +89,7 @@ export interface VoiceSettingsCtx {
 export interface VoiceSettings {
     /** Everything the section shows, refreshed from the stored state. Called by the panel's own render. */
     render: () => void;
-    /** Just the narration switch and the chosen engine. Exported because the quick bar's icon reflects it from outside. */
+    /** Just the narration switch, its volume and the chosen engine. Exported because the root reflects it from outside. */
     reflectTts: () => void;
 }
 export declare function createVoiceSettings(ctx: VoiceSettingsCtx, ports: VoicePorts): VoiceSettings;

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

@@ -34,8 +34,11 @@ function voiceName(v) {
 function panelVoiceLabel(v) {
     return (v.recommended ? '❤️ ' : '') + voiceName(v);
 }
-/** The rows a missing voice locks (ADR-0185 §4): narration, its volume and rate, the spoken index, and the voice. */
-const SPEECH_ROWS = ['#opt-tts', '#tts-vol', '#tts-ppm', '#opt-menuindex', '#tts-voz'];
+/**
+ * The rows a missing voice locks (ADR-0185 §4): narration, its volume and rate, the spoken index, the voice — and the «test voice»
+ * button a page may carry, which with no voice of the language would ask the browser for one of another (ADR-0243 §3).
+ */
+const SPEECH_ROWS = ['#opt-tts', '#tts-vol', '#tts-ppm', '#opt-menuindex', '#tts-voz', '#opt-tts-test'];
 export function createVoiceSettings(ctx, ports) {
     const { t, bcp47 } = ctx.translator;
     function reflectTts() {
@@ -46,6 +49,10 @@ export function createVoiceSettings(ctx, ports) {
             ctx.toggleBtn(b, on);
             b.textContent = toggleLabel(t, on);
         }
+        // and its volume: the slider was never drawn from the mixer, so it opened at the range's middle whatever was stored
+        const vol = ctx.$('#tts-vol');
+        if (vol && cat?.tts)
+            vol.value = String(volPercent(cat.tts.vol));
         const e = ctx.$('#tts-engine');
         if (e)
             e.value = ctx.tts.getEngineSel();
@@ -95,6 +102,8 @@ export function createVoiceSettings(ctx, ports) {
         ctx.tts.setVoiceObj(pick);
     }
     const noVoice = () => !!ctx.tts.voices && ctx.tts.voices().length === 0;
+    /** The lock last drawn on the speech rows; `null` before it is first drawn. Compared when the voices change. */
+    let lockDrawn = null;
     /** The speech rate list: each step «N PPM», the stored one selected (ADR-0183 §1, ADR-0196). */
     function renderRate() {
         const sel = ctx.$('#tts-ppm');
@@ -110,11 +119,15 @@ export function createVoiceSettings(ctx, ports) {
         }
         sel.value = String(ctx.settings.speechPpm);
     }
+    /** The voices of the language as ids, one per line: what the «Voz» list was last drawn from. */
+    const voiceIds = () => (ctx.tts.voices?.() ?? []).map((v) => v.voice).join('\n');
+    let listDrawn = null;
     function renderVoiceList() {
         const sel = ctx.$('#tts-voz');
         if (!sel || !ctx.tts.voices)
             return;
         const list = ctx.tts.voices();
+        listDrawn = voiceIds();
         sel.replaceChildren(); // options built node by node: no markup sink
         if (!list.length) {
             const o = ports.newOption();
@@ -136,6 +149,7 @@ export function createVoiceSettings(ctx, ports) {
      */
     function lockSpeechRows() {
         const lock = noVoice();
+        lockDrawn = lock;
         for (const id of SPEECH_ROWS) {
             const el = ctx.$(id);
             if (!el)
@@ -284,7 +298,43 @@ export function createVoiceSettings(ctx, ports) {
             });
     }
     wireControls();
-    ports.whenVoicesChange(populateTtsVoices);
+    /**
+     * A LOCK THAT FLIPS UNDER THE CURSOR IS TOLD, and only there (ADR-0185 erratum 2026-09-26). The footer is written with what
+     * focusing the row would show NOW — the reason, or the row's own explanation — because it would otherwise go on saying «no
+     * voice» under a row that works. Locking is heard once, through the footer, which is `aria-live`, as when a locked row is
+     * focused. Unlocking gets one sentence more: the footer then gives the row's explanation, which does not say the state
+     * changed, and whether a removed `aria-disabled` on the focused control is spoken is left to each screen reader.
+     */
+    function tellUnderCursor() {
+        const el = SPEECH_ROWS.map((id) => ctx.$(id)).find((e) => !!e && e.ownerDocument?.activeElement === e);
+        if (!el)
+            return;
+        const footer = el.closest('.overlay__card')?.querySelector('.opt-explain');
+        if (lockDrawn) {
+            if (footer)
+                footer.textContent = el.dataset.motivo ?? '';
+            return;
+        }
+        if (footer)
+            footer.textContent = el.closest('.ctrl-row')?.dataset.explain || (footer.dataset.idle ?? '');
+        ctx.srSay(t('audio.comVoz'));
+    }
+    /**
+     * 🔴 THE DEVICE'S VOICES CHANGED (ADR-0185 §4, erratum 2026-09-26): a device may list them a moment after load — empty first,
+     * then full — and may lose them. The lock is a fact about those voices, so it is evaluated again here, both ways, IN PLACE:
+     * attributes on the same nodes, never a redraw, so the focus stays where the child left it. Only a change is drawn or told:
+     * the voice list when its voices differ, the rows and the cursor's row when the lock flips.
+     */
+    function voicesChanged() {
+        populateTtsVoices();
+        if (voiceIds() !== listDrawn)
+            renderVoiceList(); // the same voices keep the same options, which the child may be reading
+        const before = lockDrawn;
+        lockSpeechRows();
+        if (lockDrawn !== before)
+            tellUnderCursor();
+    }
+    ports.whenVoicesChange(voicesChanged);
     return {
         render: () => {
             reflectTts();

package/dist-pkg/ui/where-the-child-is.js

@@ -21,7 +21,7 @@
 import { navigableItems } from './menu-items.js';
 import { announceItem } from './item-announcement.js';
 import { controlParts } from './menu-nav.js';
-import { PM_VISIBLE_ITEMS } from './pause-icons.js';
+import { PM_VISIBLE_ITEMS, LIST_DOOR } from './pause-icons.js';
 import { accessibleLabel } from '../core/accessible-label.js';
 /** Title and item joined the way a screen reader reads them: the place first, then where the cursor is in it. */
 const say = (title, item) => [title, item].filter(Boolean).join('. ');
@@ -41,7 +41,7 @@ function panelPlace(panel, ctx) {
 function cardPlace(card, ctx) {
     const sub = card.querySelector('.pause-menu:not([hidden])')?.dataset.sub ?? 'raiz';
     // a submenu is named by the item that opens it; the root by the card's title
-    const door = sub === 'opcoes' ? 'options' : sub === 'jogo' ? 'opcoesdojogo' : null;
+    const door = LIST_DOOR[sub] ?? null;
     const button = door ? card.querySelector(`.pm-btn[data-act="${door}"]`) : null;
     const title = button ? accessibleLabel(button) : (card.querySelector('h2')?.textContent?.trim() ?? '');
     const items = [...card.querySelectorAll(PM_VISIBLE_ITEMS)];