@the-inclusionist/engine 9.0.0 → 11.0.0

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

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

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

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

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

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/where-the-child-is — WHERE THE CHILD IS NOW, AND WHAT THAT PLACE SAYS (ADR-0159 rule 3; ADR-0221 step 7c).
+//
+// «Opening a menu or panel speaks its title; closing it speaks where the child is back to; entering play is announced.»
+// 📏 Measured in the dist on 2026-09-12, before that rule was built: SELECT opened the card in silence, and a panel
+// opened, closed and went back to the root without a word. A child who plays by ear was moved without being told.
+//
+// WHAT THIS ANSWERS, AND WHY IT IS ONE QUESTION
+// Two things at once, and they belong together: a KEY, which is what «did she move?» is decided on, and the SENTENCE
+// to say when she did. Splitting them would let a caller compare one and speak the other, which is the defect the key
+// exists to prevent — an arrow inside a menu changes no `hidden`, so it must not read as a change of place.
+//
+// WHY IT IS NOT IN THE COMPOSITION ROOT
+// It used to be, and it was the densest function in `boot/create-game` after the root's own body: 19 branches in 24
+// lines. A root holds WIRING (ADR-0221's erratum: its debt is paid when the BRANCHES tend to zero), and «is this a
+// panel, a list of the pause card, or play, and what is its name» is a rule with a reason, not a wire.
+//
+// ⚠️ THE DOM ARRIVES BY QUESTION AND NOT BY GLOBAL: the overlay on top, the open card and the focused element are
+// asked of whoever owns the document. That is what lets a case drive it without a root, and what keeps the module out
+// of the `globalReach` ratchet (ADR-0221 step 7d).
+import { navigableItems } from './menu-items.js';
+import { announceItem } from './item-announcement.js';
+import { controlParts } from './menu-nav.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('. ');
+/** A PANEL: its title, and the item the focus is on — not the first, because the child may have walked into it. */
+function panelPlace(panel, ctx) {
+    const title = panel.querySelector('h2')?.textContent?.trim() ?? '';
+    const items = navigableItems(panel.querySelector('.overlay__card') ?? panel);
+    const focused = items.indexOf(ctx.focused());
+    const n = focused >= 0 ? focused : 0;
+    const item = items[n] ? announceItem(ctx.t, { ...controlParts(ctx.t, items[n]), position: n + 1, total: items.length }, ctx.withIndex()) : '';
+    // ⚠️ THE KEY NAMES WHICH PANEL. Two panels reading as the same place is a child moving from the sound panel to the
+    // visual one in silence — and going from one panel straight to another is a real path: «map the keyboard» opens the
+    // controls panel on top of the motor one.
+    return { key: `painel:${panel.id}`, sentence: say(title, item) };
+}
+/** THE PAUSE CARD: which list of it is showing, named by the item that opens it, and the item under the cursor. */
+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 = 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)];
+    // 📌 THE MARKED ITEM AND NOT THE FIRST: coming back from a panel, the cursor is on the row that opened it. Naming
+    // the first row would send a child who cannot see the mark looking where she is not.
+    const marked = card.querySelector('.pm-sel') ?? items[0];
+    const item = marked ? announceItem(ctx.t, { label: accessibleLabel(marked), position: items.indexOf(marked) + 1, total: items.length }, ctx.withIndex()) : '';
+    // ⚠️ AND THE KEY CARRIES THE LIST: the root and a submenu are the same card with different rows, so a key that
+    // stopped at the card's id would make entering the settings a non-event.
+    return { key: `cartao:${card.id}:${sub}`, sentence: say(title, item) };
+}
+/**
+ * The place, in the order the screen reads: a panel sits over the card, the card sits over the game.
+ *
+ * 📌 PLAY HAS NO SENTENCE HERE and that is deliberate: «back to the game» is the caller's word for its own world, and
+ * this module has no business naming a game it does not know.
+ */
+export function whereTheChildIs(ctx) {
+    const panel = ctx.topVisibleOverlay();
+    if (panel)
+        return panelPlace(panel, ctx);
+    const card = ctx.pauseCard();
+    if (card)
+        return cardPlace(card, ctx);
+    return { key: 'jogo', sentence: null };
+}