@the-inclusionist/engine 9.0.0 → 10.0.0

package/dist-pkg/platform/kokoro.js

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+const voiceEntry = (id, locale, espeak, isRecommended = false) => Object.freeze({ locale, engine: 'kokoro', voice: id, espeak, recommended: isRecommended });
+/**
+ * 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 const KOKORO_VOICES = Object.freeze([
+    voiceEntry('pf_dora', 'pt-BR', 'pt-br'), voiceEntry('pm_alex', 'pt-BR', 'pt-br'), voiceEntry('pm_santa', 'pt-BR', 'pt-br'),
+    voiceEntry('ef_dora', 'es', 'es-419'), voiceEntry('em_alex', 'es', 'es-419'), voiceEntry('em_santa', 'es', 'es-419'),
+    voiceEntry('af_heart', 'en-US', 'en-us', true), voiceEntry('af_bella', 'en-US', 'en-us', true),
+    ...['af_alloy', 'af_aoede', 'af_jessica', 'af_kore', 'af_nicole', 'af_nova', 'af_river', 'af_sarah', 'af_sky',
+        'am_adam', 'am_echo', 'am_eric', 'am_fenrir', 'am_liam', 'am_michael', 'am_onyx', 'am_puck', 'am_santa'].map((id) => voiceEntry(id, 'en-US', 'en-us')),
+    ...['bf_alice', 'bf_emma', 'bf_isabella', 'bf_lily', 'bm_daniel', 'bm_fable', 'bm_george', 'bm_lewis'].map((id) => voiceEntry(id, 'en-GB', 'en-gb')),
+]);
+/**
+ * WHERE KOKORO COMES FROM, in one place (ADR-0114's rule for hosts): the model repository the catalogue fetches at build time; the
+ * delivery serves the same paths from its own origin (ADR-0177), and a game's port asks for them there.
+ */
+const KOKORO_REPOSITORY = 'https://huggingface.co/onnx-community/Kokoro-82M-v1.0-ONNX/resolve/main';
+export const KOKORO_MODEL_URL = `${KOKORO_REPOSITORY}/onnx/model.onnx`;
+export const URL_DO_TOKENIZADOR_KOKORO = `${KOKORO_REPOSITORY}/tokenizer.json`;
+export const kokoroVoiceUrl = (id) => `${KOKORO_REPOSITORY}/voices/${id}.bin`;
+/**
+ * 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 const KOKORO_VOICES_SHA256 = Object.freeze({
+    pf_dora: '3da7b5b2d91847ebf5646f57631af6ececae3c29a89cd300f06edf9aa6cfe9ee',
+    pm_alex: '0175c753f59c54e7fd5a995bedef0c5ff2fb67e0043dd3dcb2ae74ec2acbeb2a',
+    pm_santa: '8b012db3185778afe2e45a62cbad69db73021774fe68dda634bcc748a982eede',
+    ef_dora: 'f66ec66bd295acb18372e37008533a9a3228483ccd294e7538d5d9294ac9a532',
+    em_alex: '27809e9eafdcbcfff90a3016c697568676531de2a2c39cee29c96c7bd6b83e95',
+    em_santa: 'ad43b774e1ca24d05c6161297d8aeb770ac3d29bb95daf516727af5f7d543683',
+    af_heart: 'd583ccff3cdca2f7fae535cb998ac07e9fcb90f09737b9a41fa2734ec44a8f0b',
+    af_bella: 'f69d836209b78eb8c66e75e3cda491e26ea838a3674257e9d4e5703cbaf55c8b',
+    af_alloy: 'c4a6b876047fd7fb472edf4ebd63cfac7c3b958a7cae7c106e8f038ca6308c45',
+    af_aoede: '4a004c33430762e2461eedb2013fad808ef4ab3121f5300f554476caf58d8361',
+    af_jessica: 'a240a5e3c15b43563d6e923bdca8ef5613a23471d9b77653694012435df23bd8',
+    af_kore: '9be5221b6a941c04b561959b8ff0b06e809444dcc4ab7e75a7b23606f691819e',
+    af_nicole: 'cd2191ab31b914ed7b318416b0e4440fdf392ddad9106a060819aa600a64f59a',
+    af_nova: '18778272caa0d0eebaea251c35fd635f038434f9eee5e691d02a174bd328414f',
+    af_river: '00a2bcf82b1d86e8f19902ede58c65ccf6c0e43b44b7d74fad54e5d8933c9c30',
+    af_sarah: '4409fbc125afabacc615d94db5398d847006a737b0247d6892b7a9a0007a2f0a',
+    af_sky: '4435255c9744f3f31659e0d714ab7689bf65d9e77ec1cce060f083912614f0b9',
+    am_adam: '162b035ed91cfc48b6046982184c645f72edcdd1b82843347f605d7bf7b15716',
+    am_echo: '3968b92c3c4cd1c4416dbded36c13eaa388a90d5788d02a13e4d781f5f8cf3c3',
+    am_eric: 'e8b5be17edd1e3636901ce7598baafe2dc8dd8ff707a0c23bf9e461add7e2832',
+    am_fenrir: 'c27989f741f7ee34d273a39d8a595cc0837d35f5ced9a29b7cc162614616df43',
+    am_liam: '52403be32fd047c6a44517cb0bcd6b134f2a18baa73e70ef41651e0eab921ade',
+    am_michael: '1d1f21dd8da39c30705cd4c75d039d265e9bc4a2a93ed09bc9e1b1225eb95ba1',
+    am_onyx: 'da5d135b424164916d75a68ffb4c2abce3d7d5ccc82dd1ee6cf447ce286145e6',
+    am_puck: 'fcf73c989033e9233e0b98713eca600c8c74dcc1614b37009d5450ff4a2274a0',
+    am_santa: '61150cf726ab6c5ed7a99f90a304f91f5a72c00c592e89ec94e5df11c319227a',
+    bf_alice: '08afa6ba24da61ea5e8efa139e5aadc938d83f0a6da5a900adaf763ac1da5573',
+    bf_emma: '669fe0647f9dd04fcab92f1439a40eeb4c8b4ab1f82e4996fe3d918ce4a63b73',
+    bf_isabella: '3754352c4aaa46d17f27654ab7518d65b62ad6163a0f55a5f4330c2da2c4e94f',
+    bf_lily: '5e0ee32ebe64a467124976b14e69590746f1c4ce41a12b587a50c862edfea335',
+    bm_daniel: '6b3194bbceffb746733cbc22c8f593dd44e401a71d53895a2dca891bc595a1e8',
+    bm_fable: 'f889083196807b4adb15e9204252165f503b8d33d3982e681c52443c49d798f1',
+    bm_george: 'c4b235a4c1f2cd3b939fed08b899ce9385638b763f7b73a59616c4fc9bd6c9bc',
+    bm_lewis: 'b8f671cef828c30e66fdf0b0756a76bba58f6bb3398cbbf27058642acbcedb97',
+});
+export const KOKORO_VOICE_BYTES = 522_240;
+export const KOKORO_MODEL_SHA256 = '8fbea51ea711f2af382e88c833d9e288c6dc82ce5e98421ea61c058ce21a34cb';
+export const KOKORO_MODEL_BYTES = 325_532_232;
+export const SHA256_DO_TOKENIZADOR_KOKORO = '77a02c8e164413299b4b4c403b14f8e0e1c1b727db4d46a09d6327b861060a34';
+export const BYTES_DO_TOKENIZADOR_KOKORO = 3_497;
+/** The model's context: ids between the two pad tokens. A longer sentence is cut here (the caller splits text by sentence). */
+export const MAX_KOKORO_TOKENS = 510;
+/** A voice file is a table of style rows, one per token count, 256 numbers each. */
+export const STYLE_DIMENSION = 256;
+const KOKORO_SAMPLE_RATE = 24_000;
+/** The token ids of a phoneme string: each symbol the vocabulary knows, in order, between two pad tokens (id 0). */
+export function tokenize(phonemes, symbolIds) {
+    const ids = [];
+    for (const symbol of phonemes) {
+        const id = symbolIds[symbol];
+        if (id !== undefined)
+            ids.push(id);
+        if (ids.length === MAX_KOKORO_TOKENS)
+            break;
+    }
+    return [0, ...ids, 0];
+}
+/** The style row a sentence of `tokens` ids (pads excluded) takes from a voice table. */
+export function sentenceStyle(styleTable, tokens) {
+    const rowCount = Math.floor(styleTable.length / STYLE_DIMENSION);
+    const row = Math.max(0, Math.min(rowCount - 1, tokens));
+    return styleTable.slice(row * STYLE_DIMENSION, (row + 1) * STYLE_DIMENSION);
+}
+/**
+ * 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 function eFala(waveform) {
+    if (waveform.length === 0)
+        return false;
+    let outside = 0, energy = 0;
+    for (let i = 0; i < waveform.length; i++) {
+        const s = waveform[i];
+        if (!Number.isFinite(s))
+            return false;
+        if (Math.abs(s) > 1.5)
+            outside++;
+        energy += s * s;
+    }
+    return outside === 0 && Math.sqrt(energy / waveform.length) > 1e-3;
+}
+/** A 16-bit mono PCM WAV of a waveform, clipped to ±1 — what the narration's media element plays. */
+export function wavDe(waveform, sampleRate = KOKORO_SAMPLE_RATE) {
+    const n = waveform.length;
+    const buf = new ArrayBuffer(44 + n * 2);
+    const v = new DataView(buf);
+    const text = (o, s) => { for (let i = 0; i < s.length; i++)
+        v.setUint8(o + i, s.charCodeAt(i)); };
+    text(0, 'RIFF');
+    v.setUint32(4, 36 + n * 2, true);
+    text(8, 'WAVE');
+    text(12, 'fmt ');
+    v.setUint32(16, 16, true);
+    v.setUint16(20, 1, true);
+    v.setUint16(22, 1, true);
+    v.setUint32(24, sampleRate, true);
+    v.setUint32(28, sampleRate * 2, true);
+    v.setUint16(32, 2, true);
+    v.setUint16(34, 16, true);
+    text(36, 'data');
+    v.setUint32(40, n * 2, true);
+    for (let i = 0; i < n; i++)
+        v.setInt16(44 + i * 2, Math.round(Math.max(-1, Math.min(1, waveform[i])) * 32767), true);
+    return buf;
+}

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

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** A window that remembers what was hung on it, so it can be taken down. */
+export interface ListenerScope {
+    /** The window to hand around. Identical to the real one, except that its listeners are remembered. */
+    readonly win: Window;
+    /**
+     * Takes off every listener still installed through `win`. Idempotent: what was already removed by hand, or removed itself
+     * (`once: true`), is simply no longer there — removing a listener that is not installed is a no-op in the DOM.
+     */
+    releaseAll(): void;
+}
+export declare function createListenerScope(real: Window): ListenerScope;

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

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/listener-scope — A WINDOW THAT CAN BE LET GO.
+//
+// 🔴 WHY THIS EXISTS, AND IT IS A DEFECT THAT WAS MEASURED, NOT A TIDINESS. A root (`boot/create-game`) installs about thirty
+// listeners on the window — the scan interception, START, SELECT, `action4`, the resize, the language change, and the five that
+// `ui/menu-nav.attach()` puts there — AND THERE WAS NO WAY TO TAKE THEM OFF. `unmount()` is not that way and must not become it:
+// it releases the CURRENT CARTRIDGE (ADR-0142), and a root that went deaf on `unmount()` would come back from the next `mount()`
+// with no keyboard at all.
+//
+// 📏 What that cost, measured in the browser with the real engine: a root whose host element was removed from the document KEEPS
+// LISTENING, and every query it makes is document-wide (`getPauseMenu` is `doc.querySelector('#vp-pause-0')`,
+// `topVisibleOverlay` is `doc.querySelectorAll('#game-region .overlay')`) — so the dead root finds THE LIVE ROOT'S pause card and
+// navigates it too. One ArrowDown moved the cursor one item with one root, TWO with a second root, THREE with a third. Nobody
+// gets an error: the child presses down once and the cursor jumps two.
+//
+// ⚠️ AND `stopPropagation()` SAVES NOBODY HERE. Every one of these listeners sits on the SAME node in the SAME phase, and
+// stopping propagation does not stop the siblings on that node — only `stopImmediatePropagation()` would, and using it would mean
+// the first root to be built silences every other one, which is a worse rule than the bug.
+//
+// 🎯 THE SHAPE: one seam instead of a `detach()` in each of the seven modules that listen. The root wraps the window ONCE and
+// hands the WRAPPER down; every listener installed through it — by the root or by any module it builds — is remembered, and
+// `releaseAll()` takes all of them off at once. A module that learns to listen tomorrow is covered without being edited, which a
+// list of `detach()` calls could never promise: the one that is forgotten is the one that leaks.
+//
+// 📌 Everything else about the window is UNCHANGED. `getComputedStyle`, `requestAnimationFrame`, `matchMedia`, `innerWidth` and
+// the rest answer exactly as the real window does — this is a window with a memory, not a window with a smaller API.
+const captureOf = (o) => (typeof o === 'boolean' ? o : !!o?.capture);
+export function createListenerScope(real) {
+    const installed = [];
+    // A released scope is ended: a listener armed before the end and added after it (a timer) must not reach the window.
+    let released = false;
+    const listen = (type, listener, options) => {
+        if (released)
+            return;
+        real.addEventListener(type, listener, options);
+        installed.push({ type, listener, capture: captureOf(options), options });
+    };
+    const forget = (type, listener, options) => {
+        real.removeEventListener(type, listener, options);
+        const capture = captureOf(options);
+        const i = installed.findIndex((e) => e.type === type && e.listener === listener && e.capture === capture);
+        if (i >= 0)
+            installed.splice(i, 1);
+    };
+    /*
+     * ⚠️ WHAT LEAVES THIS TRAP IS ANSWERED BY THE REAL WINDOW, NEVER BY THE PROXY, and it is not style: `innerWidth`,
+     * `devicePixelRatio` and `location` are GETTERS on the window, and `getComputedStyle`, `requestAnimationFrame` and
+     * `matchMedia` are methods of it — run any of them with the proxy as `this` and the browser answers «Illegal invocation».
+     * So the receiver is left at its default (which IS the target) and every function is bound before it goes out.
+     *
+     * 📌 Both halves are exercised, by mutation: forwarding the proxy as the receiver kills the whole collection at load, and
+     * dropping the `bind` kills it at the first `getComputedStyle`.
+     *
+     * 🔴 BUT A CONSTRUCTOR LEAVES UNBOUND, and this was not foreseen — the suite found it. `bind` returns a function with NO
+     * `prototype`, and code that reaches a constructor THROUGH the window reads that prototype: `platform/speech-recognition`
+     * asks `'processLocally' in api.prototype` before it will use the browser's recogniser on the device, and bound, that read is
+     * `in undefined`. 📏 Measured: `tests/reading-no-createGame.browser.test.js` went red — the child who reads aloud got no
+     * microphone at all. A constructor never needs `this` from the property access; a method always does, and `prototype` is the
+     * one thing that tells the two apart.
+     */
+    const win = new Proxy(real, {
+        get(target, prop) {
+            if (prop === 'addEventListener')
+                return listen;
+            if (prop === 'removeEventListener')
+                return forget;
+            const value = Reflect.get(target, prop);
+            if (typeof value !== 'function')
+                return value;
+            return Object.hasOwn(value, 'prototype') ? value : value.bind(target);
+        },
+    });
+    const releaseAll = () => {
+        released = true;
+        // Drained as it goes: a listener that took another off while being removed would otherwise make this skip one, and a scope
+        // released twice must not try to take the same listener off again.
+        for (const e of installed.splice(0))
+            real.removeEventListener(e.type, e.listener, e.options);
+    };
+    return { win, releaseAll };
+}

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

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

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

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/locale-host — WHAT A PAGE DOES WHEN THE LANGUAGE CHANGES, and what language it would prefer (ADR-0221 step 7g).
+//
+// 🔴 WHY THIS MODULE EXISTS: `core/i18n` used to write `document.documentElement.lang`, dispatch `i18n:change` on `window`,
+// read `navigator.language` and hang itself on `window.__i18n` — four reaches into globals from `core`, which ADR-0173
+// defines as «what the engine IS, without a browser». The health ratchet measured them (step 7d) and the Dev chose to SPLIT
+// rather than to move the module (option B, 2026-09-22): the decisions — which languages exist, which one is kept, what a
+// key resolves to — stay in `core`, and the three things only a page can do live here.
+//
+// 📌 WHY NOT INJECT AND LEAVE IT AT THAT, which was the cheaper option C: the sentence «core is what the engine is, without a
+// browser» would have stayed a rule with an exception nobody reads. 📏 The cost measured before choosing was 8 sites; this
+// module is what those 8 became.
+//
+// ⚠️ It touches `document` and `window` ON PURPOSE and that is why it is `platform/`: this is the layer whose job is the
+// browser. What it must never do is decide anything about language — it receives the locale and the tag already chosen.
+/** What a browser can offer `core/i18n`: the page effects of a change, and the language the person's browser is set to. */
+export function localeHostHooks(doc, win, applyDom) {
+    return {
+        applied: (locale, tag) => {
+            // 📌 THE THREE EFFECTS IN THE ORDER THEY WERE WRITTEN IN `core/i18n`, and the order matters to a screen reader: the
+            // document's language is announced before the text it governs changes.
+            doc.documentElement.lang = tag;
+            applyDom(doc);
+            win.dispatchEvent(new CustomEvent('i18n:change', { detail: { locale } }));
+        },
+        // ⚠️ `navigator` through the window, not the global: a host that hands the engine another window — a second document, an
+        // iframe — means that window's language, and reading the global would silently answer for the wrong one.
+        preferred: () => win.navigator?.language ?? null,
+    };
+}
+/** Hangs the i18n object on the window for tests and the preview, which is what `core/i18n` used to do to itself. */
+export function exposeI18n(win, i18n) {
+    win.__i18n = i18n;
+}

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

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** The part of the Web Audio API this uses — narrow on purpose, so a case can answer it without a browser. */
+export interface AudioNodeLike {
+    connect(to: unknown): void;
+    disconnect(): void;
+}
+export interface ProcessorNode extends AudioNodeLike {
+    onaudioprocess: ((e: {
+        inputBuffer: {
+            getChannelData(ch: number): Float32Array;
+        };
+    }) => void) | null;
+}
+export interface AudioContextLike {
+    readonly sampleRate: number;
+    readonly destination: unknown;
+    createMediaStreamSource(stream: unknown): AudioNodeLike;
+    createScriptProcessor(bufferSize: number, inputs: number, outputs: number): ProcessorNode;
+    close(): Promise<void> | void;
+}
+/** A stream, in the one thing that matters after the reading: letting go of it. */
+export interface StreamLike {
+    getTracks(): readonly {
+        stop(): void;
+    }[];
+}
+/** What the microphone uses of the browser, lent by the root from the host's window (ADR-0232 D4). All REQUIRED. */
+export interface MicrophoneDeps {
+    /** The host's `navigator.mediaDevices.getUserMedia`. `undefined` is a device with no microphone: REFUSED and said, not hidden. */
+    readonly getUserMedia: ((constraints: {
+        audio: boolean;
+    }) => Promise<StreamLike>) | undefined;
+    /** A new audio context at this rate, from the host's `AudioContext`. */
+    readonly createContext: (rate: number) => AudioContextLike;
+    /** The host's clock, `performance.now()`: what the silence and the ceiling are measured against. */
+    readonly now: () => number;
+}
+export interface RecordOptions {
+    /** How long a silence ends the reading. Default 1.5 s: shorter cuts a child who is thinking between words. */
+    readonly silenceMs?: number;
+    /** The ceiling, so a forgotten microphone does not listen for ever. Default 30 s, the window Whisper reads at once. */
+    readonly maxMs?: number;
+}
+export interface Microphone {
+    /** Listens, and answers with what was said, at 16 kHz mono. */
+    record(options?: RecordOptions): Promise<Float32Array>;
+    /** Gives the microphone back now; the recording in hand answers with what it has. */
+    stop(): void;
+}
+export declare const READING_RATE = 16000;
+export declare function createMicrophone(d: MicrophoneDeps): Microphone;

