@the-inclusionist/engine 10.0.0 → 11.0.0

package/dist-pkg/platform/interruptible-speech.js

@@ -31,6 +31,7 @@
 // in milliseconds.
 export function createInterruptibleSpeech(engine) {
     let nowPlaying = null;
+    let nowFinished = null;
     let currentTurn = 0;
     /** Silences whatever is playing. The `try` exists because stopping an already finished source throws in some engines. */
     function stopPlayback() {
@@ -41,37 +42,60 @@ export function createInterruptibleSpeech(engine) {
             catch (e) { /* the source already ended — stopping again is no error */ }
             nowPlaying = null;
         }
+        const finished = nowFinished;
+        nowFinished = null;
+        finished?.();
     }
-    async function speakNow(text) {
+    async function speakNow(request, finished) {
         const myTurn = ++currentTurn; // claims the turn BEFORE any wait
         stopPlayback(); // guarantee 1: immediate silence, not at the end of synthesis
-        if (!text)
+        if (!request) {
+            finished();
             return;
+        }
         try {
-            const audio = await engine.synthesize(text);
-            if (myTurn !== currentTurn)
-                return; // guarantee 2: it arrived late — another request already took over
+            const audio = await engine.synthesize(request);
+            if (myTurn !== currentTurn) {
+                finished();
+                return;
+            } // guarantee 2: it arrived late — another request already took over
             stopPlayback(); // again: something may have started playing during the wait
-            const playing = engine.play(audio, () => { if (nowPlaying === playing)
-                nowPlaying = null; });
+            const playing = engine.play(audio, () => {
+                if (nowPlaying === playing) {
+                    nowPlaying = null;
+                    nowFinished = null;
+                }
+                finished();
+            });
+            if (playing === null) {
+                finished();
+                return;
+            }
             if (myTurn !== currentTurn) {
-                if (playing !== null) {
-                    try {
-                        engine.stop(playing);
-                    }
-                    catch (e) { /* noop */ }
+                try {
+                    engine.stop(playing);
                 }
+                catch (e) { /* noop */ }
+                finished();
                 return;
             }
             nowPlaying = playing;
+            nowFinished = finished;
         }
         catch (e) {
             // Synthesis failed for THIS text. No reason to bring the whole narration down: the next request tries again, and one
             // silent item is better than a dead engine.
+            finished();
         }
     }
+    /** Calls `finished` at most once, whichever of the ends above comes first. */
+    const once = (finished) => {
+        let called = false;
+        return () => { if (called)
+            return; called = true; finished?.(); };
+    };
     return {
-        speak: (text) => { void speakNow(text); },
+        speak: (request, finished) => { void speakNow(request, once(finished)); },
         silence: () => { currentTurn++; stopPlayback(); }, // the `++` invalidates whatever is being synthesised now
         speaking: () => nowPlaying !== null,
     };

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

@@ -46,18 +46,29 @@ export function createListenerScope(real) {
      * ⚠️ WHAT LEAVES THIS TRAP IS ANSWERED BY THE REAL WINDOW, NEVER BY THE PROXY, and it is not style: `innerWidth`,
      * `devicePixelRatio` and `location` are GETTERS on the window, and `getComputedStyle`, `requestAnimationFrame` and
      * `matchMedia` are methods of it — run any of them with the proxy as `this` and the browser answers «Illegal invocation».
-     * So the receiver is left at its default (which IS the target) and every function is bound before it goes out.
+     * So the receiver is left at its default (which IS the target) and every function leaves answered by the real window.
      *
-     * 📌 Both halves are exercised, by mutation: forwarding the proxy as the receiver kills the whole collection at load, and
-     * dropping the `bind` kills it at the first `getComputedStyle`.
-     *
-     * 🔴 BUT A CONSTRUCTOR LEAVES UNBOUND, and this was not foreseen — the suite found it. `bind` returns a function with NO
-     * `prototype`, and code that reaches a constructor THROUGH the window reads that prototype: `platform/speech-recognition`
-     * asks `'processLocally' in api.prototype` before it will use the browser's recogniser on the device, and bound, that read is
-     * `in undefined`. 📏 Measured: `tests/reading-no-createGame.browser.test.js` went red — the child who reads aloud got no
-     * microphone at all. A constructor never needs `this` from the property access; a method always does, and `prototype` is the
-     * one thing that tells the two apart.
+     * 🔴 EVERY FUNCTION, WITH NO GUESS AT WHAT IT IS (`onTheWindow`): a call runs with the real window as `this`, and everything
+     * else — `new`, the `prototype`, a static like `SpeechRecognition.available` — reaches the function itself. The rule before
+     * guessed: a function with a `prototype` was a constructor and left unbound, the rest were `bind`-ed. The guess held for the
+     * browser's own functions and failed for an extension's: one that wraps `window.fetch` does it with a plain `function`, which
+     * HAS a `prototype`, so the engine's fetch left unbound and every heavy file failed with «Illegal invocation» inside the
+     * download's `catch`. 📏 Measured on 2026-09-27 in the Dev's Brave: no heavy file ever requested, an empty checked cache, and
+     * the 👄 and the 📷 unable to start; with a wrapped fetch in a clean profile, 0 requests against 66 without it. A `bind` could
+     * not be the answer either: it drops the `prototype` that `platform/speech-recognition` reads.
      */
+    const answered = new WeakMap();
+    const onTheWindow = (fn) => {
+        // one wrapper per function, so the same property read twice is the same function; `new` builds with the function itself as
+        // the target — with the wrapper as `newTarget`, a constructor already bound (a host may lend one) built an object with none of
+        // its methods («observe is not a function», measured in `tests/no-need-to-hold.browser.test.js`)
+        if (!answered.has(fn))
+            answered.set(fn, new Proxy(fn, {
+                apply: (f, _this, args) => Reflect.apply(f, real, args),
+                construct: (f, args) => Reflect.construct(f, args),
+            }));
+        return answered.get(fn);
+    };
     const win = new Proxy(real, {
         get(target, prop) {
             if (prop === 'addEventListener')
@@ -65,9 +76,7 @@ export function createListenerScope(real) {
             if (prop === 'removeEventListener')
                 return forget;
             const value = Reflect.get(target, prop);
-            if (typeof value !== 'function')
-                return value;
-            return Object.hasOwn(value, 'prototype') ? value : value.bind(target);
+            return typeof value === 'function' ? onTheWindow(value) : value;
         },
     });
     const releaseAll = () => {

package/dist-pkg/platform/locale-host.d.ts

@@ -1,10 +1,14 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** The two hooks `core/i18n`'s port takes. A host that has no page passes neither, and the engine runs without one. */
+/** The three hooks `core/i18n`'s port takes. A host that has no page passes none, and the engine runs without one. */
 export interface LocaleHostHooks {
     readonly applied: (locale: string, tag: string) => void;
     readonly preferred: () => string | null;
+    readonly follow: (react: (locale: string) => void) => void;
 }
-/** What a browser can offer `core/i18n`: the page effects of a change, and the language the person's browser is set to. */
+/**
+ * What a browser can offer a translator: the page effects of a change, the language the person's browser is set to, and
+ * the page's signal that ANOTHER root changed the language (ADR-0232 D3: the language is the page's, and every root follows).
+ */
 export declare function localeHostHooks(doc: Document, win: Window, applyDom: (root: ParentNode) => void): LocaleHostHooks;
-/** Hangs the i18n object on the window for tests and the preview, which is what `core/i18n` used to do to itself. */
+/** Hangs a root's translator on the window for tests and the preview, which is what `core/i18n` used to do to itself. */
 export declare function exposeI18n(win: Window, i18n: unknown): void;

package/dist-pkg/platform/locale-host.js

@@ -13,7 +13,10 @@
 //
 // ⚠️ It touches `document` and `window` ON PURPOSE and that is why it is `platform/`: this is the layer whose job is the
 // browser. What it must never do is decide anything about language — it receives the locale and the tag already chosen.
-/** What a browser can offer `core/i18n`: the page effects of a change, and the language the person's browser is set to. */
+/**
+ * What a browser can offer a translator: the page effects of a change, the language the person's browser is set to, and
+ * the page's signal that ANOTHER root changed the language (ADR-0232 D3: the language is the page's, and every root follows).
+ */
 export function localeHostHooks(doc, win, applyDom) {
     return {
         applied: (locale, tag) => {
@@ -26,9 +29,17 @@ export function localeHostHooks(doc, win, applyDom) {
         // ⚠️ `navigator` through the window, not the global: a host that hands the engine another window — a second document, an
         // iframe — means that window's language, and reading the global would silently answer for the wrong one.
         preferred: () => win.navigator?.language ?? null,
+        // 📌 On the window the root was GIVEN — its listener scope, so a disposed root stops following (ADR-0220).
+        follow: (react) => {
+            win.addEventListener('i18n:change', (e) => {
+                const locale = e.detail?.locale;
+                if (typeof locale === 'string')
+                    react(locale);
+            });
+        },
     };
 }
-/** Hangs the i18n object on the window for tests and the preview, which is what `core/i18n` used to do to itself. */
+/** Hangs a root's translator on the window for tests and the preview, which is what `core/i18n` used to do to itself. */
 export function exposeI18n(win, i18n) {
     win.__i18n = i18n;
 }

package/dist-pkg/platform/reading-in-worker.d.ts

@@ -37,4 +37,28 @@ export interface ReadingInWorker {
     /** Lets the thread go. A transcription still running answers with the reason instead of never answering. */
     close(): void;
 }
+/** The reading thread of the language being read in, kept between readings; see `keepOneThreadPerLanguage`. */
+export interface ReadingThreads<T extends {
+    close(): void;
+}> {
+    /**
+     * The thread for this language: the one kept when its base language is the same, else a new one from `open` — handed a
+     * `failed` to call when its opening fails. `open` is given at each call because the one form a bundler recognises for the
+     * thread's file has to sit where the host's `Worker` is (ADR-0232 D4), which is the caller's scope and not this module's.
+     */
+    forLanguage(language: string, open: (failed: () => void) => T): T;
+    /** Lets the kept thread go (the game left); the next `forLanguage` opens one again. */
+    close(): void;
+}
+/**
+ * ONE READING THREAD PER LANGUAGE, KEPT (issue #185; ADR-0225 erratum). Opening a thread compiles a model of up to 378 MiB, so a
+ * reading in the language already open reuses its thread, and a reading in another language (a child who switched: `pt-BR` and
+ * `pt-PT` are one model, `pt` and `en` are two) closes the old thread and opens the new one — one compiled model in memory at a
+ * time, which is what a school machine can hold.
+ * 🔴 A THREAD WHOSE OPENING FAILED IS FORGOTTEN: the next reading opens it again — the model may have come down since, and a
+ * thread kept dead would answer every later reading with the first one's failure.
+ */
+export declare function keepOneThreadPerLanguage<T extends {
+    close(): void;
+}>(): ReadingThreads<T>;
 export declare function createReadingInWorker(d: ReadingInWorkerDeps): ReadingInWorker;

package/dist-pkg/platform/reading-in-worker.js

@@ -8,6 +8,44 @@
 // 📌 THE WORKER IS OPENED AT THE FIRST READING AND KEPT, not opened per utterance: opening it means compiling the model again,
 // and the model is up to 378 MiB. It is closed when the engine lets the reading go, so a game that stops listening stops
 // paying for a thread.
+/**
+ * ONE READING THREAD PER LANGUAGE, KEPT (issue #185; ADR-0225 erratum). Opening a thread compiles a model of up to 378 MiB, so a
+ * reading in the language already open reuses its thread, and a reading in another language (a child who switched: `pt-BR` and
+ * `pt-PT` are one model, `pt` and `en` are two) closes the old thread and opens the new one — one compiled model in memory at a
+ * time, which is what a school machine can hold.
+ * 🔴 A THREAD WHOSE OPENING FAILED IS FORGOTTEN: the next reading opens it again — the model may have come down since, and a
+ * thread kept dead would answer every later reading with the first one's failure.
+ */
+export function keepOneThreadPerLanguage() {
+    let kept = null;
+    const baseOf = (tag) => tag.split('-')[0].toLowerCase();
+    return {
+        forLanguage(language, open) {
+            const base = baseOf(language);
+            if (kept?.base === base && kept.thread)
+                return kept.thread;
+            kept?.thread?.close();
+            const mine = { base, thread: null, dead: false };
+            kept = mine;
+            const thread = open(() => {
+                mine.dead = true;
+                if (kept === mine)
+                    kept = null;
+                mine.thread?.close();
+            });
+            if (mine.dead) {
+                thread.close();
+                return thread;
+            } // it failed while opening: answered, and not kept
+            mine.thread = thread;
+            return thread;
+        },
+        close() {
+            kept?.thread?.close();
+            kept = null;
+        },
+    };
+}
 export function createReadingInWorker(d) {
     const worker = d.spawn();
     let nextId = 1;

package/dist-pkg/platform/reading-model.d.ts

@@ -33,6 +33,27 @@ export declare function readingModelFor(language: string): ReadingModelPlan | nu
  * eight decades below the LOUDEST point of this window, not a constant; and the scale ends in (x + 4) / 4.
  */
 export declare function logMel(samples: Float32Array, melFilters: readonly (readonly number[])[]): Float32Array;
+/** The part of a `config.json` that says how a streaming encoder cuts the wave. */
+export interface WaveFrameConfig {
+    readonly encoder_config?: {
+        readonly frame_ms?: number;
+        readonly sample_rate?: number;
+    };
+}
+/**
+ * THE FRAME A STREAMING ENCODER CUTS THE WAVE INTO, in samples: `frame_ms` at `sample_rate`, from the model's own `config.json`
+ * — 5 ms at 16 kHz, 80, for both Moonshines. 1 where the config names no frame: a model without one takes any length.
+ */
+export declare function waveFrameOf(config: WaveFrameConfig): number;
+/**
+ * WHAT MOONSHINE STREAMING'S ENCODER EATS: the wave in WHOLE FRAMES. Its first node reshapes the samples to `[1, -1, 80]`, and
+ * onnxruntime refuses a length that is not a multiple of 80 — 📏 measured on both graphs (issue #185): a microphone hands over
+ * blocks of 4096, which make whole frames only five at a time, so most readings failed. The model's own processor pads with
+ * zeros on the right to a multiple of 80 (`preprocessor_config.json`: `pad_to_multiple_of`, `padding_side`, `padding_value`),
+ * and this is that step: under 5 ms of silence after the child finished, and her wave untouched. An empty recording becomes one
+ * frame of silence, because a graph handed nothing does not run; a wave already in whole frames is handed on as it came.
+ */
+export declare function inWholeFrames(samples: Float32Array, frame: number): Float32Array;
 /** A `tokenizer.json`, in the parts a reading reads: the vocabulary, the added tokens, and which decoder undoes them. */
 export interface TokenizerFile {
     readonly model?: {

package/dist-pkg/platform/reading-model.js

@@ -14,6 +14,7 @@
 // · THE MEL FILTERS ARE NOT COMPUTED HERE. Whisper's own `preprocessor_config.json` carries them (80 × 201), which is most of its
 //   185 KB, and the catalogue already fetches it: a filterbank rebuilt from a formula is a second opinion about the model's input.
 // · Moonshine takes the WAVEFORM. No spectrogram, no padding to 30 s — it is a different front end, not a variant of this one.
+//   ⚠️ But the streaming encoder takes it in WHOLE FRAMES of 5 ms (80 samples), and refuses any other length: `inWholeFrames`.
 /** 16 kHz mono, for every one of them: it is what all three were trained on, and resampling is the caller's job. */
 export const READING_RATE = 16_000;
 /** Whisper reads a 30 s window at a time, always: shorter is padded with silence, longer is cut. */
@@ -95,6 +96,30 @@ export function logMel(samples, melFilters) {
         out[i] = (Math.max(out[i], floor) + 4) / 4;
     return out;
 }
+/**
+ * THE FRAME A STREAMING ENCODER CUTS THE WAVE INTO, in samples: `frame_ms` at `sample_rate`, from the model's own `config.json`
+ * — 5 ms at 16 kHz, 80, for both Moonshines. 1 where the config names no frame: a model without one takes any length.
+ */
+export function waveFrameOf(config) {
+    const { frame_ms: ms, sample_rate: rate } = config.encoder_config ?? {};
+    return ms && rate ? Math.round((ms * rate) / 1000) : 1;
+}
+/**
+ * WHAT MOONSHINE STREAMING'S ENCODER EATS: the wave in WHOLE FRAMES. Its first node reshapes the samples to `[1, -1, 80]`, and
+ * onnxruntime refuses a length that is not a multiple of 80 — 📏 measured on both graphs (issue #185): a microphone hands over
+ * blocks of 4096, which make whole frames only five at a time, so most readings failed. The model's own processor pads with
+ * zeros on the right to a multiple of 80 (`preprocessor_config.json`: `pad_to_multiple_of`, `padding_side`, `padding_value`),
+ * and this is that step: under 5 ms of silence after the child finished, and her wave untouched. An empty recording becomes one
+ * frame of silence, because a graph handed nothing does not run; a wave already in whole frames is handed on as it came.
+ */
+export function inWholeFrames(samples, frame) {
+    const whole = Math.max(1, Math.ceil(samples.length / frame)) * frame;
+    if (whole === samples.length)
+        return samples;
+    const out = new Float32Array(whole);
+    out.set(samples);
+    return out;
+}
 /** A PERIODIC Hann window: a symmetric one moves every value. 400 numbers, computed once. */
 const HANN = Float64Array.from({ length: N_FFT }, (_, i) => 0.5 - 0.5 * Math.cos((2 * Math.PI * i) / N_FFT));
 /**

package/dist-pkg/platform/reading-runtime.js

@@ -9,14 +9,15 @@
 // THREE FAMILIES, and they differ in ways that matter:
 // · Whisper (pt) eats a log-mel spectrogram and opens with four tokens — «transcribe, in Portuguese, without timestamps» — and
 //   refuses 88 tokens that are not speech. Without that opening it answers in whatever language it feels like.
-// · Moonshine (es) eats the waveform and opens with one token, in two decoder graphs like Whisper's.
+// · Moonshine (es) eats the waveform, in whole frames of the length its config names, and opens with one token, in two decoder
+//   graphs like Whisper's.
 // · Moonshine (en) is the same model with ONE MERGED decoder graph, told which pass it is on by `use_cache_branch` and fed empty
 //   caches on the first. It is the shape most easily written wrong from a guess, which is why it is traced too.
 //
 // ⚠️ THE CROSS-ATTENTION CACHE IS COMPUTED ONCE AND NEVER AGAIN. The first pass answers a `present.*.encoder.*` per layer that
 // depends only on the sound; feeding back the new one each step is how a loop gets slower with every token AND drifts.
 import { atDelivery, loadOnnxRuntime } from './onnx-runtime.js';
-import { logMel, nextToken, readingModelFor, readingTextOf, suppressedTokens, tokenIdOf, WHISPER_BANDS, WHISPER_FRAMES, } from './reading-model.js';
+import { inWholeFrames, logMel, nextToken, readingModelFor, readingTextOf, suppressedTokens, tokenIdOf, waveFrameOf, WHISPER_BANDS, WHISPER_FRAMES, } from './reading-model.js';
 const MAX_TOKENS = 200;
 export async function loadReadingRuntime(d) {
     const plan = readingModelFor(d.language);
@@ -53,9 +54,10 @@ export async function loadReadingRuntime(d) {
     const eos = generation.eos_token_id ?? -1;
     const { heads, width } = cacheSizeOf(config);
     const ceiling = d.maxTokens ?? MAX_TOKENS;
+    const frame = waveFrameOf(config);
     return {
         async transcribe(samples) {
-            const encoded = await encoder.run(soundFor(ort, plan, samples, melFilters));
+            const encoded = await encoder.run(soundFor(ort, plan, samples, melFilters, frame));
             const hidden = encoded[encoder.outputNames[0]];
             const shape = {
                 ort, start, hidden, heads, width,
@@ -82,12 +84,15 @@ export async function loadReadingRuntime(d) {
 }
 /**
  * WHAT THE ENCODER HEARS. Whisper a log-mel picture of 30 s drawn with the model's own filters (80 bands × 3000 frames), Moonshine
- * the wave itself, every sample. The names are the graphs' own: a real session refuses any other.
+ * the wave itself, every sample, filled with silence to the whole frames its encoder cuts (`inWholeFrames`) — the microphone's
+ * length is not the model's. The names are the graphs' own: a real session refuses any other.
  */
-function soundFor(ort, plan, samples, melFilters) {
-    return plan.input === 'log-mel'
-        ? { input_features: new ort.Tensor('float32', logMel(samples, melFilters ?? []), [1, WHISPER_BANDS, WHISPER_FRAMES]) }
-        : { input_values: new ort.Tensor('float32', samples, [1, samples.length]) };
+function soundFor(ort, plan, samples, melFilters, frame) {
+    if (plan.input === 'log-mel') {
+        return { input_features: new ort.Tensor('float32', logMel(samples, melFilters ?? []), [1, WHISPER_BANDS, WHISPER_FRAMES]) };
+    }
+    const wave = inWholeFrames(samples, frame);
+    return { input_values: new ort.Tensor('float32', wave, [1, wave.length]) };
 }
 /** What one decoder step is handed: the opening on the first, then only the newest token, and the caches so far. */
 function stepInputs(shape, session, first, ids, past) {

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

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { recognitionRoute, type RecognitionApi, type OnDeviceAvailability, type RecognitionInstance } from './speech-recognition.js';
+import type { VoiceChooser, ChooseSettings, ChoiceHeard } from './choose-by-voice.js';
 /** The browser's recognition object, with the parts a reading uses. Assigned handlers, as the API has them. */
 export interface ListeningSession extends RecognitionInstance {
     start(): void;
@@ -48,6 +49,11 @@ export interface ReadingDeps {
     readonly record?: (options: ListenOptions) => Promise<Float32Array>;
     readonly route?: typeof recognitionRoute;
     readonly createSession?: (api: RecognitionApi, language: string) => ListeningSession;
+    /**
+     * The closed-grammar recogniser a choice among shown options is heard by (`platform/choose-by-voice`, ADR-0256). Absent: a
+     * choice is REFUSED with its reason, like a reading with nothing to hear it.
+     */
+    readonly chooser?: VoiceChooser;
 }
 export interface ListenOptions {
     /** How long a silence ends the reading. Default 1.5 s: shorter cuts a child who is thinking between words. */
@@ -58,7 +64,12 @@ export interface ListenOptions {
 export interface Reading {
     /** Listens until the child goes quiet, and answers with what was read. */
     listen(options?: ListenOptions): Promise<Heard>;
-    /** Gives the microphone back now; the reading in hand answers with what it has. */
+    /**
+     * THE CHILD SAYS ONE OF THE OPTIONS THE GAME SHOWS (ADR-0256): pass them as written, get back which one was said — heard by a
+     * recogniser that can only answer with one of them. For choosing; `listen()` is for reading aloud.
+     */
+    choose(options: readonly string[], settings?: ChooseSettings): Promise<ChoiceHeard>;
+    /** Gives the microphone back now; the reading or the choice in hand answers with what it has. */
     stop(): void;
     /** Can this device serve the child's language at all? Answers with the reason when it cannot. */
     ready(): Promise<{

package/dist-pkg/platform/reading.js

@@ -92,7 +92,15 @@ export function createReading(d) {
     }
     return {
         ready,
-        stop() { askToStop?.('asked'); },
+        stop() { askToStop?.('asked'); d.chooser?.stop(); },
+        async choose(options, settings) {
+            if (!d.chooser) {
+                once('sem-escolha', 'choosing by voice: nothing on this device hears a choice among options — the child answers with the '
+                    + 'arrows only; the engine lends a chooser where it can open the command recogniser (ADR-0256)');
+                throw new Error('choosing by voice is not available here');
+            }
+            return d.chooser.choose(options, settings);
+        },
         async listen(options = {}) {
             if (inFlight)
                 return inFlight; // one microphone, one reading: the second caller waits on the first

package/dist-pkg/platform/speech-recognition.d.ts

@@ -37,7 +37,11 @@ export type HeardCommand = {
     readonly kind: 'item';
     readonly name: string;
 };
-/** How a heard text is compared: lower case, letters and spaces only. */
+/**
+ * A name or a heard text as a recogniser writes it: lower case, letters, digits and single spaces — and the ACCENTS KEPT, because
+ * a closed grammar word spelled without them is not in the model's vocabulary and is dropped (`input/voice-map`, «ação»).
+ * The digit stays so «Jogador 1» and «Jogador 2» never collapse into one name.
+ */
 export declare const spokenText: (t: string) => string;
 export interface CommandReader {
     /** The menu's item names now on screen (already as spoken). */
@@ -48,4 +52,9 @@ export interface CommandReader {
      */
     read(index: number, text: string, final: boolean): readonly HeardCommand[];
 }
+/**
+ * What two spoken forms are COMPARED by: `spokenText` without its accents. The grammar asks the model for «ação» (it would drop
+ * «acao»), but a recogniser that writes «acao» back — or a browser recogniser with no closed vocabulary — still said «ação».
+ */
+export declare const compareKey: (t: string) => string;
 export declare function createCommandReader(vocabulary: readonly string[]): CommandReader;

package/dist-pkg/platform/speech-recognition.js

@@ -37,20 +37,39 @@ export function createOnDeviceRecognition(api, language) {
     rec.interimResults = true;
     return rec;
 }
-/** How a heard text is compared: lower case, letters and spaces only. */
-export const spokenText = (t) => t.toLowerCase().normalize('NFC').replace(/[^\p{L}\s]/gu, ' ').replace(/\s+/g, ' ').trim();
+/**
+ * A name or a heard text as a recogniser writes it: lower case, letters, digits and single spaces — and the ACCENTS KEPT, because
+ * a closed grammar word spelled without them is not in the model's vocabulary and is dropped (`input/voice-map`, «ação»).
+ * The digit stays so «Jogador 1» and «Jogador 2» never collapse into one name.
+ */
+export const spokenText = (t) => t.toLowerCase().normalize('NFC').replace(/[^\p{L}\p{N}\s]/gu, ' ').replace(/\s+/g, ' ').trim();
+/**
+ * What two spoken forms are COMPARED by: `spokenText` without its accents. The grammar asks the model for «ação» (it would drop
+ * «acao»), but a recogniser that writes «acao» back — or a browser recogniser with no closed vocabulary — still said «ação».
+ */
+export const compareKey = (t) => spokenText(t).normalize('NFD').replace(/\p{M}/gu, '');
+/** The phrases a reader knows, by comparison key → the spoken form it answers with (the first one to claim the key). */
+function byKey(phrases) {
+    const m = new Map();
+    for (const p of phrases) {
+        const k = compareKey(p);
+        if (k && !m.has(k))
+            m.set(k, spokenText(p));
+    }
+    return m;
+}
 export function createCommandReader(vocabulary) {
-    const spokenForms = vocabulary.map(spokenText);
-    let spokenItems = [];
+    const words = byKey(vocabulary);
+    let items = new Map();
     const firedCount = new Map();
     const phrasesIn = (text) => {
-        const p = spokenText(text).split(' ').filter(Boolean);
+        const p = compareKey(text).split(' ').filter(Boolean);
         const found = [];
         for (let i = 0; i < p.length;) {
             let matched = null;
             for (let n = p.length - i; n >= 1; n--) {
                 const f = p.slice(i, i + n).join(' ');
-                if (spokenItems.includes(f) || spokenForms.includes(f)) {
+                if (items.has(f) || words.has(f)) {
                     matched = f;
                     i += n;
                     break;
@@ -64,16 +83,17 @@ export function createCommandReader(vocabulary) {
         return found;
     };
     return {
-        items(names) { spokenItems = names.map(spokenText); },
+        items(names) { items = byKey(names); },
         read(index, text, final) {
             const found = phrasesIn(text);
             const alreadyFired = firedCount.get(index) ?? 0;
             const newCommands = [];
             for (let i = alreadyFired; i < found.length; i++) {
                 const f = found[i];
-                if (!final && i === found.length - 1 && spokenItems.some((o) => o !== f && o.startsWith(f + ' ')))
+                if (!final && i === found.length - 1 && [...items.keys()].some((o) => o !== f && o.startsWith(f + ' ')))
                     break;
-                newCommands.push(spokenItems.includes(f) ? { kind: 'item', name: f } : { kind: 'palavra', word: f });
+                const item = items.get(f);
+                newCommands.push(item !== undefined ? { kind: 'item', name: item } : { kind: 'palavra', word: words.get(f) });
                 firedCount.set(index, i + 1);
             }
             if (final)

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

@@ -12,4 +12,13 @@ export interface GameVoice extends SpeechPort {
     soundOn(): boolean;
     volume(): number;
 }
-export declare function gameSay(voice: GameVoice, text: string): void;
+/**
+ * Says `text`, a word the game gives in `language` (BCP-47), with a voice of that language chosen by the rule narration's parts
+ * use (ADR-0243 §2): the exact tag, else a voice of the same language. REQUIRED, because an optional language would default to
+ * one, and that default — pt-BR whatever the page said — is what ADR-0243 §4 removed.
+ *
+ * 🔴 A DEVICE THAT LISTS VOICES AND NONE OF THE LANGUAGE says nothing (§3): a wrong accent is learned. A device that lists NONE
+ * yet — the browser fills the list late — is asked by the tag alone, and it picks its own voice for the language.
+ * Volume ×1.4 so the speech sits above the effects, capped at 1.
+ */
+export declare function gameSay(voice: GameVoice, text: string, language: string): void;

package/dist-pkg/platform/speech.js

@@ -1,21 +1,28 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// platform/speech.ts — the LITERACY voice (gameSay): pt-BR speech that is ALWAYS on (independent of the mixer's
-// narration toggle), through the browser's native voice. It picks a pt-BR voice and avoids pt-PT. A helper that holds nothing:
-// it takes the browser's speech and the master sound as a parameter (ADR-0232 D4, erratum D3 point 2).
+// platform/speech.ts — the LITERACY voice (gameSay): speech that is ALWAYS on (independent of the mixer's narration toggle),
+// through the browser's native voice, in the language the game says its words are in (ADR-0243 §4). A helper that holds
+// nothing: it takes the browser's speech and the master sound as a parameter (ADR-0232 D4, erratum D3 point 2).
 // The MENU's TTS (narrate/ttsSpeak and the Kokoro neural engine) is another path, gated by the mixer — `platform/tts`.
-function ptbrVoice(ss) {
+import { voiceOfLanguage } from './voice-plan.js';
+/** The device's voices, or none where the browser has not listed them yet or throws. */
+function listedVoices(ss) {
     try {
-        const vs = ss.getVoices() || [];
-        if (!vs.length)
-            return null;
-        return vs.find((v) => /pt[-_]?br/i.test(v.lang)) || vs.find((v) => /pt/i.test(v.lang) && /bras|brazil/i.test(v.name)) || vs.find((v) => /pt/i.test(v.lang) && !/pt[-_]?pt/i.test(v.lang)) || null;
+        return ss.getVoices() || [];
     }
     catch (e) {
-        return null;
+        return [];
     }
 }
-// FORCES pt-BR (not the mixer's voice, which may be pt-PT). Volume ×1.4 so the speech sits above the effects.
-export function gameSay(voice, text) {
+/**
+ * Says `text`, a word the game gives in `language` (BCP-47), with a voice of that language chosen by the rule narration's parts
+ * use (ADR-0243 §2): the exact tag, else a voice of the same language. REQUIRED, because an optional language would default to
+ * one, and that default — pt-BR whatever the page said — is what ADR-0243 §4 removed.
+ *
+ * 🔴 A DEVICE THAT LISTS VOICES AND NONE OF THE LANGUAGE says nothing (§3): a wrong accent is learned. A device that lists NONE
+ * yet — the browser fills the list late — is asked by the tag alone, and it picks its own voice for the language.
+ * Volume ×1.4 so the speech sits above the effects, capped at 1.
+ */
+export function gameSay(voice, text, language) {
     if (!text || !voice.soundOn())
         return;
     try {
@@ -23,9 +30,13 @@ export function gameSay(voice, text) {
         if (!ss)
             return;
         ss.cancel();
+        const listed = listedVoices(ss);
+        const own = voiceOfLanguage(language, listed.map((v) => ({ locale: v.lang.replace('_', '-'), engine: 'webspeech', voice: v.name })));
+        if (listed.length && !own)
+            return;
         const u = voice.utterance(text);
-        u.lang = 'pt-BR';
-        const v = ptbrVoice(ss);
+        u.lang = language;
+        const v = listed.find((x) => x.name === own?.voice);
         if (v)
             u.voice = v;
         u.volume = Math.min(1, voice.volume() * 1.4);