@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/platform/heavy.js

@@ -0,0 +1,324 @@
+// 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, DELIVERY_LISTS, readingLanguageOf, commandsLanguageOf, } from './heavy-catalogue.js';
+export { CACHE_HEAVY, HEAVY_FILES };
+/**
+ * Who waits behind whom inside one language's position (`heavyAtBoot`): 0 the ways in (the command models and runtime, the
+ * camera's reader), 1 the reading and the graph runtime it opens its models with, 2 the rest — the neural voice, which the
+ * browser's voice covers until it lands.
+ */
+function waitsBehind(id) {
+    if (id.startsWith('commands:') || id.startsWith('visao:'))
+        return 0;
+    if (id.startsWith('reading:') || id.startsWith('voz:runtime:onnx'))
+        return 1;
+    return 2;
+}
+/**
+ * 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, one per language (850 MiB for the three): `reading` is a language or a LIST of them, like `commands`, and
+ *   the root asks for every language the page can switch to, the child's first (ADR-0225 erratum, the Dev: «Negativo, baixar os
+ *   três. Toda criança vai experimentar as três línguas imediatamente.»). A language the delivery's `--reading` list left out is a
+ *   quiet 404 here and, when she reads in it, a line of `problems` and a sentence to her. 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, 108 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). `commands` is a language or a LIST of them, and the models come in the list's order: the root asks for
+ *   every language the page can switch to, the child's first, because a language changed mid-game must find its model already
+ *   kept (ADR-0225 erratum, the Dev: «A entrega leva as três línguas.»). The delivery carries the three unless its
+ *   `--commands` list narrows it; a language it did not carry is a quiet 404 here and a line of `problems` when she speaks.
+ * · The Libras player (ADR-0234): the delivery's list of its avatar, clips, glosses and three.js chunk (34.9 MB in the engine's
+ *   delivery), only with `libras`: the root asks for it while deaf mode is on, so a device whose child never asks for signing
+ *   never downloads it. No game declares it either — deaf mode is the person's (ADR-0111) — and a delivery built without
+ *   `--libras` simply has none, the same quiet 404 as a missing command model. No catalogue file is the player's: it is all the
+ *   delivery's own, kept by what the delivery carries.
+ * The ids are the catalogue's files, then the delivery lists (`DELIVERY_LISTS`), by one rule.
+ *
+ * 🔴 THE ORDER IS WHO WAITS, because the download is one file at a time (rule 1): a file of a language takes that language's
+ * position in the list it was asked by, a file of no language (the runtimes, vision) takes the first, and the sort is stable. So
+ * everything of the child's language comes first, then each other language whole — her command model never waits behind 470 MiB
+ * of another language's reading.
+ * 🔴 AND WITHIN A POSITION, THE WAYS IN COME FIRST (`waitsBehind`): the command models and the camera's reader are how a child
+ * who does not press reaches the game at all (ADR-0111), and they have nothing to fall back on; the reading is the game's own
+ * listening, with nothing either; the neural voice comes last, because the browser's voice speaks meanwhile (ADR-0200). 📏 In
+ * the catalogue's order a 👄 turned on in a fresh install waited behind 336 MiB of neural voice and 378 MiB of reading for a
+ * 34 MiB model — seven seconds from a local disk, minutes on a school's link (measured on 2026-09-27).
+ */
+export function heavyAtBoot(declared) {
+    const reading = languagesAsked(declared.reading);
+    const commands = languagesAsked(declared.commands);
+    const asked = (id) => {
+        const language = readingLanguageOf(id);
+        if (language)
+            return reading.includes(language);
+        // 📌 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 LANGUAGES are
+        // still asked, and the runtime comes with whichever one is.
+        const commanded = commandsLanguageOf(id);
+        if (commanded)
+            return commands.includes(commanded);
+        if (id.startsWith('commands:runtime'))
+            return commands.length > 0;
+        if (id.startsWith('libras:'))
+            return !!declared.libras;
+        if (id.startsWith('voz:runtime:onnx'))
+            return declared.kokoro || reading.length > 0;
+        return declared.kokoro || !(id.startsWith('voz:kokoro:') || id.startsWith('voz:runtime:'));
+    };
+    const rank = (id) => {
+        const read = readingLanguageOf(id);
+        if (read)
+            return reading.indexOf(read);
+        const spoken = commandsLanguageOf(id);
+        return spoken ? commands.indexOf(spoken) : 0;
+    };
+    return [
+        // `Array.prototype.sort` is stable (ES2019): within a position and a kind, the catalogue's order — a runtime before its model
+        ...HEAVY_FILES.map((p) => p.id).filter(asked).sort((a, b) => rank(a) - rank(b) || waitsBehind(a) - waitsBehind(b)),
+        ...DELIVERY_LISTS.map((l) => l.id).filter(asked),
+    ];
+}
+/** The base languages asked — one tag or a list of them — without repeats, in the order asked (`es-MX` asks for `es`). */
+function languagesAsked(asked) {
+    const tags = asked == null ? [] : typeof asked === 'string' ? [asked] : asked;
+    return [...new Set(tags.filter(Boolean).map((tag) => tag.split('-')[0].toLowerCase()))];
+}
+/**
+ * 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.
+ *
+ * The files handed in `also` come first (the declared library fonts), then the catalogue's, then the delivery's lists
+ * (`DELIVERY_LISTS`), each list ONE report for all its files.
+ */
+export async function downloadHeavy(options) {
+    const targets = [...(options.also ?? []), ...(options.only
+            ? [...new Set(options.only)].flatMap((id) => HEAVY_FILES.filter((p) => p.id === id))
+            : HEAVY_FILES)];
+    const lists = DELIVERY_LISTS.filter((l) => !options.only || options.only.includes(l.id));
+    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, ...lists])
+            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));
+    for (const l of lists)
+        record(await keepListed(l, 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 header a file kept from a delivery's list carries its listed sha256 in: how a later start knows it is kept, and current. */
+const LISTED_SHA256 = 'x-inclusionist-sha256';
+/**
+ * The files a delivery's list names, or a THROW saying why the list is refused whole: a list with no `files`, an entry without a
+ * path or a sha256, or one whose address falls outside the list's folders (a `..`, another origin, a query) — the list may only
+ * put the player's own files in the checked cache, never the game's page nor anything a route outside those folders serves.
+ */
+function listedFiles(data, l, base) {
+    const files = data?.files;
+    if (!Array.isArray(files))
+        throw new Error('its `files` is missing');
+    const folders = l.folders.map((folder) => new URL(folder, base).href);
+    return files.map((f) => {
+        const { path, sha256 } = (f ?? {});
+        if (typeof path !== 'string' || typeof sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(sha256)) {
+            throw new Error(`a listed file is malformed: ${JSON.stringify(f)}`);
+        }
+        const at = new URL(path, base);
+        const url = at.href;
+        if (at.search || at.hash || !folders.some((folder) => url.startsWith(folder) && url.length > folder.length)) {
+            throw new Error(`it names ${path}, outside ${l.folders.join(' and ')}`);
+        }
+        return { path, url, sha256 };
+    });
+}
+/**
+ * A DELIVERY'S LIST, KEPT FILE BY FILE (ADR-0234, pillar 8): the list is read from the page's origin, and each file it names is
+ * fetched from there, CHECKED against its listed sha256, and kept under its own address, where the service worker answers it
+ * offline. A file already kept with that sha256 is not fetched again; a body that is not the listed one is never kept, and the
+ * report names it. One report for the list: `baixado` with the bytes fetched, `ja-tinha`, or `falhou` with the files refused.
+ */
+async function keepListed(l, t) {
+    const failed = (error) => ({ id: l.id, outcome: 'falhou', error });
+    const digest = t.digest;
+    if (!digest)
+        return failed('this host cannot compute a sha256 (crypto.subtle needs a secure context)');
+    const files = await readList(l, t);
+    if (typeof files === 'string')
+        return failed(files);
+    const refused = [];
+    let bytes = 0;
+    let fetched = 0;
+    for (const f of files) {
+        const kept = await keepListedFile(f, t, digest);
+        if (typeof kept === 'string')
+            refused.push(`${f.path}: ${kept}`);
+        else if (kept !== null) {
+            bytes += kept;
+            fetched += 1;
+        }
+    }
+    if (!refused.length)
+        return fetched ? { id: l.id, outcome: 'baixado', bytes } : { id: l.id, outcome: 'ja-tinha' };
+    const more = refused.length > 5 ? `; and ${refused.length - 5} more` : '';
+    return failed(`${refused.length} of ${files.length} files of ${l.path} not kept: ${refused.slice(0, 5).join('; ')}${more}`);
+}
+/** The list's files, or why it is refused whole (not there, not JSON, or naming what it may not). */
+async function readList(l, t) {
+    try {
+        // never an old copy of the list: it is what says which files are current
+        const resp = await t.fetchFile(new URL(l.path, t.base).href, { cache: 'no-store' });
+        if (!resp.ok)
+            return `HTTP ${resp.status} — ${l.path}`;
+        return listedFiles(await resp.json(), l, t.base);
+    }
+    catch (e) {
+        return `the list ${l.path} is refused: ${e instanceof Error ? e.message : String(e)}`;
+    }
+}
+/** One listed file: `null` when it is already kept with its listed hash, the bytes kept, or why it was not kept. */
+async function keepListedFile(f, t, digest) {
+    try {
+        if ((await t.cache.match(f.url))?.headers.get(LISTED_SHA256) === f.sha256)
+            return null;
+        /*
+         * 📌 THE LISTED HASH GOES IN THE QUERY: the service worker answers these folders from this cache by their address, so a file
+         * the list CHANGED would be answered with the copy it replaces. Another address reaches the delivery, and the old copy stays
+         * kept until the new one is checked — offline a child keeps the player she had.
+         */
+        const resp = await t.fetchFile(`${f.url}?sha256=${f.sha256}`);
+        if (!resp.ok)
+            return `HTTP ${resp.status}`;
+        const body = await resp.arrayBuffer();
+        const got = await digest(body);
+        if (got !== f.sha256)
+            return `sha256 mismatch: expected ${f.sha256}, got ${got} — not kept`;
+        const headers = new Headers(resp.headers);
+        headers.set(LISTED_SHA256, f.sha256);
+        await t.cache.put(f.url, new Response(body, { status: resp.status, statusText: resp.statusText, headers }));
+        return body.byteLength;
+    }
+    catch (e) {
+        return e instanceof Error ? e.message : String(e);
+    }
+}
+/**
+ * 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,26 @@
 // 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. `Request` is what one utterance
+ * asks for: a text by default, or a text with the voice that reads it (ADR-0243 §2).
+ */
+export interface SpeechEngine<Audio, Fonte, Request = string> {
+    /** Request → audio. ASYNCHRONOUS on purpose: it is where neural synthesis spends its time. */
+    synthesize(request: Request): 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<Request = string> {
+    /**
+     * Speaks `request`, SILENCING at once whatever is speaking. It does not queue: the latest request is the one that counts.
+     * `finished` is called ONCE, when this utterance is over for any reason — it ended, it was silenced or overtaken, or it could
+     * not be synthesised or played — so a caller speaking parts in order (ADR-0243 §1) knows when to go on, and never waits forever.
+     */
+    speak(request: Request, finished?: () => void): 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, Request = string>(engine: SpeechEngine<Audio, Fonte, Request>): InterruptibleSpeech<Request>;

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

@@ -1,79 +1,102 @@
 // 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 nowFinished = 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;
         }
+        const finished = nowFinished;
+        nowFinished = null;
+        finished?.();
     }
-    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(request, finished) {
+        const myTurn = ++currentTurn; // claims the turn BEFORE any wait
+        stopPlayback(); // guarantee 1: immediate silence, not at the end of synthesis
+        if (!request) {
+            finished();
             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) {
-                    try {
-                        motor.parar(fonte);
-                    }
-                    catch (e) { /* noop */ }
+            const audio = await engine.synthesize(request);
+            if (myTurn !== currentTurn) {
+                finished();
+                return;
+            } // guarantee 2: it arrived late — another request already took over
+            stopPlayback(); // again: something may have started playing during the wait
+            const playing = engine.play(audio, () => {
+                if (nowPlaying === playing) {
+                    nowPlaying = null;
+                    nowFinished = null;
+                }
+                finished();
+            });
+            if (playing === null) {
+                finished();
+                return;
+            }
+            if (myTurn !== currentTurn) {
+                try {
+                    engine.stop(playing);
                 }
+                catch (e) { /* noop */ }
+                finished();
                 return;
             }
-            tocando = fonte;
+            nowPlaying = playing;
+            nowFinished = finished;
         }
         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.
+            finished();
         }
     }
+    /** Calls `finished` at most once, whichever of the ends above comes first. */
+    const once = (finished) => {
+        let called = false;
+        return () => { if (called)
+            return; called = true; finished?.(); };
+    };
     return {
-        falar: (texto) => { void falar(texto); },
-        calar: () => { geracao++; pararTudo(); }, // o `++` invalida o que estiver sintetizando agora
-        falando: () => tocando !== null,
+        speak: (request, finished) => { void speakNow(request, once(finished)); },
+        silence: () => { currentTurn++; stopPlayback(); }, // the `++` invalidates whatever is being synthesised now
+        speaking: () => nowPlaying !== null,
     };
 }

package/dist-pkg/platform/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>;