@the-inclusionist/engine 9.0.0 → 11.0.0

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,64 @@
+// 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;
+}
+/** The reading thread of the language being read in, kept between readings; see `keepOneThreadPerLanguage`. */
+export interface ReadingThreads<T extends {
+    close(): void;
+}> {
+    /**
+     * The thread for this language: the one kept when its base language is the same, else a new one from `open` — handed a
+     * `failed` to call when its opening fails. `open` is given at each call because the one form a bundler recognises for the
+     * thread's file has to sit where the host's `Worker` is (ADR-0232 D4), which is the caller's scope and not this module's.
+     */
+    forLanguage(language: string, open: (failed: () => void) => T): T;
+    /** Lets the kept thread go (the game left); the next `forLanguage` opens one again. */
+    close(): void;
+}
+/**
+ * ONE READING THREAD PER LANGUAGE, KEPT (issue #185; ADR-0225 erratum). Opening a thread compiles a model of up to 378 MiB, so a
+ * reading in the language already open reuses its thread, and a reading in another language (a child who switched: `pt-BR` and
+ * `pt-PT` are one model, `pt` and `en` are two) closes the old thread and opens the new one — one compiled model in memory at a
+ * time, which is what a school machine can hold.
+ * 🔴 A THREAD WHOSE OPENING FAILED IS FORGOTTEN: the next reading opens it again — the model may have come down since, and a
+ * thread kept dead would answer every later reading with the first one's failure.
+ */
+export declare function keepOneThreadPerLanguage<T extends {
+    close(): void;
+}>(): ReadingThreads<T>;
+export declare function createReadingInWorker(d: ReadingInWorkerDeps): ReadingInWorker;

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

