@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -0,0 +1,164 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/reading-runtime — THE READING, RUN (ADR-0216 §2; issues #185, #200): sound in, the child's words out.
+//
+// The model of the child's language is opened from the delivery (`heavy/` on the page's own origin, ADR-0177) and run here:
+// the encoder once, then the decoder token by token until it says it is done. What each graph is called, what it takes and what
+// comes back is not guessed — `scratchpad/leitura-de-referencia-3.py` ran the real files and its trace is what
+// `tests/reading-runtime.node.test.js` replays.
+//
+// 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, 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 { 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);
+    if (!plan)
+        throw new Error(`reading: the project has no model for ${d.language}`);
+    const get = d.fetch;
+    const ort = d.ort ?? await loadOnnxRuntime({ base: d.base, importModule: d.importModule });
+    const asJson = async (id) => {
+        const r = await get(atDelivery(id, d.base));
+        if (!r.ok)
+            throw new Error(`reading: HTTP ${r.status} for ${id} — the delivery does not carry this language's model`);
+        return await r.json();
+    };
+    const asSession = async (id) => {
+        const r = await get(atDelivery(id, d.base));
+        if (!r.ok)
+            throw new Error(`reading: HTTP ${r.status} for ${id} — the delivery does not carry this language's model`);
+        return ort.InferenceSession.create(new Uint8Array(await r.arrayBuffer()), { executionProviders: ['wasm'] });
+    };
+    const [tokenizer, generation, config] = await Promise.all([
+        asJson(plan.tokenizer),
+        asJson(plan.generation),
+        asJson(plan.config),
+    ]);
+    const melFilters = plan.input === 'log-mel' && plan.preprocessor
+        ? (await asJson(plan.preprocessor)).mel_filters
+        : null;
+    const [encoder, decoder, decoderPast] = await Promise.all([
+        asSession(plan.encoder),
+        asSession(plan.decoder),
+        plan.decoderPast ? asSession(plan.decoderPast) : Promise.resolve(null),
+    ]);
+    const start = openingOf(plan, tokenizer, generation);
+    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, frame));
+            const hidden = encoded[encoder.outputNames[0]];
+            const shape = {
+                ort, start, hidden, heads, width,
+                frames: hidden.dims?.[1] ?? 0,
+                // the merged graph wants the caches present and EMPTY on the first pass, and the flag that says which pass this is
+                merged: !decoderPast,
+            };
+            const past = {};
+            const ids = [];
+            for (let step = 0; step < ceiling; step++) {
+                const first = step === 0;
+                const session = first || shape.merged ? decoder : decoderPast;
+                const answered = await session.run(stepInputs(shape, session, first, ids, past));
+                keepPast(past, session, answered, first);
+                const chosen = nextToken(lastLogits(answered[session.outputNames[0]]), suppressedTokens(generation, first));
+                // no token at all (a row of NaN) is an end, like the end-of-text: pushing it would ask for a word the vocabulary lacks
+                if (chosen < 0 || chosen === eos)
+                    break;
+                ids.push(chosen);
+            }
+            return readingTextOf(tokenizer, ids).trim();
+        },
+    };
+}
+/**
+ * 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, 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, 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) {
+    const { ort } = shape;
+    const inputIds = first ? shape.start : [ids[ids.length - 1]];
+    const inputs = {
+        input_ids: new ort.Tensor('int64', BigInt64Array.from(inputIds, BigInt), [1, inputIds.length]),
+        encoder_hidden_states: shape.hidden,
+        ...(first && shape.merged ? emptyCaches(ort, session, shape.heads, shape.width, shape.frames) : past),
+    };
+    if (shape.merged)
+        inputs.use_cache_branch = new ort.Tensor('bool', Uint8Array.of(first ? 0 : 1), [1]);
+    return inputs;
+}
+/**
+ * The caches carried to the next step: each `present.*` the decoder answered, renamed to the `past_key_values.*` it takes. The
+ * `logits` beside them are the answer, never a cache.
+ * ⚠️ ONLY the self-attention half grows. The cross-attention half is the sound, and the sound does not change.
+ */
+function keepPast(past, session, answered, first) {
+    for (const name of session.outputNames) {
+        if (!name.startsWith('present.'))
+            continue;
+        if (first || name.includes('.decoder.'))
+            past[name.replace('present.', 'past_key_values.')] = answered[name];
+    }
+}
+/**
+ * HOW THE DECODER IS TOLD WHAT TO DO. Moonshine opens with one token and reads what it hears. Whisper opens with four, and they
+ * are an instruction: transcribe (not translate), in THIS language, without timestamps. 📏 Measured: without them it answers in
+ * whatever language it decides, and with `<|translate|>` it answers in English — a child reading Portuguese would be corrected
+ * against an English transcript.
+ */
+function openingOf(plan, tokenizer, generation) {
+    const first = generation.decoder_start_token_id ?? 0;
+    if (plan.input !== 'log-mel')
+        return [first];
+    const named = [`<|${plan.language}|>`, '<|transcribe|>', '<|notimestamps|>'].map((c) => tokenIdOf(tokenizer, c));
+    if (named.some((id) => id === null))
+        throw new Error(`reading: this model has no token for ${plan.language} transcription`);
+    return [first, ...named];
+}
+/**
+ * How big one cache is, from `config.json`: the KEY-VALUE heads (a model with grouped attention keeps fewer than it attends with),
+ * and a width of `hidden_size / heads`, 64 where the config does not say.
+ */
+function cacheSizeOf(config) {
+    return {
+        heads: config.num_key_value_heads ?? config.num_attention_heads ?? 0,
+        width: config.hidden_size && config.num_attention_heads ? config.hidden_size / config.num_attention_heads : 64,
+    };
+}
+/** The caches a merged decoder wants on its first pass: the self-attention halves empty, the cross-attention ones the sound's. */
+function emptyCaches(ort, session, heads, width, frames) {
+    const out = {};
+    for (const name of session.inputNames ?? []) {
+        if (!name.startsWith('past_key_values.'))
+            continue;
+        const length = name.includes('.decoder.') ? 0 : frames;
+        out[name] = new ort.Tensor('float32', new Float32Array(heads * length * width), [1, heads, length, width]);
+    }
+    return out;
+}
+/** The logits of the LAST position: the decoder answers one row per token it was given, and only the newest one is a choice. */
+function lastLogits(tensor) {
+    const t = tensor;
+    const vocab = t.dims?.[2] ?? t.data.length;
+    return t.data.subarray(t.data.length - vocab);
+}

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

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { loadReadingRuntime } from './reading-runtime.js';
+/** What the client asks for. */
+export type ReadingRequest = {
+    readonly kind: 'load';
+    readonly base: string;
+    readonly language: string;
+} | {
+    readonly kind: 'transcribe';
+    readonly id: number;
+    readonly samples: Float32Array;
+};
+/** What the worker answers. `id` is absent only on the answer to `load`, which nobody can ask twice. */
+export type ReadingAnswer = {
+    readonly kind: 'ready';
+} | {
+    readonly kind: 'text';
+    readonly id: number;
+    readonly text: string;
+} | {
+    readonly kind: 'failed';
+    readonly id?: number;
+    readonly message: string;
+};
+/** The side of the conversation this file needs, so a gate can run the whole protocol without a thread. */
+export interface WorkerScope {
+    onmessage: ((event: {
+        data: ReadingRequest;
+    }) => void) | null;
+    postMessage(answer: ReadingAnswer): void;
+    /**
+     * The worker realm's own `fetch`, which the model's files are fetched with (ADR-0232 D4): the runtime receives it from the
+     * scope, so the worker's entry reaches no bare global either.
+     */
+    fetch(url: string): Promise<Response>;
+}
+/**
+ * Wires the protocol onto a scope. Exported — and not only run at import — so the gate exercises the REAL handler instead of a
+ * copy of it written in the test, which is the difference between measuring the protocol and measuring a description of it.
+ */
+export declare function serveReading(scope: WorkerScope, load?: typeof loadReadingRuntime): void;

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

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/reading-worker — THE TRANSCRIPTION, OFF THE MAIN THREAD (ADR-0216 §2; issue #185).
+//
+// 🔴 WHY A THREAD OF ITS OWN, and it is measured and not hygiene: `platform/reading-runtime` runs an encoder and then a decoder
+// token by token, each one a wasm call of tens of milliseconds. On the main thread that is the thread that also draws the game
+// and feeds the microphone — 📏 measured in the lab, Whisper transcribing on the main thread CUT THE AUDIO IN GAPS OF 4 s; the
+// same work in a worker left a biggest gap of 264 ms. A child who reads aloud while the page transcribes loses the words she
+// said during the pause, and nothing anywhere says so.
+//
+// The protocol is three messages and no state the caller cannot see:
+//   · `{ kind: 'load', base, language }`      → `{ kind: 'ready' }` or `{ kind: 'failed', message }`
+//   · `{ kind: 'transcribe', id, samples }`   → `{ kind: 'text', id, text }` or `{ kind: 'failed', id, message }`
+// Every answer carries the `id` of the question, because a second reading may be asked for while the first is still running and
+// an answer that cannot be matched to its question is an answer given to the wrong child.
+//
+// ⚠️ THE MODEL IS OPENED HERE, INSIDE THE WORKER, and that is the whole point: `loadReadingRuntime` fetches the graphs from the
+// delivery and the ONNX runtime compiles them. Doing that on the main thread freezes the game for as long as it takes to open
+// 378 MiB of model, which is the other half of the defect this file exists to remove.
+import { loadReadingRuntime } from './reading-runtime.js';
+const reason = (e) => (e instanceof Error ? e.message : String(e));
+/**
+ * Wires the protocol onto a scope. Exported — and not only run at import — so the gate exercises the REAL handler instead of a
+ * copy of it written in the test, which is the difference between measuring the protocol and measuring a description of it.
+ */
+export function serveReading(scope, load = loadReadingRuntime) {
+    let transcriber = null;
+    scope.onmessage = (event) => {
+        const msg = event.data;
+        if (msg.kind === 'load') {
+            void (async () => {
+                try {
+                    // a METHOD call on the scope: `fetch` detached from its realm throws «Illegal invocation»
+                    transcriber = await load({ base: msg.base, language: msg.language, fetch: (url) => scope.fetch(url) });
+                    scope.postMessage({ kind: 'ready' });
+                }
+                catch (e) {
+                    scope.postMessage({ kind: 'failed', message: reason(e) });
+                }
+            })();
+            return;
+        }
+        // ⚠️ A REQUEST BEFORE THE MODEL IS OPEN IS ANSWERED, not dropped: a dropped message leaves the caller's promise pending for
+        // ever, and a child waiting for words that will never come has no way to know she should try again.
+        void (async () => {
+            try {
+                if (!transcriber)
+                    throw new Error('reading worker: asked to transcribe before the model was opened');
+                scope.postMessage({ kind: 'text', id: msg.id, text: await transcriber.transcribe(msg.samples) });
+            }
+            catch (e) {
+                scope.postMessage({ kind: 'failed', id: msg.id, message: reason(e) });
+            }
+        })();
+    };
+}
+if (typeof WorkerGlobalScope !== 'undefined' && typeof self !== 'undefined' && self instanceof WorkerGlobalScope) {
+    serveReading(self);
+}

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

@@ -0,0 +1,80 @@
+// 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;
+    stop(): void;
+    onresult: ((ev: {
+        readonly results: ArrayLike<ArrayLike<{
+            readonly transcript: string;
+        }> & {
+            readonly isFinal: boolean;
+        }>;
+    }) => void) | null;
+    onerror: ((ev: {
+        readonly error?: string;
+    }) => void) | null;
+    onend: (() => void) | null;
+}
+/** What a reading gives back. `route` is which recogniser heard it — for `problems` and for a lab, never for the game's logic. */
+export interface Heard {
+    readonly text: string;
+    readonly route: 'webspeech-local' | 'model';
+    /** The reading stopped because the child went quiet, because the time ran out, or because someone asked it to stop. */
+    readonly ended: 'silence' | 'timeout' | 'asked';
+}
+export interface ReadingDeps {
+    /** The BCP-47 tag of the child's language (`core/i18n.bcp47`). */
+    readonly language: () => string;
+    /** The browser's `SpeechRecognition` constructor, or nothing where there is none. */
+    readonly api?: RecognitionApi | null;
+    readonly now: () => number;
+    readonly every: (fn: () => void, ms: number) => unknown;
+    readonly stopEvery: (h: unknown) => void;
+    /** A line for `problems`, written once per reason (ADR-0169). */
+    readonly report: (line: string) => void;
+    /**
+     * The engine's own recogniser, when there is one to load — the models of ADR-0201, lazily (`platform/reading-runtime`).
+     * Absent: the refusal below.
+     */
+    readonly model?: (language: string) => Promise<{
+        transcribe(samples: Float32Array): Promise<string>;
+    }>;
+    /**
+     * The microphone, as 16 kHz mono samples. The model route needs sound, and the browser route does not: the browser's own
+     * recogniser opens the microphone itself. ⚠️ Absent with a model present is a reading that REFUSES and says which half is
+     * missing — never one that answers an empty sentence, which a game would show a child as «you read nothing».
+     */
+    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. */
+    readonly silenceMs?: number;
+    /** The ceiling, so a forgotten microphone does not listen for ever. Default 30 s, the window Whisper reads at once. */
+    readonly maxMs?: number;
+}
+export interface Reading {
+    /** Listens until the child goes quiet, and answers with what was read. */
+    listen(options?: ListenOptions): Promise<Heard>;
+    /**
+     * 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<{
+        readonly can: boolean;
+        readonly why: OnDeviceAvailability | 'sem-api' | 'sem-processamento-local' | 'no-model';
+    }>;
+}
+export declare function createReading(d: ReadingDeps): Reading;

package/dist-pkg/platform/reading.js

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/reading — THE CHILD READS ALOUD, AND THE GAME RECEIVES TEXT (ADR-0216, issue #200).
+//
+// The Dev, 2026-09-21: «a engine deve oferecer objetos de leitura e TTS. O jogo não deve precisar saber como isso funciona, apenas
+// deve pedir para ouvir e receber o texto.» So this module answers ONE question — what did the child say — and keeps the rest:
+// which recogniser heard it, in which language, and whether it may run at all.
+//
+// · ON THE DEVICE OR NOT AT ALL (ADR-0200 erratum). The browser's recogniser is used only where it says it recognises on the device
+//   AND the language is installed there (`platform/speech-recognition`). Anything else waits for the models the project carries
+//   (Whisper for pt, Moonshine for en and es — ADR-0201), which arrive through `engine` below and are not built yet: until then a
+//   request is REFUSED with its reason, never answered by a recogniser that would send a child's voice to a server.
+// · A reading ends when the child stops talking (`silenceMs`) or when the time runs out (`maxMs`), whichever comes first, and what
+//   was heard so far is what the game gets — a child who stops mid-sentence is not an error.
+// · Asking twice does not open two microphones: the second caller waits on the same reading.
+import { recognitionRoute, createOnDeviceRecognition } from './speech-recognition.js';
+const SILENCE_MS = 1500;
+const MAX_MS = 30_000;
+export function createReading(d) {
+    const routeOf = d.route ?? recognitionRoute;
+    const make = d.createSession ?? ((api, language) => createOnDeviceRecognition(api, language));
+    const said = new Set();
+    const once = (key, line) => { if (!said.has(key)) {
+        said.add(key);
+        d.report(line);
+    } };
+    let inFlight = null;
+    let askToStop = null;
+    async function ready() {
+        const { route: route, status: state } = await routeOf(d.language(), d.api);
+        if (route === 'webspeech-local')
+            return { can: true, why: state };
+        return { can: !!d.model, why: d.model ? state : 'no-model' };
+    }
+    function byBrowser(api, options) {
+        const silenceMs = options.silenceMs ?? SILENCE_MS;
+        const maxMs = options.maxMs ?? MAX_MS;
+        return new Promise((resolve, reject) => {
+            let session;
+            try {
+                session = make(api, d.language());
+            }
+            catch (e) {
+                reject(e instanceof Error ? e : new Error(String(e)));
+                return;
+            }
+            let text = '', lastSound = d.now(), done = false;
+            const ticker = d.every(() => {
+                if (done)
+                    return;
+                const quietFor = d.now() - lastSound;
+                if (quietFor >= silenceMs && text)
+                    finish('silence');
+                else if (d.now() - startedAt >= maxMs)
+                    finish('timeout');
+            }, 100);
+            const startedAt = d.now();
+            const finish = (ended) => {
+                if (done)
+                    return;
+                done = true;
+                d.stopEvery(ticker);
+                askToStop = null;
+                try {
+                    session.stop();
+                }
+                catch { /* a session that already ended is not a failure */ }
+                resolve({ text: text.trim(), route: 'webspeech-local', ended });
+            };
+            askToStop = () => finish('asked');
+            session.onresult = (ev) => {
+                let together = '';
+                for (let i = 0; i < ev.results.length; i++)
+                    together += `${ev.results[i][0].transcript} `;
+                text = together;
+                lastSound = d.now();
+            };
+            session.onerror = (ev) => {
+                // ⚠️ A refusal is not a silence: a child waiting to be heard must not wait for ever, and the adult must read why.
+                once('error', `reading: the browser's recogniser stopped (${ev.error ?? 'unknown'}) — the child reads and nothing is heard; `
+                    + 'allow the microphone for this page, or install the language on the device');
+                if (!done) {
+                    done = true;
+                    d.stopEvery(ticker);
+                    askToStop = null;
+                    reject(new Error(ev.error ?? 'recognition failed'));
+                }
+            };
+            session.onend = () => { if (!done)
+                finish(text ? 'silence' : 'asked'); };
+            session.start();
+        });
+    }
+    return {
+        ready,
+        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
+            const { route: route, status: state } = await routeOf(d.language(), d.api);
+            if (route !== 'webspeech-local') {
+                if (!d.model) {
+                    once('sem-route', `reading: nothing on this device can hear ${d.language()} (${state}) — the child's reading is not assessed; `
+                        + 'install the language in the browser, or build a delivery that carries the reading model for this language');
+                    throw new Error(`reading is not available here: ${state}`);
+                }
+                if (!d.record) {
+                    once('sem-microfone', `reading: the model for ${d.language()} is here and nothing captures the child's voice — `
+                        + 'the reading cannot run; pass `record`, the 16 kHz samples the model reads');
+                    throw new Error('reading has no microphone here');
+                }
+                const capture = d.record;
+                inFlight = (async () => {
+                    const [transcriber, samples] = await Promise.all([d.model(d.language()), capture(options)]);
+                    return { text: (await transcriber.transcribe(samples)).trim(), route: 'model', ended: 'silence' };
+                })();
+            }
+            else {
+                inFlight = byBrowser(d.api, options);
+            }
+            try {
+                return await inFlight;
+            }
+            finally {
+                inFlight = null;
+            }
+        },
+    };
+}

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

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** What the browser answers about recognising a language on the device (Chrome's `SpeechRecognition.available`). */
+export type OnDeviceAvailability = 'available' | 'downloadable' | 'downloading' | 'unavailable';
+/** The part of the browser's `SpeechRecognition` constructor this module reads. */
+export interface RecognitionApi {
+    new (): RecognitionInstance;
+    readonly prototype: object;
+    readonly available?: (options: {
+        langs: readonly string[];
+        processLocally: boolean;
+    }) => Promise<OnDeviceAvailability>;
+}
+export interface RecognitionInstance {
+    lang: string;
+    processLocally?: boolean;
+    continuous: boolean;
+    interimResults: boolean;
+}
+export interface RecognitionRoute {
+    /** `webspeech-local`: the browser recognises on the device. `recuo`: the engine's own recogniser. */
+    readonly route: 'webspeech-local' | 'recuo';
+    /** Why: the browser's answer, or what is missing. */
+    readonly status: OnDeviceAvailability | 'sem-api' | 'sem-processamento-local';
+}
+/**
+ * THE ROUTE, measured on the device (ADR-0200 §3). ⚠️ A browser whose recognition object has no `processLocally` would take the
+ * flag as an unknown property and recognise on its servers — it is never the route, whatever it says about availability.
+ */
+export declare function recognitionRoute(language: string, api: RecognitionApi | null | undefined): Promise<RecognitionRoute>;
+/** A recognition object set to recognise on the device, continuously, with partial hypotheses. Refuses a browser that cannot. */
+export declare function createOnDeviceRecognition(api: RecognitionApi, language: string): RecognitionInstance;
+/** A command heard: a direction word, or the name of an item of the open menu. */
+export type HeardCommand = {
+    readonly kind: 'palavra';
+    readonly word: string;
+} | {
+    readonly kind: 'item';
+    readonly name: string;
+};
+/**
+ * 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). */
+    items(names: readonly string[]): void;
+    /**
+     * One hypothesis of utterance `index`: returns the commands it completes that were not returned before for that utterance. A
+     * partial one holds back its last name while another item's name continues it («voltar» may become «voltar ao jogo»).
+     */
+    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

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/speech-recognition — which recogniser hears the child, and what a command is in what was heard (ADR-0200 and its
+// erratum, ADR-0193, ADR-0194; issue #190).
+//
+// The browser's recognition comes first, and ONLY on the device: the Dev, «Só local, voz da criança não deve sair do aparelho». So
+// Web Speech is the route only where the browser can say it recognises on the device (`processLocally`) AND the language is
+// installed there; anything else — no API, a browser that would ignore the flag and send the voice to its servers, a language to
+// download — falls back to the recognisers the engine carries (Vosk for commands). The words heard, whoever heard them, become
+// commands the same way: the direction words and the open menu's item names, the longest name first, a partial hypothesis firing
+// what it already holds and a name another item's name continues waiting for the end (ADR-0194 §3).
+/**
+ * THE ROUTE, measured on the device (ADR-0200 §3). ⚠️ A browser whose recognition object has no `processLocally` would take the
+ * flag as an unknown property and recognise on its servers — it is never the route, whatever it says about availability.
+ */
+export async function recognitionRoute(language, api) {
+    if (!api)
+        return { route: 'recuo', status: 'sem-api' };
+    if (!('processLocally' in api.prototype) || typeof api.available !== 'function')
+        return { route: 'recuo', status: 'sem-processamento-local' };
+    let availability;
+    try {
+        availability = await api.available({ langs: [language], processLocally: true });
+    }
+    catch {
+        return { route: 'recuo', status: 'unavailable' };
+    }
+    return { route: availability === 'available' ? 'webspeech-local' : 'recuo', status: availability };
+}
+/** A recognition object set to recognise on the device, continuously, with partial hypotheses. Refuses a browser that cannot. */
+export function createOnDeviceRecognition(api, language) {
+    if (!('processLocally' in api.prototype))
+        throw new Error('speech recognition on the device is not supported here: the voice would leave the device');
+    const rec = new api();
+    rec.lang = language;
+    rec.processLocally = true;
+    rec.continuous = true;
+    rec.interimResults = true;
+    return rec;
+}
+/**
+ * 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 words = byKey(vocabulary);
+    let items = new Map();
+    const firedCount = new Map();
+    const phrasesIn = (text) => {
+        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 (items.has(f) || words.has(f)) {
+                    matched = f;
+                    i += n;
+                    break;
+                }
+            }
+            if (matched)
+                found.push(matched);
+            else
+                i++;
+        }
+        return found;
+    };
+    return {
+        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 && [...items.keys()].some((o) => o !== f && o.startsWith(f + ' ')))
+                    break;
+                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)
+                firedCount.delete(index);
+            return newCommands;
+        },
+    };
+}