@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/platform/heavy.js

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/heavy.ts — THE HEAVY THINGS, DOWNLOADED ON FIRST LOAD (ADR-0110, ADR-0116, ADR-0119).
+//
+// ========================= WHAT THIS IS =========================
+// Pillar 8 says "PWA ONLINE on the first day, then OFFLINE-FIRST", and ADR-0116 removed the contradiction that blocked
+// this: installing is already a network act, so fetching at install violates nothing. What was missing was someone
+// fetching.
+//
+// ⚠️ AND IT DOES NOT BLOCK THE GAME. The child plays while the heavy files come down; what must not happen is them
+// reaching the second day, offline, and finding the voice was never fetched.
+//
+// ========================= THE THREE RULES THE SHAPE IMPOSES =========================
+//  1. **ONE AT A TIME.** Four 60 MB downloads in parallel on a school link fight for the same bandwidth and none
+//     finishes first — and the game, which needs the network for its own images, waits behind them.
+//  2. **NEVER THROWS.** A network failure is REPORTED and the list goes on. A `throw` here would bring down a game's
+//     start over a resource it may not even use today.
+//  3. **IDEMPOTENT.** What is already in Cache Storage is not fetched again — which is what makes this safe to call on
+//     every start instead of only "on the first", which nobody can detect honestly.
+import { CACHE_HEAVY, HEAVY_FILES, readingLanguageOf, commandsLanguageOf } from './heavy-catalogue.js';
+export { CACHE_HEAVY, HEAVY_FILES };
+/**
+ * WHAT A GAME'S START FETCHES (ADR-0216 §3): the catalogue, less what this game did not ask for.
+ *
+ * · The neural voice — its model, its voices AND the runtime that speaks them: without that answer they are 372 MB taken from a
+ *   school's link and a child's device for nothing.
+ * · The reading models: 850 MiB for the three languages, so `reading` is not a yes or no but a LANGUAGE — the child's, known at
+ *   boot. A delivery may carry more than one; a device downloads the one being read in. A game that never listens gets none.
+ * · 🔴 THE GRAPH RUNTIME IS NOT THE VOICE'S, and its `voz:` name said otherwise. `platform/onnx-runtime` runs Kokoro AND the
+ *   reading models, so a game that only LISTENS needs it: without this line its delivery carried a 378 MiB model and nothing
+ *   able to open it, and the first `listen()` asked for a file the build never wrote. Measured on 2026-09-21, building the
+ *   very delivery this exists to serve. The PHONEMIZER (`voz:runtime:fonemas`, 18.7 MiB) stays the voice's — nothing else
+ *   turns letters into sounds.
+ * · The command models (issue #184): one per language too, 112 MiB for the three, and the runtime that loads them. Nothing in
+ *   the game decides this — speaking instead of pressing is a way INTO the controller, and a cartridge does not get to close
+ *   one (ADR-0111). What decides is the delivery: `inclusionist-heavy --commands pt` puts Portuguese in it.
+ */
+export function heavyAtBoot(declared) {
+    const reading = declared.reading ? declared.reading.split('-')[0].toLowerCase() : null;
+    const commands = declared.commands ? declared.commands.split('-')[0].toLowerCase() : null;
+    return HEAVY_FILES.filter((p) => {
+        const language = readingLanguageOf(p.id);
+        if (language)
+            return language === reading;
+        // 📌 THE COMMAND MODELS ARE A TRANSPORT'S, not a game's: no cartridge declares them, because a child who speaks instead of
+        // pressing is reaching the controller, and a cartridge does not get to deny her a way in (ADR-0111). The LANGUAGE is still
+        // asked — 112 MiB for the three — and the runtime comes with whichever one does.
+        const commanded = commandsLanguageOf(p.id);
+        if (commanded)
+            return commanded === commands;
+        if (p.id.startsWith('commands:runtime'))
+            return !!commands;
+        if (p.id.startsWith('voz:runtime:onnx'))
+            return declared.kokoro || !!reading;
+        return declared.kokoro || !(p.id.startsWith('voz:kokoro:') || p.id.startsWith('voz:runtime:'));
+    }).map((p) => p.id);
+}
+/**
+ * WHERE THE DELIVERY SERVES A HEAVY FILE (ADR-0177, issue #173): `heavy/<host><path>` beside the page. The child's device
+ * reads it from the game's own origin; the upstream address is only where the build fetched it from.
+ * 📌 The upstream address stays the CACHE KEY: it is what the voice and vision libraries ask for, and the service worker answers
+ * them from the checked cache without a network request.
+ *
+ * 🔴 THE FOLDER WAS CALLED «pesados» UNTIL 2026-09-21 (ADR-0219). 📏 What that costs a school was measured before it changed:
+ * the entries are kept under the UPSTREAM address, so nothing is re-downloaded — what breaks is a delivery built by the old
+ * `bin` under a new engine, which asks for `heavy/…` and gets a 404 until the delivery is built again.
+ */
+export function deliveryPath(url) {
+    const u = new URL(url);
+    return `heavy/${u.host}${u.pathname}`;
+}
+/**
+ * The inverse, for the service worker: a request for `…/heavy/<host><path>` is answered from the entry kept under
+ * `https://<host><path>`; any other address has no key (`null`). It is the route's `cacheKeyWillBeUsed` itself, so it also
+ * takes Workbox's `{ request }`. Self-contained on purpose — the PWA plugin copies this function's SOURCE into `sw.js`, where
+ * nothing else from this module exists.
+ *
+ * ⚠️ THE OFFSET COMES FROM THE FOLDER'S OWN LENGTH, and it is written this way because of what a blind rename would have done
+ * here: the old code advanced by 9, the length of the old folder's name with its slashes, and `/heavy/` is 7 — a text
+ * replacement of the name alone would
+ * have left every cache key with two characters of the host eaten, and the only symptom would be a cache that never hits.
+ */
+export function deliveryCacheKey(urlOrRequest) {
+    const folder = '/heavy/';
+    const urlPath = new URL(typeof urlOrRequest === 'string' ? urlOrRequest : urlOrRequest.request.url).pathname;
+    const i = urlPath.indexOf(folder);
+    return i < 0 ? null : 'https://' + urlPath.slice(i + folder.length);
+}
+/**
+ * DOWNLOADS WHAT IS MISSING, ONE AT A TIME, AND RETURNS WHAT HAPPENED TO EACH.
+ *
+ * ⚠️ ENTRIES WITHOUT A `url` ARE NOT SKIPPED IN SILENCE — they return `sem-fonte`. It is the difference between "this
+ * subsystem has nowhere to come from yet" and "this subsystem is handled", exactly the distinction ADR-0119 measured as
+ * missing: the engine PROMISED four things and delivered one, with nothing saying so.
+ */
+export async function downloadHeavy(options) {
+    const targets = options.only ? HEAVY_FILES.filter((p) => options.only.includes(p.id)) : HEAVY_FILES;
+    const out = [];
+    const record = (r) => { out.push(r); options.onProgress?.(r); };
+    const { cacheStorage, fetch: fetchFile, digest, base } = options;
+    if (!cacheStorage || !fetchFile) {
+        for (const p of targets)
+            record({ id: p.id, outcome: 'falhou', error: 'sem Cache Storage ou sem fetch' });
+        return out;
+    }
+    const tools = { cache: await cacheStorage.open(CACHE_HEAVY), fetchFile, digest, base };
+    for (const p of targets)
+        record(await fetchOne(p, tools));
+    return out;
+}
+/** One file's fate: already kept, fetched from the delivery and checked, or refused — always with the reason. */
+async function fetchOne(p, t) {
+    if (!p.url)
+        return { id: p.id, outcome: 'sem-fonte', error: p.whyNoSource };
+    try {
+        if (await t.cache.match(p.url))
+            return { id: p.id, outcome: 'ja-tinha' };
+        // from the delivery's own origin, never from the upstream host (ADR-0177)
+        const resp = await t.fetchFile(new URL(deliveryPath(p.url), t.base).href);
+        if (!resp.ok)
+            return { id: p.id, outcome: 'falhou', error: `HTTP ${resp.status}` };
+        return await keepIfChecked(p, p.url, resp, t);
+    }
+    catch (e) {
+        return { id: p.id, outcome: 'falhou', error: e instanceof Error ? e.message : String(e) };
+    }
+}
+/**
+ * CHECKED BEFORE KEPT (issue #168; STRIDE client pass). What is kept runs in the child's page and is served offline from then
+ * on, so a body whose SHA-256 is not the measured one never enters the cache. It is kept under the UPSTREAM address, which is
+ * what the voice and vision libraries ask for.
+ */
+async function keepIfChecked(p, url, resp, t) {
+    const refused = (reason) => ({ id: p.id, outcome: 'falhou', error: reason });
+    if (!p.sha256)
+        return refused('this entry pins its sha256 nowhere: there is nothing to check it against');
+    if (!t.digest)
+        return refused('this host cannot compute a sha256 (crypto.subtle needs a secure context)');
+    const body = await resp.arrayBuffer();
+    const got = await t.digest(body);
+    if (got !== p.sha256)
+        return refused(`sha256 mismatch: expected ${p.sha256}, got ${got} — not kept`);
+    await t.cache.put(url, new Response(body, { status: resp.status, statusText: resp.statusText, headers: resp.headers }));
+    return { id: p.id, outcome: 'baixado', bytes: p.bytes };
+}
+/**
+ * THE SHA-256 OF A BODY AS LOWERCASE HEX, by the `crypto.subtle` it is handed (issue #168) — or `null` when there is none,
+ * which is a host outside a secure context: the answer `HeavyOptions.digest` reads as «cannot hash, so keep nothing».
+ */
+export function sha256With(subtle) {
+    if (!subtle)
+        return null;
+    return async (payload) => {
+        const bytes = new Uint8Array(await subtle.digest('SHA-256', payload));
+        return [...bytes].map((x) => x.toString(16).padStart(2, '0')).join('');
+    };
+}
+/**
+ * WHETHER A CATALOGUE FILE IS IN THE CHECKED CACHE, by its upstream address — what `platform/vision` and
+ * `platform/vosk-runtime` ask before loading anything. The host's `caches` is handed in; `undefined` (an insecure context)
+ * holds nothing, so every file is missing and the loader names them.
+ */
+export function checkedCacheHas(cacheStorage) {
+    return async (url) => !!cacheStorage && !!(await (await cacheStorage.open(CACHE_HEAVY)).match(url));
+}
+/** The size of what is still missing, in bytes — so a notice can say how much is left before it starts. */
+export function bytesLeftToDownload(soFar) {
+    const feitos = new Set(soFar.filter((r) => r.outcome === 'ja-tinha' || r.outcome === 'baixado').map((r) => r.id));
+    return HEAVY_FILES.filter((p) => p.url && !feitos.has(p.id)).reduce((s, p) => s + (p.bytes ?? 0), 0);
+}

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