@@ -0,0 +1,125 @@
+// 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.
+/**
+ * ONE READING THREAD PER LANGUAGE, KEPT (issue #185; ADR-0225 erratum). Opening a thread compiles a model of up to 378 MiB, so a
+ * reading in the language already open reuses its thread, and a reading in another language (a child who switched: `pt-BR` and
+ * `pt-PT` are one model, `pt` and `en` are two) closes the old thread and opens the new one — one compiled model in memory at a
+ * time, which is what a school machine can hold.
+ * 🔴 A THREAD WHOSE OPENING FAILED IS FORGOTTEN: the next reading opens it again — the model may have come down since, and a
+ * thread kept dead would answer every later reading with the first one's failure.
+ */
+export function keepOneThreadPerLanguage() {
+    let kept = null;
+    const baseOf = (tag) => tag.split('-')[0].toLowerCase();
+    return {
+        forLanguage(language, open) {
+            const base = baseOf(language);
+            if (kept?.base === base && kept.thread)
+                return kept.thread;
+            kept?.thread?.close();
+            const mine = { base, thread: null, dead: false };
+            kept = mine;
+            const thread = open(() => {
+                mine.dead = true;
+                if (kept === mine)
+                    kept = null;
+                mine.thread?.close();
+            });
+            if (mine.dead) {
+                thread.close();
+                return thread;
+            } // it failed while opening: answered, and not kept
+            mine.thread = thread;
+            return thread;
+        },
+        close() {
+            kept?.thread?.close();
+            kept = null;
+        },
+    };
+}
+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();
+        },
+    };
+}

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

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** What the engine asks of a language: which catalogue files, and what the encoder eats. */
+export interface ReadingModelPlan {
+    readonly language: string;
+    /** Whisper eats a log-mel spectrogram; Moonshine eats the samples. */
+    readonly input: 'log-mel' | 'waveform';
+    readonly encoder: string;
+    readonly decoder: string;
+    /** The second decoder graph, where the model has one: the first pass builds the cache, this one uses it. */
+    readonly decoderPast?: string;
+    readonly tokenizer: string;
+    readonly generation: string;
+    /** How many heads the caches hold and how wide each is — what a merged decoder needs to be handed empty ones. */
+    readonly config: string;
+    /** Only the mel front end needs one. */
+    readonly preprocessor?: string;
+}
+/** 16 kHz mono, for every one of them: it is what all three were trained on, and resampling is the caller's job. */
+export declare const READING_RATE = 16000;
+/** Whisper reads a 30 s window at a time, always: shorter is padded with silence, longer is cut. */
+export declare const WHISPER_SAMPLES: number;
+export declare const WHISPER_FRAMES = 3000;
+export declare const WHISPER_BANDS = 80;
+export declare const READING_MODELS: readonly ReadingModelPlan[];
+/** The model of a language tag (`pt-BR` → pt), or `null` where the project has none — which the caller must SAY, not hide. */
+export declare function readingModelFor(language: string): ReadingModelPlan | null;
+/**
+ * WHAT WHISPER'S ENCODER EATS: a log-mel spectrogram of 80 bands by 3000 frames, from a 30 s window at 16 kHz.
+ *
+ * The steps are `WhisperFeatureExtractor`'s, in its order, and each one matters: the window is a PERIODIC Hann (a symmetric one
+ * moves every value); the signal is reflected at both ends by half a window, so frame 0 is centred on sample 0; the power
+ * spectrum is the magnitude SQUARED; the last frame is dropped, which is why 480 000 samples give 3000 and not 3001; the floor is
+ * eight decades below the LOUDEST point of this window, not a constant; and the scale ends in (x + 4) / 4.
+ */
+export declare function logMel(samples: Float32Array, melFilters: readonly (readonly number[])[]): Float32Array;
+/** The part of a `config.json` that says how a streaming encoder cuts the wave. */
+export interface WaveFrameConfig {
+    readonly encoder_config?: {
+        readonly frame_ms?: number;
+        readonly sample_rate?: number;
+    };
+}
+/**
+ * THE FRAME A STREAMING ENCODER CUTS THE WAVE INTO, in samples: `frame_ms` at `sample_rate`, from the model's own `config.json`
+ * — 5 ms at 16 kHz, 80, for both Moonshines. 1 where the config names no frame: a model without one takes any length.
+ */
+export declare function waveFrameOf(config: WaveFrameConfig): number;
+/**
+ * WHAT MOONSHINE STREAMING'S ENCODER EATS: the wave in WHOLE FRAMES. Its first node reshapes the samples to `[1, -1, 80]`, and
+ * onnxruntime refuses a length that is not a multiple of 80 — 📏 measured on both graphs (issue #185): a microphone hands over
+ * blocks of 4096, which make whole frames only five at a time, so most readings failed. The model's own processor pads with
+ * zeros on the right to a multiple of 80 (`preprocessor_config.json`: `pad_to_multiple_of`, `padding_side`, `padding_value`),
+ * and this is that step: under 5 ms of silence after the child finished, and her wave untouched. An empty recording becomes one
+ * frame of silence, because a graph handed nothing does not run; a wave already in whole frames is handed on as it came.
+ */
+export declare function inWholeFrames(samples: Float32Array, frame: number): Float32Array;
+/** A `tokenizer.json`, in the parts a reading reads: the vocabulary, the added tokens, and which decoder undoes them. */
+export interface TokenizerFile {
+    readonly model?: {
+        readonly vocab?: Readonly<Record<string, number>>;
+    };
+    readonly added_tokens?: readonly {
+        readonly id: number;
+        readonly content: string;
+        readonly special?: boolean;
+    }[];
+    readonly decoder?: {
+        readonly type?: string;
+    };
+}
+/**
+ * WHAT THE CHILD ACTUALLY SAID, from the ids the decoder answered.
+ *
+ * The two families undo themselves differently and the file says which: Whisper writes every byte as a printable character
+ * (`ByteLevel`), Moonshine writes a space as `▁` and a rare byte as `<0x..>` (`Replace` + `ByteFallback` + `Fuse` + `Strip`).
+ * Both end in ONE decode of UTF-8, which is what keeps an accent that spans two tokens from becoming two broken characters.
+ */
+export declare function readingTextOf(tokenizer: TokenizerFile, ids: readonly number[]): string;
+/** What a `generation_config.json` says must never be answered — Whisper's list of tokens that are not speech. */
+export interface GenerationConfig {
+    readonly suppress_tokens?: readonly number[];
+    readonly begin_suppress_tokens?: readonly number[];
+    readonly eos_token_id?: number;
+    readonly decoder_start_token_id?: number;
+}
+/**
+ * The tokens refused at this step. `atStart` is the first answered token, where Whisper also refuses the ones that would make it
+ * open with a silence or a punctuation mark — without this it answers «.» to a child who read a whole sentence.
+ */
+export declare function suppressedTokens(config: GenerationConfig, atStart: boolean): ReadonlySet<number>;
+/** The id of a named token (`<|pt|>`, `<|transcribe|>`), or `null` — a model that does not have it must be SAID, not guessed. */
+export declare function tokenIdOf(tokenizer: TokenizerFile, content: string): number | null;
+/** The next token: the biggest logit that is not refused. Greedy, because a child reading a known text needs no imagination. */
+export declare function nextToken(logits: ArrayLike<number>, suppressed?: ReadonlySet<number>): number;

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