package/dist-pkg/platform/microphone.js

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/microphone — THE CHILD'S VOICE, AND NOTHING ELSE (ADR-0216 §2, ADR-0200 erratum; issues #185, #200).
+//
+// The reading model eats 16 kHz mono samples. This is where they come from, and it is the only place in the engine that opens a
+// microphone for reading: what it captures stays in this page, is handed to the model on this machine, and is dropped when the
+// reading ends (ADR-0200's erratum: on the device or not at all).
+//
+// · IT ENDS WHEN THE CHILD DOES. A reading closes after `silenceMs` of quiet FOLLOWING something that was said, or at the `maxMs`
+//   ceiling, whichever comes first. A child who stops mid-sentence is not an error: what was heard so far is the answer.
+// · «QUIET» IS MEASURED, NOT ASSUMED. The first moments are taken as the room she is in, and sound is what stands above it —
+//   a fixed threshold would end a whispering child's reading in a noisy classroom, and never end in a quiet one.
+// · ⚠️ IT USES `ScriptProcessorNode`, which is deprecated. The replacement, an AudioWorklet, needs its code fetched as a module,
+//   and the engine's CSP has no `blob:` in `script-src` since ADR-0214 — so the modern way would need a new file in every
+//   delivery and a decision about serving it. This one works everywhere the project targets today, and it is written here so the
+//   next person does not «fix» it without that decision.
+export const READING_RATE = 16_000;
+const SILENCE_MS = 1500;
+const MAX_MS = 30_000;
+const BUFFER = 4096;
+/** How much of the start is taken as «the room»: long enough to be a room, short enough not to swallow a first word. */
+const ROOM_MS = 300;
+/** How far above the room a sound must be to be a voice, and the floor under it for a digitally silent input. */
+const OVER_ROOM = 4;
+const QUIETEST = 0.005;
+const rms = (block) => {
+    let sum = 0;
+    for (const v of block)
+        sum += v * v;
+    return Math.sqrt(sum / (block.length || 1));
+};
+/** 16 kHz from whatever the device gave us. Linear, because what follows is a mel filterbank, not a listener. */
+function atReadingRate(samples, from) {
+    if (from === READING_RATE)
+        return samples;
+    const out = new Float32Array(Math.round((samples.length * READING_RATE) / from));
+    const step = from / READING_RATE;
+    for (let i = 0; i < out.length; i++) {
+        const at = i * step;
+        const left = Math.floor(at);
+        const right = Math.min(left + 1, samples.length - 1);
+        out[i] = samples[left] + (samples[right] - samples[left]) * (at - left);
+    }
+    return out;
+}
+export function createMicrophone(d) {
+    const { now } = d;
+    let askToStop = null;
+    return {
+        stop() { askToStop?.(); },
+        async record(options = {}) {
+            const { getUserMedia } = d;
+            if (!getUserMedia)
+                throw new Error('microphone: this device offers none, so a reading cannot be heard here');
+            const makeContext = d.createContext;
+            const silenceMs = options.silenceMs ?? SILENCE_MS;
+            const maxMs = options.maxMs ?? MAX_MS;
+            const stream = await getUserMedia({ audio: true });
+            const context = makeContext(READING_RATE);
+            const source = context.createMediaStreamSource(stream);
+            const processor = context.createScriptProcessor(BUFFER, 1, 1);
+            const blocks = [];
+            const startedAt = now();
+            let room = 0, roomBlocks = 0, spoke = false, lastSound = startedAt, done = false;
+            return await new Promise((resolve) => {
+                const finish = () => {
+                    if (done)
+                        return;
+                    done = true;
+                    askToStop = null;
+                    processor.onaudioprocess = null;
+                    processor.disconnect();
+                    source.disconnect();
+                    // ⚠️ THE LIGHT GOES OUT. A track left running keeps the microphone open and the browser saying so, which to a child
+                    // and to whoever is with her means the game is still listening.
+                    for (const track of stream.getTracks())
+                        track.stop();
+                    void context.close();
+                    let total = 0;
+                    for (const b of blocks)
+                        total += b.length;
+                    const whole = new Float32Array(total);
+                    let at = 0;
+                    for (const b of blocks) {
+                        whole.set(b, at);
+                        at += b.length;
+                    }
+                    resolve(atReadingRate(whole, context.sampleRate));
+                };
+                askToStop = finish;
+                processor.onaudioprocess = (e) => {
+                    if (done)
+                        return;
+                    const block = Float32Array.from(e.inputBuffer.getChannelData(0));
+                    blocks.push(block);
+                    const level = rms(block);
+                    const elapsed = now() - startedAt;
+                    if (elapsed < ROOM_MS) {
+                        room = (room * roomBlocks + level) / (roomBlocks + 1);
+                        roomBlocks++;
+                        return;
+                    }
+                    if (level > Math.max(room * OVER_ROOM, QUIETEST)) {
+                        spoke = true;
+                        lastSound = now();
+                    }
+                    else if (spoke && now() - lastSound >= silenceMs) {
+                        finish();
+                        return;
+                    }
+                    if (elapsed >= maxMs)
+                        finish();
+                };
+                source.connect(processor);
+                processor.connect(context.destination);
+            });
+        },
+    };
+}

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

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+export interface OnnxTensor {
+    readonly data: unknown;
+    readonly dims?: readonly number[];
+}
+/** An open graph: the names it answers with, and one run. */
+export interface OnnxSession {
+    readonly inputNames?: readonly string[];
+    readonly outputNames: readonly string[];
+    run(inputs: {
+        readonly [name: string]: OnnxTensor;
+    }): Promise<{
+        readonly [name: string]: OnnxTensor;
+    }>;
+}
+/** The part of onnxruntime the engine uses — small on purpose: what is not named here cannot be depended on. */
+export interface OnnxRuntime {
+    readonly Tensor: new (type: 'int64' | 'float32' | 'bool', data: BigInt64Array | Float32Array | Uint8Array, shape: readonly number[]) => OnnxTensor;
+    readonly InferenceSession: {
+        create(model: Uint8Array, options: {
+            executionProviders: readonly string[];
+        }): Promise<OnnxSession>;
+    };
+}
+/** Where the delivery serves a catalogued file, from the page's own address. */
+export declare const atDelivery: (id: string, base: string) => string;
+export interface OnnxRuntimeDeps {
+    /** The page's address, which `heavy/` is resolved against. */
+    readonly base: string;
+    /** `import()`, injected so a case can hand in a module without a network or a wasm engine. */
+    readonly importModule?: (url: string) => Promise<unknown>;
+}
+/** The runtime, from the delivery, with its threads pointed at the delivery too. Refuses by NAME when it is not there. */
+export declare function loadOnnxRuntime(d: OnnxRuntimeDeps): Promise<OnnxRuntime>;

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

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/onnx-runtime — THE ONE GRAPH RUNNER, LOADED FROM THE DELIVERY (ADR-0216 and its erratum; issues #185, #200).
+//
+// Two things of the engine run an ONNX graph: the neural voice (`platform/kokoro-runtime`) and the reading
+// (`platform/reading-runtime`). They load the same runtime the same way, and that way has one rule nobody may forget, so it is
+// written here once and not in each of them.
+//
+// ⚠️ THE THREADS LOOK FOR THEIR OWN FILES. Left alone, onnxruntime's workers import their glue and their wasm from the address
+// the library was published at — a CDN — and in a school with no network they find nothing, never answer, and the page waits for
+// a session that never opens. Measured in the quiz demo (#181). So the paths are pointed at `heavy/` on the page's own origin.
+//
+// ⚠️ NOTHING HERE IS IMPORTED FROM npm: `import(url)` of an address on our own origin needs no bundler and puts no megabyte in
+// the chunk of a game that runs no graph at all.
+import { deliveryPath } from './heavy.js';
+import { HEAVY_FILES } from './heavy-catalogue.js';
+const ORT_ESM = 'voz:runtime:onnx';
+const ORT_GLUE = 'voz:runtime:onnx:cola';
+const ORT_WASM = 'voz:runtime:onnx:wasm';
+/**
+ * ⚠️ THE ADDRESSES ARE NOT WRITTEN HERE. They live once, in the catalogue, with the sha256 that is checked before anything is
+ * written into a delivery (ADR-0114, ADR-0177): a second copy in a module would be a version that drifts from the one the build
+ * fetched, and the page would ask for a file the delivery does not have.
+ */
+function heavyUrlOf(id) {
+    const heavy = HEAVY_FILES.find((p) => p.id === id);
+    if (!heavy?.url)
+        throw new Error(`the heavy catalogue has no address for ${id}`);
+    return heavy.url;
+}
+/** Where the delivery serves a catalogued file, from the page's own address. */
+export const atDelivery = (id, base) => new URL(deliveryPath(heavyUrlOf(id)), base).href;
+/** The runtime, from the delivery, with its threads pointed at the delivery too. Refuses by NAME when it is not there. */
+export async function loadOnnxRuntime(d) {
+    const loadModule = d.importModule ?? ((url) => import(/* @vite-ignore */ url));
+    const module = await loadModule(atDelivery(ORT_ESM, d.base));
+    const ort = (module.default ?? module);
+    if (!ort?.InferenceSession)
+        throw new Error(`onnxruntime did not load from the delivery (${ORT_ESM})`);
+    if (ort.env?.wasm)
+        ort.env.wasm.wasmPaths = { mjs: atDelivery(ORT_GLUE, d.base), wasm: atDelivery(ORT_WASM, d.base) };
+    return ort;
+}

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

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { ReadingAnswer, ReadingRequest } from './reading-worker.js';
+/** The little of a `Worker` this module uses, so a gate can answer the protocol without a thread. */
+export interface ReadingWorkerLike {
+    postMessage(message: ReadingRequest, transfer?: readonly Transferable[]): void;
+    onmessage: ((event: {
+        data: ReadingAnswer;
+    }) => void) | null;
+    onerror?: ((event: unknown) => void) | null;
+    terminate(): void;
+}
+export interface ReadingInWorkerDeps {
+    /** The page's address: the worker resolves `heavy/` against it, because IT is who fetches the model. */
+    readonly base: string;
+    readonly language: string;
+    /**
+     * Opens the thread: `platform/reading-worker` started as a module worker. REQUIRED (ADR-0232 D4), and the root writes it,
+     * because the one form a bundler recognises — `new Worker(new URL('…', import.meta.url), { type: 'module' })`, literally —
+     * has to sit where the `Worker` is the host's.
+     */
+    readonly spawn: () => ReadingWorkerLike;
+    /**
+     * WHY THE THREAD COULD NOT OPEN, WHEN NOBODY IS THERE TO BE TOLD (ADR-0169).
+     *
+     * 🔴 The opening is awaited by `transcribe()`, and only by it. A game that declares `uses: { reading: true }` and has
+     * not listened yet — or one whose child never will — has nobody awaiting the answer, so a model that does not load
+     * used to reject into NOTHING: an unhandled rejection in a browser's console, and silence in `problems`.
+     * 📌 THE REASON AND NOT THE SENTENCE: what this hands over is the failure's own words, and the line a human reads —
+     * what the child loses, what to do about it — is written by whoever owns the diagnostic channel. A module that is
+     * one thread's protocol has no business holding interface prose, and the raw-prose ledger is where that shows.
+     * 📌 Optional, and the absence is answered: without it the failure is still owned, it is just not reported.
+     */
+    readonly report?: (reason: string) => void;
+}
+export interface ReadingInWorker {
+    transcribe(samples: Float32Array): Promise<string>;
+    /** Lets the thread go. A transcription still running answers with the reason instead of never answering. */
+    close(): void;
+}
+export declare function createReadingInWorker(d: ReadingInWorkerDeps): ReadingInWorker;

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

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/reading-in-worker — THE ENGINE'S SIDE OF THE READING WORKER (ADR-0216 §2; issue #185).
+//
+// Answers the same shape `platform/reading` asks its `model` port for — something with `transcribe(samples)` — and keeps the
+// work off the thread that draws the game and feeds the microphone (`platform/reading-worker` says what that costs when it is
+// not kept off it).
+//
+// 📌 THE WORKER IS OPENED AT THE FIRST READING AND KEPT, not opened per utterance: opening it means compiling the model again,
+// and the model is up to 378 MiB. It is closed when the engine lets the reading go, so a game that stops listening stops
+// paying for a thread.
+export function createReadingInWorker(d) {
+    const worker = d.spawn();
+    let nextId = 1;
+    const waiting = new Map();
+    let opened = null;
+    let closed = false;
+    const openedPromise = new Promise((resolve, reject) => { opened = { resolve, reject }; });
+    /*
+     * 🔴 THE OPENING HAS AN OWNER FROM BIRTH, and giving it one is the whole job of this line. Nothing awaits
+     * `openedPromise` until the first `transcribe()`, so a thread that cannot open — a model file the delivery never
+     * wrote, a wasm that will not compile — rejected into nothing.
+     * 📏 Measured 2026-09-22: the browser project ended with every one of its 1140 cases green and an exit code of
+     * FAILURE, from this rejection alone. A suite that reports failure while passing teaches everyone to stop reading
+     * the exit code, and this house has already paid for that once — the published branch's CI was red for eight days.
+     * ⚠️ AND IT DOES NOT SWALLOW THE REASON: `transcribe()` awaits this same promise and still throws it, so whoever
+     * asked for a reading is told what went wrong. This line is for when NOBODY asks.
+     * 📌 Letting the thread go is not a failure: `close()` rejects the opening to release whoever was waiting, and a
+     * child who changed games is not a defect to report.
+     */
+    openedPromise.catch((e) => {
+        if (closed)
+            return;
+        d.report?.(e.message);
+    });
+    /** Everything pending gives up with the SAME reason — a promise nobody ever settles is how a game freezes politely. */
+    const giveUp = (message) => {
+        opened?.reject(new Error(message));
+        for (const { reject } of waiting.values())
+            reject(new Error(message));
+        waiting.clear();
+    };
+    worker.onmessage = (event) => {
+        const msg = event.data;
+        if (msg.kind === 'ready') {
+            opened?.resolve();
+            return;
+        }
+        if (msg.kind === 'text') {
+            waiting.get(msg.id)?.resolve(msg.text);
+            waiting.delete(msg.id);
+            return;
+        }
+        if (msg.id === undefined) {
+            opened?.reject(new Error(msg.message));
+            return;
+        }
+        waiting.get(msg.id)?.reject(new Error(msg.message));
+        waiting.delete(msg.id);
+    };
+    // a worker that dies — a file that did not load, a wasm that ran out of memory — must not leave the child waiting in silence
+    if ('onerror' in worker)
+        worker.onerror = () => { giveUp('reading worker: the thread stopped before answering'); };
+    worker.postMessage({ kind: 'load', base: d.base, language: d.language });
+    return {
+        async transcribe(samples) {
+            if (closed)
+                throw new Error('reading worker: asked to transcribe after the thread was let go');
+            await openedPromise;
+            const id = nextId++;
+            const answer = new Promise((resolve, reject) => { waiting.set(id, { resolve, reject }); });
+            /*
+             * 📌 THE SAMPLES ARE TRANSFERRED AND NOT COPIED: 30 s at 16 kHz is 1.9 MB, and copying it is a pause on the very thread
+             * this module exists to keep free. ⚠️ The buffer is empty on this side afterwards, which is correct — the recording
+             * belongs to the transcription now, and `platform/microphone` hands over a fresh one for the next reading.
+             */
+            worker.postMessage({ kind: 'transcribe', id, samples }, [samples.buffer]);
+            return await answer;
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            giveUp('reading worker: the thread was let go while this reading was still running');
+            worker.terminate();
+        },
+    };
+}