@@ -1,19 +1,19 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** O que o chamador precisa fornecer. Nada aqui conhece PIPER, Web Audio ou o navegador. */
-export interface MotorDeFala<Audio, Fonte> {
-    /** Texto → áudio. ASSÍNCRONO de propósito: é onde a síntese neural gasta o tempo dela. */
-    sintetizar(texto: string): Promise<Audio>;
-    /** Começa a tocar e devolve a fonte, para que ela possa ser parada. `null` = não deu para tocar agora. */
-    tocar(audio: Audio, aoTerminar: () => void): Fonte | null;
-    /** Cala a fonte. Chamado com o que `tocar` devolveu, e nunca com `null`. */
-    parar(fonte: Fonte): void;
+/** What the caller provides. Nothing here knows the neural engine, Web Audio or the browser. */
+export interface SpeechEngine<Audio, Fonte> {
+    /** Text → audio. ASYNCHRONOUS on purpose: it is where neural synthesis spends its time. */
+    synthesize(text: string): Promise<Audio>;
+    /** Starts playing and returns the source, so it can be stopped. `null` = it could not play right now. */
+    play(audio: Audio, onEnded: () => void): Fonte | null;
+    /** Silences the source. Called with what `play` returned, and never with `null`. */
+    stop(playing: Fonte): void;
 }
-export interface FalaInterrompivel {
-    /** Fala `texto`, CALANDO na hora o que estiver falando. Não enfileira: o último pedido é o que vale. */
-    falar(texto: string): void;
-    /** Cala e esquece. Usado ao fechar um menu ou ao desligar a narração. */
-    calar(): void;
-    /** Está tocando alguma coisa? Só para teste e depuração — a política não depende disto. */
-    falando(): boolean;
+export interface InterruptibleSpeech {
+    /** Speaks `text`, SILENCING at once whatever is speaking. It does not queue: the latest request is the one that counts. */
+    speak(text: string): void;
+    /** Silences and forgets. Used when a menu closes or narration is switched off. */
+    silence(): void;
+    /** Is anything playing? For tests and debugging only — the policy does not depend on it. */
+    speaking(): boolean;
 }
-export declare function criarFalaInterrompivel<Audio, Fonte>(motor: MotorDeFala<Audio, Fonte>): FalaInterrompivel;
+export declare function createInterruptibleSpeech<Audio, Fonte>(engine: SpeechEngine<Audio, Fonte>): InterruptibleSpeech;

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

@@ -1,79 +1,78 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// platform/interruptible-speech — FALAR O ÚLTIMO PEDIDO, E CALAR O ANTERIOR NA HORA (ADR-0044, item 2).
+// platform/interruptible-speech — SPEAK THE LATEST REQUEST, AND SILENCE THE PREVIOUS ONE AT ONCE (ADR-0044, item 2).
 //
-// ========================= O DEFEITO QUE ISTO SUBSTITUI =========================
-// O motor neural falava assim:
+// ========================= THE DEFECT THIS REPLACES =========================
+// The neural engine used to speak like this:
 //
-//     speak: (text) => { if (busy) next = text; else speakNow(text); }   // fila de 1
+//     speak: (text) => { if (busy) next = text; else speakNow(text); }   // a queue of 1
 //
-// Uma FILA, e de tamanho um. Varrendo cinco itens de menu, a criança ouvia o PRIMEIRO inteiro e depois o
-// ÚLTIMO — os três do meio sumiam em silêncio, porque cada novo pedido sobrescrevia o `next`. É lento E
-// perde informação, e as duas coisas doem no mesmo lugar: a pessoa que não enxerga navega POR ESCUTA, e a
-// escuta estava vários itens atrás do foco.
+// A QUEUE, of size one. Sweeping five menu items, the child heard the FIRST one whole and then the LAST — the three in
+// between vanished in silence, because each new request overwrote `next`. It is slow AND it loses information, and both
+// hurt in the same place: a person who cannot see navigates BY EAR, and the ear was several items behind the focus.
 //
-// A XAG 106 diz o que fazer, e diz por quê: se a narração do item em foco ainda está sendo lida e o foco
-// muda, "a narração do elemento original deve PARAR IMEDIATAMENTE, e a do novo elemento começar".
+// XAG 106 says what to do, and why: if the focused item's narration is still being read when the focus moves, the
+// original element's narration stops IMMEDIATELY and the new element's begins.
 //
-// ========================= AS DUAS COISAS QUE ISTO GARANTE =========================
+// ========================= THE TWO THINGS THIS GUARANTEES =========================
 //
-//   1. CALA ANTES DE SINTETIZAR, não depois. Síntese neural leva tempo; parar só quando o áudio novo fica
-//      pronto deixaria a voz velha falando durante a espera — o item errado, com convicção. Silêncio é a
-//      resposta certa: a criança sabe que se moveu, e o silêncio confirma.
+//   1. SILENCE BEFORE SYNTHESISING, not after. Neural synthesis takes time; stopping only once the new audio is ready would
+//      leave the old voice speaking during the wait — the wrong item, with conviction. Silence is the right answer: the
+//      child knows they moved, and the silence confirms it.
 //
-//   2. GERAÇÃO, e é o que impede a corrida. `sintetizar` é assíncrono, e dois pedidos podem terminar fora
-//      de ordem: o segundo fica pronto primeiro, começa a tocar, e o primeiro chega depois e o atropela —
-//      a criança ouviria o item que ela JÁ passou, por cima do atual. Cada pedido carrega o seu número; o
-//      que voltar com número velho é descartado, em cada um dos dois `await`.
+//   2. A GENERATION, which is what prevents the race. `synthesize` is asynchronous, and two requests can finish out of
+//      order: the second is ready first and starts playing, then the first arrives and runs it over — the child would
+//      hear the item they ALREADY passed, on top of the current one. Each request carries its number; whatever comes back
+//      with an old number is dropped, at each of the two `await`s.
 //
-// ========================= POR QUE É UM MÓDULO, E NÃO UMA LINHA NO `tts` =========================
-// Porque assim se pode PROVAR. O bloco neural vive dentro de um `import()` dinâmico que só resolve com o
-// runtime de 25,6 MB presente; testá-lo lá dentro exigiria o motor de verdade. Aqui a política é pura —
-// recebe "como sintetizar", "como tocar" e "como parar" — e o teste de node exercita a corrida e a
-// interrupção com falsos, em milissegundos.
-export function criarFalaInterrompivel(motor) {
-    let tocando = null;
-    let geracao = 0;
-    /** Cala o que estiver tocando. O `try` existe porque parar uma fonte já terminada lança em alguns motores. */
-    function pararTudo() {
-        if (tocando !== null) {
+// ========================= WHY A MODULE, AND NOT A LINE IN `tts` =========================
+// Because this way it can be PROVEN. The neural block lives inside a dynamic `import()` that only resolves with the
+// runtime present; testing it there would need the real engine. Here the policy is pure — it receives "how to
+// synthesise", "how to play" and "how to stop" — and the node test exercises the race and the interruption with fakes,
+// in milliseconds.
+export function createInterruptibleSpeech(engine) {
+    let nowPlaying = null;
+    let currentTurn = 0;
+    /** Silences whatever is playing. The `try` exists because stopping an already finished source throws in some engines. */
+    function stopPlayback() {
+        if (nowPlaying !== null) {
             try {
-                motor.parar(tocando);
+                engine.stop(nowPlaying);
             }
-            catch (e) { /* fonte já encerrada — parar de novo não é erro */ }
-            tocando = null;
+            catch (e) { /* the source already ended — stopping again is no error */ }
+            nowPlaying = null;
         }
     }
-    async function falar(texto) {
-        const minha = ++geracao; // reivindica a vez ANTES de qualquer espera
-        pararTudo(); // garantia 1: silêncio imediato, não ao fim da síntese
-        if (!texto)
+    async function speakNow(text) {
+        const myTurn = ++currentTurn; // claims the turn BEFORE any wait
+        stopPlayback(); // guarantee 1: immediate silence, not at the end of synthesis
+        if (!text)
             return;
         try {
-            const audio = await motor.sintetizar(texto);
-            if (minha !== geracao)
-                return; // garantia 2: chegou tarde — outro pedido já assumiu
-            pararTudo(); // de novo: alguém pode ter começado a tocar durante a espera
-            const fonte = motor.tocar(audio, () => { if (tocando === fonte)
-                tocando = null; });
-            if (minha !== geracao) {
-                if (fonte !== null) {
+            const audio = await engine.synthesize(text);
+            if (myTurn !== currentTurn)
+                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; });
+            if (myTurn !== currentTurn) {
+                if (playing !== null) {
                     try {
-                        motor.parar(fonte);
+                        engine.stop(playing);
                     }
                     catch (e) { /* noop */ }
                 }
                 return;
             }
-            tocando = fonte;
+            nowPlaying = playing;
         }
         catch (e) {
-            // Síntese falhou para ESTE texto. Não é motivo para derrubar a narração inteira: o próximo pedido
-            // tenta de novo, e o silêncio de um item é melhor que um motor morto.
+            // 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.
         }
     }
     return {
-        falar: (texto) => { void falar(texto); },
-        calar: () => { geracao++; pararTudo(); }, // o `++` invalida o que estiver sintetizando agora
-        falando: () => tocando !== null,
+        speak: (text) => { void speakNow(text); },
+        silence: () => { currentTurn++; stopPlayback(); }, // the `++` invalidates whatever is being synthesised now
+        speaking: () => nowPlaying !== null,
     };
 }

package/dist-pkg/platform/kokoro-port.d.ts

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { KokoroModule } from './kokoro.js';
+import type { OnnxRuntime } from './onnx-runtime.js';
+/** The file system espeak-ng's Emscripten module exposes — only what this uses. */
+export interface EspeakFileSystem {
+    readonly writeFile: (path: string, text: string) => void;
+    readonly readFile: (path: string, options: {
+        encoding: 'utf8';
+    }) => string;
+}
+/** espeak-ng's module factory: one program run per call, with its arguments and the hooks run before `main`. */
+export type EspeakFactory = (options: {
+    readonly arguments: readonly string[];
+    readonly preRun: readonly ((m: {
+        FS: EspeakFileSystem;
+    }) => void)[];
+}) => Promise<{
+    FS: EspeakFileSystem;
+}>;
+export interface KokoroPortDeps {
+    readonly espeak: EspeakFactory;
+    readonly ort: OnnxRuntime;
+    readonly fetch: (url: string) => Promise<Response>;
+    /** The page's address `heavy/` is resolved against. */
+    readonly base: string;
+}
+export declare function createKokoroPort(d: KokoroPortDeps): KokoroModule;

package/dist-pkg/platform/kokoro-port.js

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { KOKORO_MODEL_URL, URL_DO_TOKENIZADOR_KOKORO, kokoroVoiceUrl } from './kokoro.js';
+import { deliveryPath } from './heavy.js';
+const INPUT = 'entrada.txt';
+const OUTPUT = 'fonemas.txt';
+export function createKokoroPort(d) {
+    const fromDelivery = async (url) => {
+        const path = deliveryPath(url);
+        const r = await d.fetch(new URL(path, d.base).href);
+        if (!r.ok)
+            throw new Error(`Kokoro: HTTP ${r.status} for ${path} — the delivery does not carry it (inclusionist-heavy --kokoro)`);
+        return r;
+    };
+    let vocabulary = null;
+    // ⚠️ ONE COPY of the 325 MB model for every session: the engine tries WebGPU and may fall back to WASM
+    let model = null;
+    return {
+        async phonemize(text, espeak) {
+            // the sentence goes in as a FILE and never as an argument: a line starting with «-» would be read as an option
+            const e = await d.espeak({
+                arguments: ['-q', '--ipa', '--phonout', OUTPUT, '-v', espeak, '-f', INPUT],
+                preRun: [(m) => m.FS.writeFile(INPUT, text.replace(/\s+/g, ' '))],
+            });
+            return e.FS.readFile(OUTPUT, { encoding: 'utf8' }).trim().replace(/\s*\n\s*/g, ' ');
+        },
+        vocabulary() {
+            vocabulary ??= fromDelivery(URL_DO_TOKENIZADOR_KOKORO)
+                .then(async (r) => (await r.json()).model.vocab);
+            return vocabulary;
+        },
+        async voice(id) {
+            return new Float32Array(await (await fromDelivery(kokoroVoiceUrl(id))).arrayBuffer());
+        },
+        async session(device) {
+            model ??= fromDelivery(KOKORO_MODEL_URL).then(async (r) => new Uint8Array(await r.arrayBuffer()));
+            const s = await d.ort.InferenceSession.create(await model, { executionProviders: [device] });
+            const session = {
+                async synthesize(ids, style) {
+                    const out = await s.run({
+                        input_ids: new d.ort.Tensor('int64', BigInt64Array.from(ids, (id) => BigInt(id)), [1, ids.length]),
+                        style: new d.ort.Tensor('float32', style, [1, style.length]),
+                        speed: new d.ort.Tensor('float32', Float32Array.of(1), [1]), // the pace is the engine's, on playback (ADR-0196)
+                    });
+                    return out[s.outputNames[0]].data;
+                },
+            };
+            return session;
+        },
+    };
+}

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

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { KokoroModule } from './kokoro.js';
+export interface KokoroRuntimeDeps {
+    /** The page's address, which `heavy/` is resolved against. */
+    readonly base: string;
+    /**
+     * The host's `fetch`, and the host's `WebAssembly.compile` and `instantiate` below: REQUIRED (ADR-0232 D4). The root lends
+     * them from `host.win`; a default would be the page's globals reached from `platform/`, and a case answers without a network.
+     */
+    readonly fetch: (url: string) => Promise<Response>;
+    /** `import()`, injected so a case can hand in the two modules without a network. Optional: `import()` is not a global. */
+    readonly importModule?: (url: string) => Promise<unknown>;
+    readonly compileWasm: (bytes: ArrayBuffer) => Promise<WebAssembly.Module>;
+    readonly instantiateWasm: (module: WebAssembly.Module, imports: WebAssembly.Imports) => Promise<WebAssembly.Instance>;
+}
+/**
+ * Builds the neural voice. Everything it needs is fetched from the delivery, so a device that never had a network day has it all
+ * or has none of it — and «none of it» is a refusal the caller reports, not a silence.
+ */
+export declare function loadKokoroRuntime(d: KokoroRuntimeDeps): Promise<KokoroModule>;

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

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/kokoro-runtime — THE ENGINE LOADS THE NEURAL VOICE ITSELF (ADR-0216 and its erratum; 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». So the
+// phonemizer and the ONNX runtime are no longer a game's dependency: they are catalogued heavy files (`voz:runtime:*`), the build
+// puts them in the delivery, and this loads them from `heavy/` on the page's own origin — the same path the vision runtime
+// already takes (ADR-0177, `platform/vision`).
+//
+// ⚠️ NOTHING HERE IS IMPORTED FROM npm, and that is the point: an `import 'espeak-ng'` would put the phonemizer in the bundle of
+// every game that merely links the engine, and would need a bundler to resolve it. `import(url)` of an address on our own origin
+// needs neither, and it happens only when a child picks a neural voice.
+//
+// · The wasm of espeak-ng is compiled ONCE and instantiated per sentence: its module runs one program and exits.
+// · onnxruntime's threads load their own glue and wasm; they are pointed at `heavy/` too, because a worker that goes looking for
+//   them on a CDN finds nothing in a school with no network, and the child hears silence (measured in the quiz demo, #181).
+import { createKokoroPort } from './kokoro-port.js';
+import { atDelivery, loadOnnxRuntime } from './onnx-runtime.js';
+// The addresses are the catalogue's, reached by id through `platform/onnx-runtime` — never written twice (ADR-0114, ADR-0177).
+const ESPEAK_GLUE = 'voz:runtime:fonemas';
+const ESPEAK_WASM = 'voz:runtime:fonemas:wasm';
+/**
+ * Builds the neural voice. Everything it needs is fetched from the delivery, so a device that never had a network day has it all
+ * or has none of it — and «none of it» is a refusal the caller reports, not a silence.
+ */
+export async function loadKokoroRuntime(d) {
+    const { compileWasm: compile, instantiateWasm: instantiate, fetch: get } = d;
+    const loadModule = d.importModule ?? ((url) => import(/* @vite-ignore */ url));
+    const espeakModule = await loadModule(atDelivery(ESPEAK_GLUE, d.base));
+    const factory = (typeof espeakModule === 'function' ? espeakModule : espeakModule.default);
+    if (typeof factory !== 'function')
+        throw new Error('Kokoro: espeak-ng did not load from the delivery (voz:runtime:fonemas)');
+    // by BYTES and not by stream: a server that sends the file without `application/wasm` must not break the voice
+    let compiled = null;
+    const espeak = (options) => {
+        compiled ??= get(atDelivery(ESPEAK_WASM, d.base)).then(async (r) => {
+            if (!r.ok)
+                throw new Error(`Kokoro: HTTP ${r.status} for espeak-ng's wasm — the delivery does not carry it`);
+            return compile(await r.arrayBuffer());
+        });
+        const module = compiled;
+        return factory({
+            ...options,
+            instantiateWasm: (imports, ready) => {
+                void module.then(async (m) => ready(await instantiate(m, imports), m));
+                return {};
+            },
+        });
+    };
+    // the runtime, and the rule about its threads, are `platform/onnx-runtime`'s — the reading loads the same one the same way
+    const ort = await loadOnnxRuntime({ base: d.base, importModule: loadModule });
+    return createKokoroPort({ espeak, ort, fetch: get, base: d.base });
+}

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

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { NeuralVoice } from './voice-plan.js';
+/** A Kokoro inference session on one device: token ids and a style row in, a 24 kHz waveform out. */
+export interface KokoroSession {
+    readonly synthesize: (ids: readonly number[], styleVector: Float32Array) => Promise<Float32Array>;
+}
+/**
+ * WHAT SPEAKING NEEDS OF KOKORO — `platform/kokoro-runtime` fills it from the delivery (ADR-0216 §1).
+ * `phonemize` is espeak-ng in the voice's language (`pt-br`, `es-419`, `en-us`, `en-gb`); `vocabulary` the model tokenizer's symbols;
+ * `voice` a voice's style table; `session` a session on WebGPU or WASM.
+ *
+ * 📌 IT LIVES IN THIS LEAF and not beside the speaking, so that the runtime that builds one can be reached from `platform/tts` by
+ * `import()` without the two naming each other — a cycle the direction gate (ADR-0173) refuses, and rightly: the loader must not
+ * have to load the speaker to be loaded by it.
+ */
+export interface KokoroModule {
+    readonly phonemize: (text: string, espeak: string) => Promise<string>;
+    readonly vocabulary: () => Promise<Readonly<{
+        [symbol: string]: number;
+    }>>;
+    readonly voice: (id: string) => Promise<Float32Array>;
+    readonly session: (device: 'webgpu' | 'wasm') => Promise<KokoroSession>;
+}
+/** How the neural voice arrives. Until ADR-0216 every game wrote one of these; now the engine has its own. */
+export type LoadKokoro = () => Promise<KokoroModule>;
+/** A Kokoro voice of the engine's three languages. `recommended` marks the two the Dev rated good (ADR-0198 §3). */
+export interface KokoroVoice extends NeuralVoice {
+    readonly engine: 'kokoro';
+    /** The espeak-ng voice that phonemizes this voice's text. */
+    readonly espeak: string;
+    readonly recommended: boolean;
+}
+/**
+ * Kokoro-82M v1.0's voices for Portuguese, Spanish and English, as the model repository lists them (read 2026-09-14). The model's
+ * first letter is the language — `p` Brazilian Portuguese, `e` Spanish, `a` American and `b` British English — and the second the
+ * voice's gender. The others (French, Hindi, Italian, Japanese, Chinese) are not the engine's languages.
+ */
+export declare const KOKORO_VOICES: readonly KokoroVoice[];
+export declare const KOKORO_MODEL_URL = "https://huggingface.co/onnx-community/Kokoro-82M-v1.0-ONNX/resolve/main/onnx/model.onnx";
+export declare const URL_DO_TOKENIZADOR_KOKORO = "https://huggingface.co/onnx-community/Kokoro-82M-v1.0-ONNX/resolve/main/tokenizer.json";
+export declare const kokoroVoiceUrl: (id: string) => string;
+/**
+ * Each voice file's SHA-256 and size, read from the repository's LFS metadata on 2026-09-14 (all 522 240 bytes); `pf_dora` also
+ * measured on the downloaded file. The model: 325 532 232 bytes, measured on the file. Checked before anything is kept (#168).
+ */
+export declare const KOKORO_VOICES_SHA256: Readonly<{
+    [id: string]: string;
+}>;
+export declare const KOKORO_VOICE_BYTES = 522240;
+export declare const KOKORO_MODEL_SHA256 = "8fbea51ea711f2af382e88c833d9e288c6dc82ce5e98421ea61c058ce21a34cb";
+export declare const KOKORO_MODEL_BYTES = 325532232;
+export declare const SHA256_DO_TOKENIZADOR_KOKORO = "77a02c8e164413299b4b4c403b14f8e0e1c1b727db4d46a09d6327b861060a34";
+export declare const BYTES_DO_TOKENIZADOR_KOKORO = 3497;
+/** The model's context: ids between the two pad tokens. A longer sentence is cut here (the caller splits text by sentence). */
+export declare const MAX_KOKORO_TOKENS = 510;
+/** A voice file is a table of style rows, one per token count, 256 numbers each. */
+export declare const STYLE_DIMENSION = 256;
+/** The token ids of a phoneme string: each symbol the vocabulary knows, in order, between two pad tokens (id 0). */
+export declare function tokenize(phonemes: string, symbolIds: Readonly<{
+    [symbol: string]: number;
+}>): number[];
+/** The style row a sentence of `tokens` ids (pads excluded) takes from a voice table. */
+export declare function sentenceStyle(styleTable: Float32Array, tokens: number): Float32Array;
+/**
+ * Is a synthesis speech? Measured on 2026-09-14: WebGPU on one AMD GPU gave a waveform whose samples ran to 2×10⁷ — noise a child
+ * would hear as a burst. A speech waveform stays within ±1 (a sample or two past it is clipping, not noise) and is not silent.
+ */
+export declare function eFala(waveform: ArrayLike<number>): boolean;
+/** A 16-bit mono PCM WAV of a waveform, clipped to ±1 — what the narration's media element plays. */
+export declare function wavDe(waveform: ArrayLike<number>, sampleRate?: number): ArrayBuffer;