@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/platform/vision.js

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/vision — THE FACE LANDMARKER AND THE CAMERA, FROM THE GAME'S OWN ORIGIN (ADR-0213, ADR-0177; issue #196).
+//
+// · MediaPipe `tasks-vision` and the face model are the files the install already fetched and checked by sha256 (`platform/heavy`).
+//   They are asked for at `heavy/<host><path>` beside the page, so no third-party host is contacted, and a file that is not in the
+//   checked cache is never loaded: the reader says which ones are missing instead, so the child hears why the eyes do not work.
+// · The bundle is imported by an ABSOLUTE address: a relative one resolves against this module, not against the page.
+// · GPU first; a GPU that fails to create the landmarker, or fails on a frame, gives way to the CPU once. The frame that failed reads
+//   nothing while the CPU landmarker is being built.
+// · `tasks-vision` tries to send usage logs to `odml.pa.googleapis.com`; the page's CSP refuses it (measured in the lab) and that is
+//   kept on purpose — nothing about the child's camera leaves the device.
+// · The camera is video only, 640×480: the lab's readings were measured at that size, and a larger capture changed them.
+import { HEAVY_FILES, deliveryPath } from './heavy.js';
+/** The files the face reader needs, by catalogue id. */
+export const FACE_VISION_FILES = ['visao:runtime', 'visao:runtime:cola', 'visao:runtime:wasm', 'visao:modelo:rosto'];
+/** The files the hand reader needs (ADR-0210 hands map: the Gesture Recognizer gives the canned gestures and the landmarks). */
+export const HAND_VISION_FILES = ['visao:runtime', 'visao:runtime:cola', 'visao:runtime:wasm', 'visao:modelo:gestos'];
+const urlOf = (id) => HEAVY_FILES.find((x) => x.id === id).url; // the vision entries are in the catalogue, with addresses
+const OPTIONS = (modelAssetPath, delegate) => ({
+    baseOptions: { modelAssetPath, delegate }, runningMode: 'VIDEO', numFaces: 1,
+    outputFaceBlendshapes: true, outputFacialTransformationMatrixes: true,
+});
+/** Checks the files in the checked cache and opens the bundle; the missing ids when any file is not there. */
+async function open(deps, files) {
+    const { hasFile } = deps;
+    const importBundle = deps.importBundle ?? ((u) => import(/* @vite-ignore */ u));
+    const missing = [];
+    for (const id of files)
+        if (!(await hasFile(urlOf(id))))
+            missing.push(id);
+    if (missing.length)
+        return { missing };
+    const at = (id) => new URL(deliveryPath(urlOf(id)), deps.base).href;
+    const vision = await importBundle(at('visao:runtime'));
+    const glue = at('visao:runtime:cola');
+    return { vision, fileset: await vision.FilesetResolver.forVisionTasks(glue.slice(0, glue.lastIndexOf('/'))), at };
+}
+/**
+ * GPU first; a GPU that fails to create, or fails on a frame, gives way to the CPU once; the frame that failed reads nothing while the CPU
+ * one is built; a CPU that cannot be built makes the next frame throw. Shared by the face and the hands.
+ */
+async function withFallback(create, read) {
+    let delegate = 'GPU', closed = false, failure = null;
+    let current;
+    try {
+        current = await create('GPU');
+    }
+    catch {
+        delegate = 'CPU';
+        current = await create('CPU');
+    }
+    const toCpu = () => {
+        current?.close();
+        current = null;
+        delegate = 'CPU';
+        create('CPU').then((l) => { if (closed)
+            l.close();
+        else
+            current = l; }, (e) => { failure = e; });
+    };
+    return {
+        detect(frame, ms) {
+            if (failure)
+                throw failure; // the CPU could not be built either: the frame loop says so on screen
+            if (!current)
+                return null;
+            try {
+                return read(current, frame, ms);
+            }
+            catch (e) {
+                if (delegate === 'CPU')
+                    throw e;
+                toCpu();
+                return null;
+            }
+        },
+        delegate: () => delegate,
+        close() { closed = true; current?.close(); current = null; },
+    };
+}
+export async function loadFaceTracker(deps) {
+    const o = await open(deps, FACE_VISION_FILES);
+    if ('missing' in o)
+        return { ok: false, missing: o.missing };
+    const F = o.vision.FaceLandmarker;
+    const eyeLines = {
+        eyes: [...F.FACE_LANDMARKS_LEFT_EYE, ...F.FACE_LANDMARKS_RIGHT_EYE, ...F.FACE_LANDMARKS_LEFT_IRIS, ...F.FACE_LANDMARKS_RIGHT_IRIS],
+        brows: [...F.FACE_LANDMARKS_LEFT_EYEBROW, ...F.FACE_LANDMARKS_RIGHT_EYEBROW],
+    };
+    const shell = await withFallback((d) => F.createFromOptions(o.fileset, OPTIONS(o.at('visao:modelo:rosto'), d)), (l, frame, ms) => l.detectForVideo(frame, ms));
+    return {
+        ok: true,
+        tracker: {
+            ...shell,
+            eyeLines,
+            faceLines: { ...eyeLines, lips: F.FACE_LANDMARKS_LIPS },
+        },
+    };
+}
+/** The Gesture Recognizer, one hand, in video mode — as the lab's map rounds ran it. */
+export async function loadHandTracker(deps) {
+    const o = await open(deps, HAND_VISION_FILES);
+    if ('missing' in o)
+        return { ok: false, missing: o.missing };
+    const options = (d) => ({ baseOptions: { modelAssetPath: o.at('visao:modelo:gestos'), delegate: d }, runningMode: 'VIDEO', numHands: 1 });
+    const shell = await withFallback((d) => o.vision.GestureRecognizer.createFromOptions(o.fileset, options(d)), (g, frame, ms) => g.recognizeForVideo(frame, ms));
+    return { ok: true, tracker: { ...shell, handLines: o.vision.GestureRecognizer.HAND_CONNECTIONS } };
+}
+/** The camera, video only, at the size the readings were measured. */
+export function openCamera(media) {
+    return media.getUserMedia({ video: { width: 640, height: 480 }, audio: false });
+}
+/** Let the camera go: every track stops, so the device's light goes off. */
+export function closeCamera(stream) {
+    for (const t of stream?.getTracks() ?? [])
+        t.stop();
+}

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

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { AudioContextLike, StreamLike } from './microphone.js';
+import type { VoskModel } from './vosk-runtime.js';
+/** How much sound is handed over at a time. The lab's number; smaller starves the recogniser, larger delays a command. */
+export declare const VOICE_BLOCK = 4096;
+export interface VoiceListenerDeps {
+    readonly model: VoskModel;
+    /** Every phrase the recogniser may answer with: the language's words, plus what the open menu is showing (ADR-0194). */
+    readonly grammar: readonly string[];
+    /**
+     * The host's `navigator.mediaDevices.getUserMedia`, lent by the root (ADR-0232 D4). REQUIRED, and `undefined` is a device
+     * with no microphone: REFUSED and said, never hidden.
+     */
+    readonly getUserMedia: ((constraints: {
+        audio: object | boolean;
+    }) => Promise<StreamLike>) | undefined;
+    /** A new audio context from the host's `AudioContext`, lent by the root. REQUIRED. */
+    readonly createContext: () => AudioContextLike;
+    /** What the recogniser has heard so far in this utterance. */
+    readonly onPartial: (text: string) => void;
+    /** The utterance ended: whoever counts what was already answered for starts a new sentence. */
+    readonly onFinal?: () => void;
+}
+export interface VoiceListener {
+    /** The words the recogniser may answer with, from now on. A new grammar is a new recogniser; the microphone stays open. */
+    setGrammar(grammar: readonly string[]): void;
+    /** Gives the microphone back and closes everything. Safe to call twice. */
+    stop(): Promise<void>;
+}
+/**
+ * Opens the microphone and feeds the recogniser until `stop()`.
+ *
+ * ⚠️ THE MICROPHONE IS ASKED FOR WITH ECHO CANCELLATION AND NOISE SUPPRESSION, which is what a classroom needs: twenty children
+ * in one room is the case, not the exception. Mono, because the recogniser hears one channel.
+ */
+export declare function startVoiceListening(d: VoiceListenerDeps): Promise<VoiceListener>;

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

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/voice-listener — THE MICROPHONE THAT HEARS COMMANDS, AND LETS GO (ADR-0189, ADR-0193; issue #184).
+//
+// The reading opens a microphone for one sentence and closes it (`platform/microphone`); this one stays open while the child
+// plays by voice, because a command may come at any moment. Everything else is the same promise: the sound is handed to a
+// recogniser ON THIS MACHINE, nothing is kept, and letting go is part of the job — a page that is still listening after the
+// child turned voice off is the promise broken, however good the reason.
+//
+// 📌 THE GRAMMAR CARRIES `[unk]`, and it is what lets the recogniser answer «that was not one of these». Without it a closed
+// grammar pushes whatever it hears to the NEAREST word — the lab measured «configurações de inclusão» coming back as «quatro»,
+// which in a game is a button the child never pressed.
+//
+// ⚠️ `ScriptProcessorNode`, deprecated, for the reason already written in `platform/microphone`: the AudioWorklet replacement
+// needs its code served as a module and the engine's policy has no `blob:` in `script-src` (ADR-0214). It is also what
+// `acceptWaveform` takes directly. Written here so the next person does not «fix» it without that decision.
+/** How much sound is handed over at a time. The lab's number; smaller starves the recogniser, larger delays a command. */
+export const VOICE_BLOCK = 4096;
+const withUnknown = (grammar) => JSON.stringify([...grammar, '[unk]']);
+/**
+ * Opens the microphone and feeds the recogniser until `stop()`.
+ *
+ * ⚠️ THE MICROPHONE IS ASKED FOR WITH ECHO CANCELLATION AND NOISE SUPPRESSION, which is what a classroom needs: twenty children
+ * in one room is the case, not the exception. Mono, because the recogniser hears one channel.
+ */
+export async function startVoiceListening(d) {
+    const { getUserMedia } = d;
+    if (!getUserMedia)
+        throw new Error('voice-listener: this device cannot open a microphone');
+    const context = d.createContext();
+    let recognizer = new d.model.KaldiRecognizer(context.sampleRate, withUnknown(d.grammar));
+    const listen = (r) => {
+        r.on('partialresult', (heard) => { const t = heard.result.partial; if (t)
+            d.onPartial(t); });
+        r.on('result', () => { d.onFinal?.(); });
+    };
+    listen(recognizer);
+    const stream = await getUserMedia({ audio: { echoCancellation: true, noiseSuppression: true, channelCount: 1 } });
+    const node = context.createScriptProcessor(VOICE_BLOCK, 1, 1);
+    let stopped = false;
+    node.onaudioprocess = (e) => {
+        if (stopped)
+            return;
+        // ⚠️ A recogniser that throws on one block must not take the microphone down with it: the next block is a new chance, and
+        // a child mid-sentence would otherwise lose the rest of it.
+        try {
+            recognizer.acceptWaveform(e.inputBuffer);
+        }
+        catch { /* this block is lost, the next is not */ }
+    };
+    context.createMediaStreamSource(stream).connect(node);
+    // 📌 The graph has to REACH the destination or nothing is pulled through it — and it must be silent, or the classroom hears
+    // itself. That is what the muted gain is for; it is not decoration.
+    node.connect(context.destination);
+    return {
+        setGrammar(grammar) {
+            if (stopped)
+                return;
+            const previous = recognizer;
+            recognizer = new d.model.KaldiRecognizer(context.sampleRate, withUnknown(grammar));
+            listen(recognizer);
+            try {
+                previous.remove();
+            }
+            catch { /* an old recogniser that is already gone is not a failure */ }
+        },
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            node.onaudioprocess = null;
+            try {
+                node.disconnect();
+            }
+            catch { /* a node already detached is not a failure */ }
+            for (const t of stream.getTracks())
+                t.stop();
+            try {
+                recognizer.remove();
+            }
+            catch { /* idem */ }
+            try {
+                d.model.terminate?.();
+            }
+            catch { /* idem */ }
+            await context.close();
+        },
+    };
+}

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