@@ -0,0 +1,272 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/reading-model — WHAT A READING MODEL NEEDS DONE TO SOUND AND TO TOKENS, in its pure half (ADR-0216 §2; issues #185, #200).
+//
+// The engine hears a child read aloud with one model per language (ADR-0201 erratum): Whisper small for Portuguese, Moonshine
+// streaming small for English and Spanish. Around the graphs there is arithmetic that has nothing to do with a browser — turning
+// sound into what the encoder eats, and turning the numbers the decoder answers back into words — and it lives here, where it can
+// be measured. `platform/reading-runtime` is the half that opens sessions and fetches files.
+//
+// 🎯 MEASURED AGAINST THE ORIGINALS, not against my idea of them: `tests/fixtures/reading-ground-truth.json` is what
+// `WhisperFeatureExtractor` and the three tokenizers answer for one deterministic signal and three phrases, written by
+// `scratchpad/verdade-da-leitura.py`. A front end that is subtly wrong still runs and still returns text — the wrong text — so
+// «it produced something» is not a check.
+//
+// · THE MEL FILTERS ARE NOT COMPUTED HERE. Whisper's own `preprocessor_config.json` carries them (80 × 201), which is most of its
+//   185 KB, and the catalogue already fetches it: a filterbank rebuilt from a formula is a second opinion about the model's input.
+// · Moonshine takes the WAVEFORM. No spectrogram, no padding to 30 s — it is a different front end, not a variant of this one.
+//   ⚠️ But the streaming encoder takes it in WHOLE FRAMES of 5 ms (80 samples), and refuses any other length: `inWholeFrames`.
+/** 16 kHz mono, for every one of them: it is what all three were trained on, and resampling is the caller's job. */
+export const READING_RATE = 16_000;
+/** Whisper reads a 30 s window at a time, always: shorter is padded with silence, longer is cut. */
+export const WHISPER_SAMPLES = 30 * READING_RATE;
+export const WHISPER_FRAMES = 3000;
+export const WHISPER_BANDS = 80;
+const N_FFT = 400;
+const HOP = 160;
+const HALF = N_FFT / 2;
+const BINS = HALF + 1;
+/** What a band is when its power is clipped: the original clips at 1e-10 before the log. */
+const CLIPPED = Math.log10(1e-10);
+export const READING_MODELS = Object.freeze([
+    {
+        language: 'pt', input: 'log-mel',
+        encoder: 'reading:pt:encoder', decoder: 'reading:pt:decoder', decoderPast: 'reading:pt:decoder:past',
+        tokenizer: 'reading:pt:tokenizer', generation: 'reading:pt:generation', config: 'reading:pt:config',
+        preprocessor: 'reading:pt:preprocessor',
+    },
+    {
+        language: 'en', input: 'waveform',
+        encoder: 'reading:en:encoder', decoder: 'reading:en:decoder',
+        tokenizer: 'reading:en:tokenizer', generation: 'reading:en:generation', config: 'reading:en:config',
+    },
+    {
+        language: 'es', input: 'waveform',
+        encoder: 'reading:es:encoder', decoder: 'reading:es:decoder', decoderPast: 'reading:es:decoder:past',
+        tokenizer: 'reading:es:tokenizer', generation: 'reading:es:generation', config: 'reading:es:config',
+    },
+]);
+/** The model of a language tag (`pt-BR` → pt), or `null` where the project has none — which the caller must SAY, not hide. */
+export function readingModelFor(language) {
+    const tag = language.split('-')[0].toLowerCase();
+    return READING_MODELS.find((m) => m.language === tag) ?? null;
+}
+/**
+ * WHAT WHISPER'S ENCODER EATS: a log-mel spectrogram of 80 bands by 3000 frames, from a 30 s window at 16 kHz.
+ *
+ * The steps are `WhisperFeatureExtractor`'s, in its order, and each one matters: the window is a PERIODIC Hann (a symmetric one
+ * moves every value); the signal is reflected at both ends by half a window, so frame 0 is centred on sample 0; the power
+ * spectrum is the magnitude SQUARED; the last frame is dropped, which is why 480 000 samples give 3000 and not 3001; the floor is
+ * eight decades below the LOUDEST point of this window, not a constant; and the scale ends in (x + 4) / 4.
+ */
+export function logMel(samples, melFilters) {
+    const audio = new Float32Array(WHISPER_SAMPLES);
+    audio.set(samples.subarray(0, WHISPER_SAMPLES));
+    // the reflected padding, written once: `at(i)` is the padded signal, so no copy of 480 000 samples is made
+    const at = (i) => {
+        const j = i - HALF;
+        if (j < 0)
+            return audio[-j];
+        if (j >= WHISPER_SAMPLES)
+            return audio[2 * WHISPER_SAMPLES - j - 2];
+        return audio[j];
+    };
+    const turns = dftTurns();
+    const out = new Float32Array(WHISPER_BANDS * WHISPER_FRAMES);
+    const power = new Float64Array(BINS);
+    let loudest = -Infinity;
+    for (let frame = 0; frame < WHISPER_FRAMES; frame++) {
+        const start = frame * HOP;
+        // 🎯 A WINDOW OF PURE SILENCE IS ANSWERED, NOT COMPUTED, and it is EXACT: every bin of a window of zeros is zero, so every
+        // band is the clipped value. A child reads for a few seconds into a 30 s window, so most frames are this one. It never
+        // raises the loudest point: no computed band is ever below the clip, and an all-silent window floors at −∞.
+        let quiet = true;
+        for (let n = 0; n < N_FFT && quiet; n++)
+            quiet = at(start + n) === 0;
+        if (quiet) {
+            for (let band = 0; band < WHISPER_BANDS; band++)
+                out[band * WHISPER_FRAMES + frame] = CLIPPED;
+            continue;
+        }
+        powerOf(at, start, turns, power);
+        loudest = Math.max(loudest, melOf(power, melFilters, out, frame));
+    }
+    // the floor is eight decades below the LOUDEST point of this window, not a constant, and the scale ends in (x + 4) / 4
+    const floor = loudest - 8;
+    for (let i = 0; i < out.length; i++)
+        out[i] = (Math.max(out[i], floor) + 4) / 4;
+    return out;
+}
+/**
+ * THE FRAME A STREAMING ENCODER CUTS THE WAVE INTO, in samples: `frame_ms` at `sample_rate`, from the model's own `config.json`
+ * — 5 ms at 16 kHz, 80, for both Moonshines. 1 where the config names no frame: a model without one takes any length.
+ */
+export function waveFrameOf(config) {
+    const { frame_ms: ms, sample_rate: rate } = config.encoder_config ?? {};
+    return ms && rate ? Math.round((ms * rate) / 1000) : 1;
+}
+/**
+ * WHAT MOONSHINE STREAMING'S ENCODER EATS: the wave in WHOLE FRAMES. Its first node reshapes the samples to `[1, -1, 80]`, and
+ * onnxruntime refuses a length that is not a multiple of 80 — 📏 measured on both graphs (issue #185): a microphone hands over
+ * blocks of 4096, which make whole frames only five at a time, so most readings failed. The model's own processor pads with
+ * zeros on the right to a multiple of 80 (`preprocessor_config.json`: `pad_to_multiple_of`, `padding_side`, `padding_value`),
+ * and this is that step: under 5 ms of silence after the child finished, and her wave untouched. An empty recording becomes one
+ * frame of silence, because a graph handed nothing does not run; a wave already in whole frames is handed on as it came.
+ */
+export function inWholeFrames(samples, frame) {
+    const whole = Math.max(1, Math.ceil(samples.length / frame)) * frame;
+    if (whole === samples.length)
+        return samples;
+    const out = new Float32Array(whole);
+    out.set(samples);
+    return out;
+}
+/** A PERIODIC Hann window: a symmetric one moves every value. 400 numbers, computed once. */
+const HANN = Float64Array.from({ length: N_FFT }, (_, i) => 0.5 - 0.5 * Math.cos((2 * Math.PI * i) / N_FFT));
+/**
+ * ⚠️ THE TURNS ARE COMPUTED ONCE. A 400-point real DFT for 201 bins is 80 400 sines and cosines per frame, and there are 3000
+ * frames: asking `Math.cos` for them each time is a quarter of a billion calls, which on a school machine is not «slower», it is
+ * a child waiting half a minute to be told what they read.
+ */
+function dftTurns() {
+    const cos = new Float64Array(BINS * N_FFT);
+    const sin = new Float64Array(BINS * N_FFT);
+    for (let k = 0; k < BINS; k++) {
+        for (let n = 0; n < N_FFT; n++) {
+            const angle = (-2 * Math.PI * k * n) / N_FFT;
+            cos[k * N_FFT + n] = Math.cos(angle);
+            sin[k * N_FFT + n] = Math.sin(angle);
+        }
+    }
+    return { cos, sin };
+}
+/** One frame's power spectrum: the windowed DFT's magnitude SQUARED, one value per bin. */
+function powerOf(at, start, turns, power) {
+    for (let k = 0; k < BINS; k++) {
+        let re = 0, im = 0;
+        const row = k * N_FFT;
+        for (let n = 0; n < N_FFT; n++) {
+            const x = at(start + n) * HANN[n];
+            re += x * turns.cos[row + n];
+            im += x * turns.sin[row + n];
+        }
+        power[k] = re * re + im * im;
+    }
+}
+/** One frame's 80 bands, each the power through its mel filter, clipped at 1e-10 BEFORE the log. Answers the frame's loudest. */
+function melOf(power, melFilters, out, frame) {
+    let loudest = -Infinity;
+    for (let band = 0; band < WHISPER_BANDS; band++) {
+        const filter = melFilters[band];
+        let sum = 0;
+        for (let k = 0; k < BINS; k++)
+            sum += power[k] * filter[k];
+        const value = Math.log10(Math.max(sum, 1e-10));
+        out[band * WHISPER_FRAMES + frame] = value;
+        if (value > loudest)
+            loudest = value;
+    }
+    return loudest;
+}
+/** id → the piece of text that token stands for, with the special ones (`<|pt|>`, `</s>`…) marked so they never reach a child. */
+function piecesOf(tokenizer) {
+    const text = new Map();
+    for (const [piece, id] of Object.entries(tokenizer.model?.vocab ?? {}))
+        text.set(id, piece);
+    const special = new Set();
+    for (const added of tokenizer.added_tokens ?? []) {
+        text.set(added.id, added.content);
+        // ⚠️ `special` is absent on some files and the mark is what keeps `<|startoftranscript|>` out of a child's sentence, so the
+        // shape of the content decides when the flag does not: every one of them is bracketed.
+        if (added.special ?? /^<.*>$/.test(added.content))
+            special.add(added.id);
+    }
+    return { text, special };
+}
+/** The bytes GPT-2 writes as themselves: its three printable ranges, inclusive (`bytes_to_unicode`, openai/gpt-2 `encoder.py`). */
+const PRINTABLE_RANGES = [[33, 126], [161, 172], [174, 255]];
+// GPT-2's byte alphabet: the printable character each byte is written as, so a tokenizer file stays text. Whisper's decoder is
+// this one (`ByteLevel`), and reversing it is the whole of it.
+const byteOfChar = (() => {
+    const map = new Map();
+    const printable = [];
+    for (const [lo, hi] of PRINTABLE_RANGES)
+        for (let b = lo; b <= hi; b++)
+            printable.push(b);
+    for (const b of printable)
+        map.set(String.fromCharCode(b), b);
+    let next = 0;
+    for (let b = 0; b < 256; b++) {
+        if (printable.includes(b))
+            continue;
+        map.set(String.fromCharCode(256 + next), b);
+        next++;
+    }
+    return map;
+})();
+const BYTE_FALLBACK = /^<0x([0-9A-Fa-f]{2})>$/;
+/**
+ * WHAT THE CHILD ACTUALLY SAID, from the ids the decoder answered.
+ *
+ * The two families undo themselves differently and the file says which: Whisper writes every byte as a printable character
+ * (`ByteLevel`), Moonshine writes a space as `▁` and a rare byte as `<0x..>` (`Replace` + `ByteFallback` + `Fuse` + `Strip`).
+ * Both end in ONE decode of UTF-8, which is what keeps an accent that spans two tokens from becoming two broken characters.
+ */
+export function readingTextOf(tokenizer, ids) {
+    const { text, special } = piecesOf(tokenizer);
+    const byteLevel = tokenizer.decoder?.type === 'ByteLevel';
+    const bytes = [];
+    for (const id of ids) {
+        if (special.has(id))
+            continue;
+        const piece = text.get(id);
+        if (piece === undefined)
+            continue; // an id the vocabulary does not have is not a character: it is dropped, never guessed
+        if (byteLevel) {
+            for (const ch of piece)
+                bytes.push(byteOfChar.get(ch) ?? ch.charCodeAt(0));
+            continue;
+        }
+        const fallback = BYTE_FALLBACK.exec(piece);
+        if (fallback) {
+            bytes.push(parseInt(fallback[1], 16));
+            continue;
+        }
+        for (const b of new TextEncoder().encode(piece.replaceAll('▁', ' ')))
+            bytes.push(b);
+    }
+    const whole = new TextDecoder().decode(Uint8Array.from(bytes));
+    return byteLevel ? whole : whole.replace(/^ /, '');
+}
+/**
+ * The tokens refused at this step. `atStart` is the first answered token, where Whisper also refuses the ones that would make it
+ * open with a silence or a punctuation mark — without this it answers «.» to a child who read a whole sentence.
+ */
+export function suppressedTokens(config, atStart) {
+    const out = new Set(config.suppress_tokens ?? []);
+    if (atStart)
+        for (const id of config.begin_suppress_tokens ?? [])
+            out.add(id);
+    return out;
+}
+/** The id of a named token (`<|pt|>`, `<|transcribe|>`), or `null` — a model that does not have it must be SAID, not guessed. */
+export function tokenIdOf(tokenizer, content) {
+    for (const added of tokenizer.added_tokens ?? [])
+        if (added.content === content)
+            return added.id;
+    const fromVocab = tokenizer.model?.vocab?.[content];
+    return fromVocab ?? null;
+}
+/** The next token: the biggest logit that is not refused. Greedy, because a child reading a known text needs no imagination. */
+export function nextToken(logits, suppressed) {
+    let best = -1, bestValue = -Infinity;
+    for (let id = 0; id < logits.length; id++) {
+        if (suppressed?.has(id))
+            continue;
+        const value = logits[id];
+        if (value > bestValue) {
+            bestValue = value;
+            best = id;
+        }
+    }
+    return best;
+}

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

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type OnnxRuntime } from './onnx-runtime.js';
+/** What the engine gets back: something that turns samples into words. */
+export interface ReadingTranscriber {
+    /** 16 kHz mono samples in, the child's words out. Empty when the model answered nothing. */
+    transcribe(samples: Float32Array): Promise<string>;
+}
+export interface ReadingRuntimeDeps {
+    /** The page's address, which `heavy/` is resolved against. */
+    readonly base: string;
+    /** The child's language tag (`pt-BR`). A language the project has no model for is refused BY NAME. */
+    readonly language: string;
+    /**
+     * The `fetch` of the realm this runs in, lent by whoever opens the reading (ADR-0232 D4): the root's window where there is
+     * no worker, the worker's own scope inside `platform/reading-worker`. REQUIRED — this module reaches no global.
+     */
+    readonly fetch: (url: string) => Promise<Response>;
+    /** Injected so a case can replay a real model's numbers without its 378 MiB; the default is the delivery's runtime. */
+    readonly ort?: OnnxRuntime;
+    readonly importModule?: (url: string) => Promise<unknown>;
+    /** A ceiling on the answer, so a model that loops does not hold the microphone for ever. */
+    readonly maxTokens?: number;
+}
+export declare function loadReadingRuntime(d: ReadingRuntimeDeps): Promise<ReadingTranscriber>;