@@ -1,109 +1,13 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** Uma voz do catálogo. `voice` é o identificador no fornecedor; `engine` é o motor que a lê. */
-export interface VozNeural {
+/** A voice a child may pick. `voice` is its identifier in its engine; `engine` is the engine that reads it. */
+export interface NeuralVoice {
     readonly locale: string;
     readonly engine: string;
     readonly voice: string;
 }
 /**
- * AS QUATRO QUE A ENGINE GARANTE (ADR-0110), decididas pelo Dev em 2026-09-08.
- *
- * ⚠️ TODAS `vits-piper` E NENHUMA `ncnn`, que o ADR-0065 §5 já proibia: `ncnn` é outro MOTOR DE INFERÊNCIA —
- * modelos `.param`/`.bin` e não `.onnx` — e este projeto corre sherpa-onnx. Dois dos links que chegaram em
- * 2026-09-08 apontavam para os espelhos `ncnn`, e é por isso que a proibição tem gate e não só um comentário.
- * ⚠️ E NENHUMA `int8`, pela razão MEDIDA do mesmo §5: no backend WASM o int8 corre ~3× MAIS LENTO que o fp32
- * (RTF 5,6 contra 2,5, do log do próprio Dev) e produz saída incorrecta ou muda. Quantizar não encurta a
- * espera aqui — alonga-a.
+ * The voices a child may pick for a language (ADR-0185): matched on the LANGUAGE of the tag, not the region — a Mexican
+ * voice reads Spanish from Spain, and a Brazilian game tagged `pt` is still Portuguese. A voice reading another language
+ * is not offered: Portuguese text through English phonemes is noise.
  */
-export declare const VOZES_NEURAIS: readonly VozNeural[];
-/**
- * DE ONDE VÊM OS MODELOS (ADR-0114), num sítio só.
- *
- * 📏 MEDIDO EM 2026-09-08, e não escolhido: o `piper.ttstool.com` — que o Dev nomeou ao perguntar — serve o
- * próprio runtime da própria origem e busca os modelos aqui. As quatro vozes deste catálogo respondem 200
- * neste endereço, com `Access-Control-Allow-Origin: *`, logo um PWA pode buscá-las de outra origem.
- *
- * ⚠️ UM SÍTIO SÓ É A METADE QUE O REGISTO PEDE. Um endereço repetido no ponto de uso é como o CDN do
- * WebGazer chegou ao `ui/webcam` — escrito à mão, sem política, e sem ninguém a poder mudá-lo de uma vez.
- *
- * ========================= 🔴 MUDOU DE ESPELHO EM 2026-09-09, E A REGRA É «BUSCAR DE ONDE O LEITOR LÊ» ====
- * Era `rhasspy/piper-voices`, medido a 08/09 como o espelho que o `piper.ttstool.com` usa. Depois de o
- * `platform/pesados` passar a descer os modelos no primeiro carregamento, mediu-se o outro lado — o
- * `@mintplex-labs/piper-tts-web@1.0.4` INSTALADO, lido do bundle e não do README — e ele busca em
- * `diffusionstudio/piper-voices`, com uma guarda que recusa qualquer URL fora de `huggingface.co`.
- *
- * 🎯 ENDEREÇOS DIFERENTES SIGNIFICAM CACHE DIFERENTE: a Cache Storage é indexada pela URL do pedido, logo os
- * 241 MB que desciam no primeiro dia NÃO ERAM LIDOS POR NINGUÉM, e a biblioteca descarregava tudo outra vez
- * no dia em que a voz fosse pedida. Até 482 MB num link de escola para uma voz.
- *
- * 📏 E OS DOIS ESPELHOS SERVEM OS MESMOS BYTES — 63 201 294 para o `pt_BR-faber-medium`, caminhos idênticos,
- * `Access-Control-Allow-Origin: *` nos dois. Medido nos dois no mesmo minuto, o que torna esta troca uma
- * correcção de facto e não uma preferência entre fornecedores.
- *
- * ⚠️ A CLÁUSULA DO ADR-0114 NÃO SE MEXE: o host continua nomeado num ponto só. O que mudou foi QUAL, e a
- * regra que decide isso passa a estar escrita para não voltar a divergir — **busca-se de onde o LEITOR lê**.
- * No dia em que a engine for dona do runtime (ADR-0124 cláusula 2), o leitor passa a ser ela e é ela que
- * escolhe; até lá, o único leitor é a porta do cartucho.
- */
-export declare const HOST_DOS_MODELOS = "https://huggingface.co/diffusionstudio/piper-voices/resolve/main/";
-/**
- * O CAMINHO DO MODELO, DERIVADO DO IDENTIFICADOR — e não uma segunda tabela.
- *
- * `pt_BR-faber-medium` diz tudo o que o caminho precisa: `pt/pt_BR/faber/medium/pt_BR-faber-medium.onnx`.
- * 🎯 DERIVAR EM VEZ DE TABELAR é a decisão inteira desta função: uma tabela de caminhos ao lado da tabela
- * de vozes seria o mesmo facto escrito duas vezes, e este repositório já pagou isso três vezes — o
- * `DomQuery`, os rótulos de movimento reduzido, as chaves de armazenamento. Duas listas divergem, e
- * divergem uma entrada de cada vez.
- *
- * ⚠️ Devolve `null` para um identificador que não tenha a forma esperada, em vez de montar um caminho
- * torto: uma URL inventada dá 404 na escola, e um `null` dá para reportar antes de sair de casa.
- */
-export declare function caminhoDoModelo(v: VozNeural): string | null;
-/** O endereço completo do modelo. `null` quando o identificador não se deixa ler. */
-export declare function urlDoModelo(v: VozNeural): string | null;
-/**
- * A CONFIGURAÇÃO da voz, que o motor lê junto com o modelo.
- *
- * 📌 `.onnx.json` e não um segundo caminho: é o mesmo ficheiro com outro sufixo, medido a responder 200 no
- * mesmo sítio. Escrevê-lo como derivação mantém a regra de que o identificador é a única fonte.
- */
-export declare function urlDaConfig(v: VozNeural): string | null;
-/** Em que pé está cada voz. `falhou` é um estado e não uma excepção — ver `vozEmUso`. */
-export type EstadoDaVoz = 'ausente' | 'a-buscar' | 'pronta' | 'falhou';
-/** O que se sabe de cada voz, por identificador. Uma voz ausente do mapa é `ausente`. */
-export type EstadosDasVozes = Readonly<Record<string, EstadoDaVoz | undefined>>;
-export declare const estadoDe: (estados: EstadosDasVozes, v: VozNeural) => EstadoDaVoz;
-/**
- * A ORDEM POR QUE SE BUSCAM: primeiro as do idioma corrente, depois as outras, cada grupo na ordem do
- * catálogo. Só entram as que ainda não estão prontas nem em curso.
- *
- * ⚠️ O IDIOMA CORRENTE PRIMEIRO É A REGRA INTEIRA, e ela é sobre uma criança e não sobre eficiência: as
- * outras são para «conforme interesse do jogador», mas a dela é a que ela precisa AGORA. Buscar em ordem de
- * catálogo faria uma criança brasileira esperar por duas vozes inglesas na rede de uma escola.
- *
- * 📌 `falhou` VOLTA À FILA. Uma escola perde a rede a meio da manhã e recupera-a; uma voz marcada como
- * falhada para sempre seria uma criança sem voz até alguém recarregar a página. Quem chama decide QUANDO
- * tentar de novo — este módulo só diz que ainda há o que buscar.
- */
-export declare function ordemDeBusca(estados: EstadosDasVozes, localeCorrente: string, catalogo?: readonly VozNeural[]): VozNeural[];
-/** O que a criança ouve agora. `recuo` é a voz do sistema — eSpeak ou Web Speech. */
-export type VozEmUso = {
-    readonly tipo: 'neural';
-    readonly voice: string;
-} | {
-    readonly tipo: 'recuo';
-    readonly porque: 'a-buscar' | 'sem-voz-para-o-idioma' | 'falhou' | 'ausente';
-};
-/**
- * QUEM ESTÁ A FALAR, E POR QUE — e esta função é o gate 3 do ADR-0110 em forma de código.
- *
- * ⚠️ O DEFEITO QUE ELA IMPEDE TEM NOME NESTE REPOSITÓRIO: «um recuo que se apresenta como a coisa real é a
- * família do `reflectTTS`». Uma engine que dissesse «voz neural» enquanto o modelo ainda desce faria um adulto
- * concluir que a qualidade que ouve É a qualidade final — e desistir de esperar por uma coisa que já vinha a
- * caminho. Dizer `recuo` e dizer PORQUÊ custa uma linha e é a diferença entre informar e enganar.
- *
- * 📌 A PRIMEIRA VOZ PRONTA DO IDIOMA, e nada mais: onde há duas prontas, esta função NÃO escolhe entre elas —
- * devolve a primeira do catálogo porque tem de devolver alguma, e qual delas a criança prefere é a pergunta
- * que o ADR-0110 deixou em aberto. Ver o cabeçalho.
- */
-export declare function vozEmUso(estados: EstadosDasVozes, localeCorrente: string, catalogo?: readonly VozNeural[]): VozEmUso;
+export declare function voicesForLocale(tag: string, catalogue: readonly NeuralVoice[]): readonly NeuralVoice[];

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

@@ -1,156 +1,14 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// platform/voice-plan.ts — O PLANO DAS VOZES NEURAIS (ADR-0110), na metade PURA.
+// platform/voice-plan.ts — the shape of a voice a child may pick, and which of them speak a language (ADR-0185).
 //
-// ========================= O QUE ESTE MÓDULO É =========================
-// O catálogo das quatro vozes que a engine GARANTE, a ordem por que se buscam, e — a parte que mais importa —
-// a resposta honesta a «o que é que esta criança está a ouvir AGORA». Sem rede, sem cache, sem tempo. Quem
-// busca de facto é a outra metade; quem decide O QUE buscar e o que DIZER é esta.
-//
-// ⚠️ POR QUE O CATÁLOGO VIVE AQUI E NÃO NO `TTS_SOURCES`. A tabela do `platform/tts` é indexada por idioma e
-// tem UMA voz por idioma; este catálogo tem QUATRO vozes para TRÊS idiomas, porque o en-US tem duas. Ligá-las
-// hoje mudaria comportamento: o `loadTTS` passaria a pedir `en_US-ryan-medium` à PORTA DO CARTUCHO
-// (ADR-0094), que pode não ter essa voz. A tabela liga-se a isto quando o buscador existir, e nem um dia
-// antes — uma lista ligada a um fornecedor que não a conhece é pior do que uma lista à espera.
-//
-// ⚠️ E QUAL DAS DUAS VOZES EN-US A CRIANÇA OUVE POR PADRÃO NÃO SE DECIDE AQUI. O ADR-0110 deixa-o
-// explicitamente em aberto, e a ORDEM DESTE ARRAY NÃO É UMA PREFERÊNCIA — é a ordem em que o Dev as nomeou.
-// Ler ordem como escolha seria decidir por omissão, que é o defeito que este projeto persegue.
-/**
- * AS QUATRO QUE A ENGINE GARANTE (ADR-0110), decididas pelo Dev em 2026-09-08.
- *
- * ⚠️ TODAS `vits-piper` E NENHUMA `ncnn`, que o ADR-0065 §5 já proibia: `ncnn` é outro MOTOR DE INFERÊNCIA —
- * modelos `.param`/`.bin` e não `.onnx` — e este projeto corre sherpa-onnx. Dois dos links que chegaram em
- * 2026-09-08 apontavam para os espelhos `ncnn`, e é por isso que a proibição tem gate e não só um comentário.
- * ⚠️ E NENHUMA `int8`, pela razão MEDIDA do mesmo §5: no backend WASM o int8 corre ~3× MAIS LENTO que o fp32
- * (RTF 5,6 contra 2,5, do log do próprio Dev) e produz saída incorrecta ou muda. Quantizar não encurta a
- * espera aqui — alonga-a.
- */
-export const VOZES_NEURAIS = Object.freeze([
-    Object.freeze({ locale: 'pt-BR', engine: 'piper', voice: 'pt_BR-faber-medium' }),
-    Object.freeze({ locale: 'en-US', engine: 'piper', voice: 'en_US-ryan-medium' }),
-    Object.freeze({ locale: 'en-US', engine: 'piper', voice: 'en_US-amy-medium' }),
-    Object.freeze({ locale: 'es-MX', engine: 'piper', voice: 'es_MX-claude-high' }),
-]);
-/**
- * DE ONDE VÊM OS MODELOS (ADR-0114), num sítio só.
- *
- * 📏 MEDIDO EM 2026-09-08, e não escolhido: o `piper.ttstool.com` — que o Dev nomeou ao perguntar — serve o
- * próprio runtime da própria origem e busca os modelos aqui. As quatro vozes deste catálogo respondem 200
- * neste endereço, com `Access-Control-Allow-Origin: *`, logo um PWA pode buscá-las de outra origem.
- *
- * ⚠️ UM SÍTIO SÓ É A METADE QUE O REGISTO PEDE. Um endereço repetido no ponto de uso é como o CDN do
- * WebGazer chegou ao `ui/webcam` — escrito à mão, sem política, e sem ninguém a poder mudá-lo de uma vez.
- *
- * ========================= 🔴 MUDOU DE ESPELHO EM 2026-09-09, E A REGRA É «BUSCAR DE ONDE O LEITOR LÊ» ====
- * Era `rhasspy/piper-voices`, medido a 08/09 como o espelho que o `piper.ttstool.com` usa. Depois de o
- * `platform/pesados` passar a descer os modelos no primeiro carregamento, mediu-se o outro lado — o
- * `@mintplex-labs/piper-tts-web@1.0.4` INSTALADO, lido do bundle e não do README — e ele busca em
- * `diffusionstudio/piper-voices`, com uma guarda que recusa qualquer URL fora de `huggingface.co`.
- *
- * 🎯 ENDEREÇOS DIFERENTES SIGNIFICAM CACHE DIFERENTE: a Cache Storage é indexada pela URL do pedido, logo os
- * 241 MB que desciam no primeiro dia NÃO ERAM LIDOS POR NINGUÉM, e a biblioteca descarregava tudo outra vez
- * no dia em que a voz fosse pedida. Até 482 MB num link de escola para uma voz.
- *
- * 📏 E OS DOIS ESPELHOS SERVEM OS MESMOS BYTES — 63 201 294 para o `pt_BR-faber-medium`, caminhos idênticos,
- * `Access-Control-Allow-Origin: *` nos dois. Medido nos dois no mesmo minuto, o que torna esta troca uma
- * correcção de facto e não uma preferência entre fornecedores.
- *
- * ⚠️ A CLÁUSULA DO ADR-0114 NÃO SE MEXE: o host continua nomeado num ponto só. O que mudou foi QUAL, e a
- * regra que decide isso passa a estar escrita para não voltar a divergir — **busca-se de onde o LEITOR lê**.
- * No dia em que a engine for dona do runtime (ADR-0124 cláusula 2), o leitor passa a ser ela e é ela que
- * escolhe; até lá, o único leitor é a porta do cartucho.
- */
-export const HOST_DOS_MODELOS = 'https://huggingface.co/diffusionstudio/piper-voices/resolve/main/';
-/**
- * O CAMINHO DO MODELO, DERIVADO DO IDENTIFICADOR — e não uma segunda tabela.
- *
- * `pt_BR-faber-medium` diz tudo o que o caminho precisa: `pt/pt_BR/faber/medium/pt_BR-faber-medium.onnx`.
- * 🎯 DERIVAR EM VEZ DE TABELAR é a decisão inteira desta função: uma tabela de caminhos ao lado da tabela
- * de vozes seria o mesmo facto escrito duas vezes, e este repositório já pagou isso três vezes — o
- * `DomQuery`, os rótulos de movimento reduzido, as chaves de armazenamento. Duas listas divergem, e
- * divergem uma entrada de cada vez.
- *
- * ⚠️ Devolve `null` para um identificador que não tenha a forma esperada, em vez de montar um caminho
- * torto: uma URL inventada dá 404 na escola, e um `null` dá para reportar antes de sair de casa.
- */
-export function caminhoDoModelo(v) {
-    const partes = v.voice.split('-');
-    if (partes.length !== 3)
-        return null;
-    const [locale, nome, qualidade] = partes;
-    const idioma = locale.split('_')[0];
-    if (!idioma || !nome || !qualidade || idioma === locale)
-        return null;
-    return `${idioma}/${locale}/${nome}/${qualidade}/${v.voice}.onnx`;
-}
-/** O endereço completo do modelo. `null` quando o identificador não se deixa ler. */
-export function urlDoModelo(v) {
-    const caminho = caminhoDoModelo(v);
-    return caminho === null ? null : HOST_DOS_MODELOS + caminho;
-}
-/**
- * A CONFIGURAÇÃO da voz, que o motor lê junto com o modelo.
- *
- * 📌 `.onnx.json` e não um segundo caminho: é o mesmo ficheiro com outro sufixo, medido a responder 200 no
- * mesmo sítio. Escrevê-lo como derivação mantém a regra de que o identificador é a única fonte.
- */
-export function urlDaConfig(v) {
-    const url = urlDoModelo(v);
-    return url === null ? null : url + '.json';
-}
-export const estadoDe = (estados, v) => estados[v.voice] ?? 'ausente';
-/**
- * A ORDEM POR QUE SE BUSCAM: primeiro as do idioma corrente, depois as outras, cada grupo na ordem do
- * catálogo. Só entram as que ainda não estão prontas nem em curso.
- *
- * ⚠️ O IDIOMA CORRENTE PRIMEIRO É A REGRA INTEIRA, e ela é sobre uma criança e não sobre eficiência: as
- * outras são para «conforme interesse do jogador», mas a dela é a que ela precisa AGORA. Buscar em ordem de
- * catálogo faria uma criança brasileira esperar por duas vozes inglesas na rede de uma escola.
- *
- * 📌 `falhou` VOLTA À FILA. Uma escola perde a rede a meio da manhã e recupera-a; uma voz marcada como
- * falhada para sempre seria uma criança sem voz até alguém recarregar a página. Quem chama decide QUANDO
- * tentar de novo — este módulo só diz que ainda há o que buscar.
- */
-export function ordemDeBusca(estados, localeCorrente, catalogo = VOZES_NEURAIS) {
-    const porBuscar = catalogo.filter((v) => {
-        const e = estadoDe(estados, v);
-        return e === 'ausente' || e === 'falhou';
-    });
-    return [
-        ...porBuscar.filter((v) => v.locale === localeCorrente),
-        ...porBuscar.filter((v) => v.locale !== localeCorrente),
-    ];
-}
+// 📌 The engine owns no neural voice catalogue of its own (ADR-0207) and Kokoro's voices come through the
+// game's port (`platform/kokoro`, ADR-0198). What stays here is the rule every list obeys — the browser's and Kokoro's.
 /**
- * QUEM ESTÁ A FALAR, E POR QUE — e esta função é o gate 3 do ADR-0110 em forma de código.
- *
- * ⚠️ O DEFEITO QUE ELA IMPEDE TEM NOME NESTE REPOSITÓRIO: «um recuo que se apresenta como a coisa real é a
- * família do `reflectTTS`». Uma engine que dissesse «voz neural» enquanto o modelo ainda desce faria um adulto
- * concluir que a qualidade que ouve É a qualidade final — e desistir de esperar por uma coisa que já vinha a
- * caminho. Dizer `recuo` e dizer PORQUÊ custa uma linha e é a diferença entre informar e enganar.
- *
- * 📌 A PRIMEIRA VOZ PRONTA DO IDIOMA, e nada mais: onde há duas prontas, esta função NÃO escolhe entre elas —
- * devolve a primeira do catálogo porque tem de devolver alguma, e qual delas a criança prefere é a pergunta
- * que o ADR-0110 deixou em aberto. Ver o cabeçalho.
+ * The voices a child may pick for a language (ADR-0185): matched on the LANGUAGE of the tag, not the region — a Mexican
+ * voice reads Spanish from Spain, and a Brazilian game tagged `pt` is still Portuguese. A voice reading another language
+ * is not offered: Portuguese text through English phonemes is noise.
  */
-export function vozEmUso(estados, localeCorrente, catalogo = VOZES_NEURAIS) {
-    const doIdioma = catalogo.filter((v) => v.locale === localeCorrente);
-    if (doIdioma.length === 0)
-        return { tipo: 'recuo', porque: 'sem-voz-para-o-idioma' };
-    const pronta = doIdioma.find((v) => estadoDe(estados, v) === 'pronta');
-    if (pronta)
-        return { tipo: 'neural', voice: pronta.voice };
-    // A PRECEDÊNCIA DOS TRÊS RECUOS, e cada degrau tem a sua razão:
-    //
-    // ⚠️ «A BUSCAR» GANHA DE «FALHOU» quando as duas coexistem: enquanto alguma ainda vem a caminho, dizer
-    //    «falhou» seria anunciar uma derrota que ainda não aconteceu, e um adulto desligaria a espera cedo.
-    // ⚠️ E «AUSENTE» NÃO SE DISFARÇA DE «A BUSCAR», que era como esta função estava escrita à primeira. Nada
-    //    começou é diferente de está a caminho: o primeiro é uma engine que ainda não pediu — possivelmente
-    //    porque ninguém a mandou —, e chamar-lhe «a buscar» esconderia um buscador que nunca arrancou atrás de
-    //    uma frase tranquilizadora. É o mesmo defeito de forma que o `neuralDisponivel` já custou à #91.
-    if (doIdioma.some((v) => estadoDe(estados, v) === 'a-buscar'))
-        return { tipo: 'recuo', porque: 'a-buscar' };
-    if (doIdioma.some((v) => estadoDe(estados, v) === 'falhou'))
-        return { tipo: 'recuo', porque: 'falhou' };
-    return { tipo: 'recuo', porque: 'ausente' };
+export function voicesForLocale(tag, catalogue) {
+    const language = (tag.split('-')[0] ?? '').toLowerCase();
+    return catalogue.filter((v) => (v.locale.split('-')[0] ?? '').toLowerCase() === language);
 }

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

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** The three files of the runtime. The model is chosen by language, below. */
+export declare const VOICE_RUNTIME_FILES: readonly ["commands:runtime", "commands:runtime:worker", "commands:runtime:wasm"];
+/** The catalogue id of the model that hears THIS language, or `null` where the project has none. */
+export declare function commandModelId(language: string): string | null;
+/** What the recogniser answers with. `partial` grows during one utterance; `text` is the sentence once it ends. */
+export interface VoskHeard {
+    readonly result: {
+        readonly partial?: string;
+        readonly text?: string;
+    };
+}
+export interface VoskRecognizer {
+    on(event: 'partialresult' | 'result', cb: (heard: VoskHeard) => void): void;
+    /** One block of sound, as the audio graph delivers it. */
+    acceptWaveform(buffer: AudioBuffer): void;
+    remove(): void;
+}
+export interface VoskModel {
+    KaldiRecognizer: new (sampleRate: number, grammar: string) => VoskRecognizer;
+    terminate?(): void;
+}
+/**
+ * What the bundle exports. `resolve` is how it asks US for the two files it needs beside the model — the worker it spawns and
+ * the wasm that worker loads — so nothing is ever guessed from the bundle's own address.
+ */
+export interface VoskApi {
+    createModel(url: string, resolve: (logicalPath: string) => string, logLevel?: number): Promise<VoskModel>;
+}
+export interface VoskDeps {
+    /** The page's address, to make the delivery paths absolute. */
+    readonly base: string;
+    /** The child's language (`core/i18n.bcp47`): it chooses the model. */
+    readonly language: string;
+    /**
+     * Whether a catalogue file (by its upstream address) is in the checked cache — `platform/heavy`'s `checkedCacheHas`, over the
+     * host's `caches`. REQUIRED (ADR-0232 D4): the root lends the cache; this module reaches none.
+     */
+    readonly hasFile: (upstreamUrl: string) => Promise<boolean>;
+    /**
+     * Imports the bundle and answers with what it exports — `createBundleLoader` below, built ONCE by the root, so the bundle is
+     * put in the page once per address. REQUIRED, and injected so a gate never imports 3 MiB of wasm loader.
+     */
+    readonly loadBundle: (absoluteUrl: string) => Promise<VoskApi>;
+}
+export type VoskLoad = {
+    readonly ok: true;
+    readonly model: VoskModel;
+}
+/** The catalogue ids that are not in the checked cache — `language` when the project has no model for it. */
+ | {
+    readonly ok: false;
+    readonly missing: readonly string[];
+};
+/**
+ * PUTS THE BUNDLE IN THE PAGE ONCE PER ADDRESS, and answers with what it exports. A second call answers the same one: the
+ * bundle registers a worker and a wasm module, and loading it twice would pay for both again on a machine that has little of
+ * either. A rejection is forgotten, so a load that failed on a bad minute can be retried.
+ *
+ * 🔴 THE MEMO IS THE LOADER'S, AND THE LOADER IS BUILT ONCE BY THE ROOT (ADR-0232 D4), which hands it to every start of the
+ * recogniser. A memo built inside `loadVoskRuntime` was a new memo every call, so «once» only ever held within one call; a
+ * memo at module level was one per PAGE, shared by roots that share nothing else. `load` is the root's `import(url)`.
+ */
+export declare function createBundleLoader(load: (absoluteUrl: string) => Promise<unknown>): (absoluteUrl: string) => Promise<VoskApi>;
+/**
+ * Opens the recogniser for the child's language, or says what is missing.
+ *
+ * ⚠️ THE MODEL IS A `.tar.gz` THE BUNDLE FETCHES ITSELF, so what it is given is the DELIVERY path: the service worker answers it
+ * from the checked cache, and a school with no network after the first day still hears the child (pillar 8).
+ */
+export declare function loadVoskRuntime(d: VoskDeps): Promise<VoskLoad>;