@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/platform/heavy-catalogue.d.ts

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** A heavy thing the engine promises that does not fit in the package. */
+export interface HeavyFile {
+    readonly id: string;
+    /** `null` = decided that it exists, but there is nowhere to fetch it from yet. See `whyNoSource`. */
+    readonly url: string | null;
+    /** Measured, not estimated — the number an honest sentence uses before the download starts. */
+    readonly bytes?: number;
+    /**
+     * The SHA-256 of the bytes, MEASURED (issue #168): what the fetcher compares before keeping anything. A pinned URL is
+     * not pinned content — a CDN or a mirror can serve other bytes at the same address, and these run in the child's page.
+     */
+    readonly sha256?: string;
+    /** Required when `url` is `null`: an absence without a written reason becomes a forgotten absence. */
+    readonly whyNoSource?: string;
+}
+/** The Cache Storage name. Versioned: changing the catalogue's content must not serve old bytes. */
+export declare const CACHE_HEAVY = "incl-pesados-v2";
+/** The language a reading id serves, or `null` where the id is not a reading model's. */
+export declare function readingLanguageOf(id: string): string | null;
+/**
+ * The language a command MODEL serves, or `null` for anything else — including the runtime, which serves every language.
+ * ⚠️ The middle word is read on purpose: `id.split(':')[1]` would call the runtime a language of its own and leave the three
+ * models behind it out of the start of every delivery.
+ */
+export declare function commandsLanguageOf(id: string): string | null;
+/**
+ * WHERE THE DELIVERY PUTS THE LIBRAS PLAYER'S FILES (ADR-0234, route B, the engine's interpreter since phase B3): the avatar, its
+ * clips, their manifest and the build-time glosses, beside the game's page (`inclusionist-heavy --libras`). Written here, below
+ * the player that reads it (`ui/libras-avatar-plan` re-exports it), because the delivery's list of those files names it too.
+ *
+ * 📌 THERE IS NO CATALOGUE ENTRY FOR IT: the avatar and the clips are this project's own export of LAViD-UFPB's GPL-3.0 sign
+ * sources, pinned by sha256 in `scripts/libras-avatar.json`, and each delivery lists what it wrote (`DELIVERY_LISTS`). Nothing
+ * closed and nothing patched is served for it.
+ */
+export declare const LIBRAS_AVATAR_FOLDER = "libras/avatar/";
+/**
+ * THE START OF THE FREE PLAYER'S STAGE CHUNK, under the page: `ui/libras-avatar-stage` and the three.js it carries, which the
+ * bundler emits as `assets/libras-avatar-stage-<content hash>.js`. The precache leaves it out on purpose (three.js is only a
+ * deaf-mode child's download), so the delivery finds the hashed name after the build and lists it; a NAME's start and not a
+ * folder, because the rest of `assets/` belongs to the precache.
+ */
+export declare const LIBRAS_AVATAR_STAGE_CHUNK = "assets/libras-avatar-stage-";
+/**
+ * A LIST THE DELIVERY WRITES OF ITS OWN FILES, each with its sha256 — for what no catalogue entry can pin because each delivery
+ * makes it: the Libras player's avatar, clips and manifest, the glosses of the engine's and the game's texts, and the build's
+ * stage chunk (ADR-0234, pillar 8). The device reads the list and keeps each file only if its bytes are the listed ones, in the
+ * checked cache, under the file's own address, where the service worker answers the player from offline.
+ *
+ * ⚠️ WHAT THE LIST PROVES, AND WHAT IT DOES NOT: it comes from the page's own origin, like the page's code, so it is exactly as
+ * trusted as the page — it is not a pin. What it guarantees is that what is kept is what this delivery wrote: never a truncated
+ * body, a fallback page served for a missing file, or a file of the previous delivery. The avatar's and the clips' hashes in it
+ * are the ones `scripts/libras-avatar.json` pins, checked when the delivery wrote them.
+ */
+export interface DeliveryList {
+    readonly id: string;
+    /** Where the delivery writes the list, relative to the page. */
+    readonly path: string;
+    /**
+     * The only places the list may name, relative to the page: a listed file outside them is refused, never kept. Each is a
+     * folder (ending in `/`) or, for a file whose name the build hashes, the start of that name (`LIBRAS_AVATAR_STAGE_CHUNK`).
+     */
+    readonly folders: readonly string[];
+}
+/**
+ * The lists a device may read, each asked for with deaf mode (`heavyAtBoot`) — one per delivery step that writes files of its own:
+ * · `libras:avatar:delivery`, the Libras player's avatar, clips, manifest and glosses and the stage chunk with three.js, written by
+ *   `--libras` (ADR-0234, phase B3). A delivery built without it has no such list: a quiet 404, and deaf mode says «signing
+ *   unavailable» when the sonar is pressed.
+ * 📌 THE RULE IS «WHAT THE DELIVERY CARRIES, DEAF MODE KEEPS»: the files are kept whichever interpreter the host lends.
+ */
+export declare const DELIVERY_LISTS: readonly DeliveryList[];
+/**
+ * 📌 Every entry with an address needs its licence group in `scripts/licences/third-party.mjs`: the delivery writes that group's
+ * `LICENSE` and `NOTICE` beside the file, and refuses a file whose licence nobody recorded (ADR-0177).
+ */
+export declare const HEAVY_FILES: readonly HeavyFile[];

package/dist-pkg/platform/heavy-catalogue.js

@@ -0,0 +1,256 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/heavy-catalogue.ts — WHAT IS HEAVY, WHERE IT COMES FROM, AND HOW MUCH IT WEIGHS.
+//
+// 📌 APART FROM THE FETCHER on purpose: the list is DATA and changes by recorded decision; the fetcher is a rule and
+// changes by defect found. Together, every URL fix would touch the file that decides the download order, and every
+// order fix would touch the list a record governs.
+//
+// 📌 Every address is written ONCE, where its module owns it: Kokoro's in `platform/kokoro`, the vision runtime's here.
+import { KOKORO_VOICES, KOKORO_MODEL_URL, URL_DO_TOKENIZADOR_KOKORO, kokoroVoiceUrl, KOKORO_VOICES_SHA256, KOKORO_VOICE_BYTES, KOKORO_MODEL_SHA256, KOKORO_MODEL_BYTES, SHA256_DO_TOKENIZADOR_KOKORO, BYTES_DO_TOKENIZADOR_KOKORO, } from './kokoro.js';
+/** The Cache Storage name. Versioned: changing the catalogue's content must not serve old bytes. */
+// v2 since issue #168: what v1 kept was never checked against a hash, so it is not trusted — it is fetched again, checked.
+export const CACHE_HEAVY = 'incl-pesados-v2';
+/**
+ * THE VISION RUNTIME — **MediaPipe**, decided by the Dev (ADR-0124): «… mediapipe (webgazer não), e LPCP: devem
+ * acompanhar a engine». WebGazer, brought back by ADR-0132, left again (ADR-0214).
+ *
+ * 📏 MEASURED 2026-09-09: the three files answer 200 on jsDelivr with `Access-Control-Allow-Origin: *`, at the PINNED
+ * version — 155 439 + 323 377 + 11 756 954 bytes.
+ *
+ * ⚠️ A PINNED CDN IS ALLOWED AND ADR-0116 SAYS WHY: what pillar 8 forbids is depending on the network AFTER the first day.
+ * This comes down at INSTALL, with the rest. 📌 The version goes in the URL, which is what `check:precache` requires of
+ * any external entry: different bytes arrive by a different address, and a pinned entry never freezes.
+ *
+ * 🎯 IT IS THE THREE FILES AND NOT ONLY THE `.wasm`: `vision_bundle.mjs` is what loads it and `vision_wasm_internal.js` is
+ * the Emscripten glue. The wasm alone is a «downloaded» thing that does not run.
+ */
+const MP = 'https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@1.0.1';
+const MP_MODELS = 'https://storage.googleapis.com/mediapipe-models';
+/**
+ * 🔴 THE MODELS, without which the runtime recognises nothing: 11.7 MB of WebAssembly without a `.task` is a download
+ * that does no work. The Dev caught the first version of this list, which carried the runtime and no model.
+ *
+ * 📏 MEASURED, all 200 with open CORS. `float16` and not `float32`: half the weight, and the precision lost is irrelevant
+ * to saying where an iris is on a 320×180 screen.
+ */
+const MEDIAPIPE = Object.freeze([
+    { id: 'visao:runtime', url: `${MP}/vision_bundle.mjs`, bytes: 155_439,
+        sha256: 'd885630c297c0b20b1fe86096cb06291c4c8080876f27852e724f24ac603713f' },
+    { id: 'visao:runtime:cola', url: `${MP}/wasm/vision_wasm_internal.js`, bytes: 323_377,
+        sha256: 'e170ee67dd4e16c1a6fcd8840a206687e5a59b22c20e4a902bc445b095454d73' },
+    { id: 'visao:runtime:wasm', url: `${MP}/wasm/vision_wasm_internal.wasm`, bytes: 11_756_954,
+        sha256: '8da277a733926eacd0474b8704b36742d6ec3231c57a860c5b889dff8f1df886' },
+    { id: 'visao:modelo:rosto', url: `${MP_MODELS}/face_landmarker/face_landmarker/float16/1/face_landmarker.task`, bytes: 3_758_596,
+        sha256: '64184e229b263107bc2b804c6625db1341ff2bb731874b0bcc2fe6544e0bc9ff' },
+    { id: 'visao:modelo:gestos', url: `${MP_MODELS}/gesture_recognizer/gesture_recognizer/float16/1/gesture_recognizer.task`, bytes: 8_373_440,
+        sha256: '97952348cf6a6a4915c2ea1496b4b37ebabc50cbbf80571435643c455f2b0482' },
+    { id: 'visao:modelo:maos', url: `${MP_MODELS}/hand_landmarker/hand_landmarker/float16/1/hand_landmarker.task`, bytes: 7_819_105,
+        sha256: 'fbc2a30080c3c557093b5ddfc334698132eb341044ccee322ccf8bcf3607cde1' },
+]);
+/**
+ * THE VOICE RUNTIME (ADR-0216 and its erratum; issue #200): what SPEAKS a neural voice, fetched like the vision runtime and for the
+ * same reason — the engine imports nothing from npm at run time, so a game that never asks for this voice carries none of it, and
+ * the published package stays free of a bundler-only import.
+ *
+ * · eSpeak NG turns a sentence into phonemes, in every language the project speaks. GPL-3.0-or-later, compatible with the engine's
+ *   AGPL-3.0 (LICENSES.md). It is the PROJECT'S OWN BUILD (issue #192): the npm build named no source, so the engine compiles it
+ *   from a pinned commit (`scripts/models/build-espeak-ng.ps1`), and that commit and that recipe travel beside the mirror's copy.
+ *   Its address is the project's mirror because nothing upstream holds these bytes.
+ * · onnxruntime-web runs Kokoro's graph. The `jsep` pair is what its own threads load, which is why both are here: a worker that
+ *   cannot find them answers nothing, and the child hears silence (measured in the quiz demo, #181).
+ *
+ * ⚠️ sha256 MEASURED on the files, not taken from a page: onnxruntime-web's on those the dev dependency put on the build machine,
+ * which the first delivery run proved jsDelivr serves; eSpeak NG's on two runs of its recipe, which wrote the same bytes.
+ */
+const ESPEAK = 'https://lfs-oinclusionista.jrocha.dev.br/espeak-ng-530bf0a';
+const ORT = 'https://cdn.jsdelivr.net/npm/onnxruntime-web@1.27.0';
+const VOICE_RUNTIME = Object.freeze([
+    { id: 'voz:runtime:fonemas', url: `${ESPEAK}/espeak-ng.js`, bytes: 70_951,
+        sha256: 'd2f7cea5ed29daed420a05271a48e5b7ab5315b1f4b33fa04ea54014c155889e' },
+    { id: 'voz:runtime:fonemas:wasm', url: `${ESPEAK}/espeak-ng.wasm`, bytes: 1_493_661,
+        sha256: '44e0cc6accb436880d1d52d2dd7b69a72f8f6a8c8f2cdb3dcf00e3914db4eb05' },
+    { id: 'voz:runtime:onnx', url: `${ORT}/dist/ort.webgpu.bundle.min.mjs`, bytes: 113_035,
+        sha256: '3a18c7f261e05d44a15b2eef18a28e5f53c044d5d140bcea6066baf1f09c8b53' },
+    { id: 'voz:runtime:onnx:cola', url: `${ORT}/dist/ort-wasm-simd-threaded.jsep.mjs`, bytes: 46_614,
+        sha256: '3ee381d20a80f51a788a1c4a5872f6f1d047538dd4342f4af00062de5f9ea4c6' },
+    { id: 'voz:runtime:onnx:wasm', url: `${ORT}/dist/ort-wasm-simd-threaded.jsep.wasm`, bytes: 26_827_543,
+        sha256: '78feeeb3d08f6bcee94d938ed322f69073bb8076b5f9d34697a574ffba8deb48' },
+]);
+/**
+ * THE READING MODELS (ADR-0201 erratum, ADR-0203; issues #185, #200): what hears a child read aloud, ONE MODEL PER LANGUAGE —
+ * Whisper small for Portuguese, Moonshine streaming small for English and Spanish, the three the lab measured (pt 7.7 % WER,
+ * en 19.3 %, es 7.2 %).
+ *
+ * 🎯 THE ADDRESS IS THE PROJECT'S OWN, and it has to be: these two exports do not exist anywhere else. The Whisper one was made
+ * here (`scripts/models/export-whisper-small.py`) because the ready-made export states no licence, and the Spanish Moonshine was
+ * exported here from weights that ship no ONNX. The project mirrors them under ADR-0203 — «hospedar na Cloudflare do projeto» —
+ * with the licence of each beside it in `the-inclusionist-lfs`.
+ *
+ * ⚠️ AND THEY ARE BIG: 378 MiB for pt, 162 for en, 310 for es — and a device that reads keeps all three, because a child tries
+ * the three languages at once (ADR-0225 erratum, the Dev: «Negativo, baixar os três.»). The start asks for the child's language
+ * first and then each other whole (`heavyAtBoot`); a game that does not declare `uses: { reading: true }` asks for none of them.
+ *
+ * 📌 The ids are in English while their neighbours are not: what is here stays until the renaming of the whole catalogue (the
+ * English plan, phase 2, a single BREAKING release), and nothing new arrives in Portuguese meanwhile.
+ *
+ * ⚠️ sha256 MEASURED on the mirror's own files, each checked against the `SHA256SUMS` its folder publishes.
+ */
+const READING_MIRROR = 'https://lfs-oinclusionista.jrocha.dev.br';
+const READING = Object.freeze([
+    // pt — Whisper small, exported and quantized by this project
+    { id: 'reading:pt:encoder', url: `${READING_MIRROR}/whisper-small-onnx/onnx/encoder_model_quantized.onnx`, bytes: 95_131_296,
+        sha256: '25eae0fce49960d460d800c53a9df788afdf54baceee16ab6a6333869e2fc78f' },
+    { id: 'reading:pt:decoder', url: `${READING_MIRROR}/whisper-small-onnx/onnx/decoder_model_quantized.onnx`, bytes: 156_551_161,
+        sha256: '63e48cd0bef0f3367f4611728f38bf8f123af545212a2e744fe2ec28e0e887a3' },
+    { id: 'reading:pt:decoder:past', url: `${READING_MIRROR}/whisper-small-onnx/onnx/decoder_with_past_model_quantized.onnx`, bytes: 142_305_767,
+        sha256: '670b3e8b846f4e86dd3c26930bb671dec2df476b81c138c1864db37aa8bc92c0' },
+    { id: 'reading:pt:tokenizer', url: `${READING_MIRROR}/whisper-small-onnx/tokenizer.json`, bytes: 2_480_466,
+        sha256: '27fc476bfe7f17299480be2273fc0608e4d5a99aba2ab5dec5374b4482d1a566' },
+    { id: 'reading:pt:config', url: `${READING_MIRROR}/whisper-small-onnx/config.json`, bytes: 1_967,
+        sha256: 'e6a2b489da1b5aed65a8eb8d1e7466fa867ad5643a8bc138ba708bd56b2875c4' },
+    // what the reading must NOT invent: the tokens Whisper suppresses, and the mel filterbank its features are built with
+    { id: 'reading:pt:generation', url: `${READING_MIRROR}/whisper-small-onnx/generation_config.json`, bytes: 3_868,
+        sha256: '71565b8ef50d0bf7a1193ed4bbed195b94e70c18894d81bba2f1233dcec3ab53' },
+    { id: 'reading:pt:preprocessor', url: `${READING_MIRROR}/whisper-small-onnx/preprocessor_config.json`, bytes: 184_990,
+        sha256: '9b5cd03a36fbb8a627c64d98a5b5b126ead95a77720723944487311f0110b666' },
+    // en — Moonshine streaming small, the Workmind ONNX export, copied unchanged (MIT)
+    { id: 'reading:en:encoder', url: `${READING_MIRROR}/moonshine-streaming-small-onnx/onnx/encoder_model_quantized.onnx`, bytes: 74_923_158,
+        sha256: '69c786908794eb9e2e50d7137c4e755abdde7b4bdebffd68fe0c292eee5ffc55' },
+    { id: 'reading:en:decoder', url: `${READING_MIRROR}/moonshine-streaming-small-onnx/onnx/decoder_model_merged_quantized.onnx`, bytes: 90_830_447,
+        sha256: '3bd2e7a7e94c608b1988fa035be1f1b1f2acdbe059f7fe5cc70d85201c2835f5' },
+    { id: 'reading:en:tokenizer', url: `${READING_MIRROR}/moonshine-streaming-small-onnx/tokenizer.json`, bytes: 3_761_754,
+        sha256: '7b913404bdd039af4756783218af4440bc07fb7d6d8258d677e34f95b3ec416f' },
+    { id: 'reading:en:config', url: `${READING_MIRROR}/moonshine-streaming-small-onnx/config.json`, bytes: 1_745,
+        sha256: '849ca79b5af5603b1e7b8eeebf67265f931c70117434446fca6f35a26fc03df1' },
+    { id: 'reading:en:generation', url: `${READING_MIRROR}/moonshine-streaming-small-onnx/generation_config.json`, bytes: 163,
+        sha256: 'fd54ad15ad0a14f68db3c58a8d8e5e8f3791ef95e1ea92ee46cd71b4a5d7528c' },
+    // es — Moonshine streaming small, exported here from the upstream weights. ⚠️ Its encoder is fp32 and the biggest file of the
+    // three: quantized to q8 it drifted in the lab, and a reading that mis-hears a child is worse than a bigger download.
+    { id: 'reading:es:encoder', url: `${READING_MIRROR}/moonshine-streaming-small-es-onnx/onnx/encoder_model.onnx`, bytes: 205_951_994,
+        sha256: 'e675a5cf070ed40da516f1648bea62eb21f77421f1c490cedfe0d16bdc77a090' },
+    { id: 'reading:es:decoder', url: `${READING_MIRROR}/moonshine-streaming-small-es-onnx/onnx/decoder_model_quantized.onnx`, bytes: 63_639_862,
+        sha256: '6775c2b74f429ae202e5a11cc0db7e291a0e593641364ddf416613d130528fcf' },
+    { id: 'reading:es:decoder:past', url: `${READING_MIRROR}/moonshine-streaming-small-es-onnx/onnx/decoder_with_past_model_quantized.onnx`, bytes: 55_504_894,
+        sha256: '9cddfa057c8b5d65d3e5057b748b6f6b58753306846dd0fa4d0e8639cb22bfd9' },
+    { id: 'reading:es:tokenizer', url: `${READING_MIRROR}/moonshine-streaming-small-es-onnx/tokenizer.json`, bytes: 476_245,
+        sha256: 'e8dae7af9c2b6e5a1f413819db1eb70837ff4cf53b5a482a37f2ffc608b8b977' },
+    { id: 'reading:es:config', url: `${READING_MIRROR}/moonshine-streaming-small-es-onnx/config.json`, bytes: 1_653,
+        sha256: 'bfd932c804df9cde662468a8f933763cd5174bfed2c043b2440b4daaa702efbd' },
+    { id: 'reading:es:generation', url: `${READING_MIRROR}/moonshine-streaming-small-es-onnx/generation_config.json`, bytes: 246,
+        sha256: '3e5f0aa2b32615a4023d0a08cccb7c1ec292aba9a8d8f6f4886df2a769af31b0' },
+]);
+/** The language a reading id serves, or `null` where the id is not a reading model's. */
+export function readingLanguageOf(id) {
+    const parts = id.split(':');
+    return parts[0] === 'reading' && parts[1] ? parts[1] : null;
+}
+/**
+ * THE COMMAND MODELS (ADR-0189, ADR-0193, ADR-0194; issue #184): what hears a child SAY A WORD OF THE GAME. Not the same job as
+ * the reading above, and not the same tool: a command is heard against a CLOSED GRAMMAR — the names the menu is showing right
+ * now — which is why 32 MiB answer in 0.25 s what 378 MiB of Whisper answered in seconds and, on single words, wrongly (📏 lab:
+ * Vosk 7/7 commands, Whisper base 1/7).
+ *
+ * 🎯 THE RUNTIME IS THE PROJECT'S OWN BUILD, and that is the whole reason it exists: every published `vosk-browser` evaluates
+ * text as code, which this engine's Content-Security-Policy refuses (ADR-0193 — never `'unsafe-eval'`, never a patch). It was
+ * rebuilt from lichess-org/vosk-browser with `-s DYNAMIC_EXECUTION=0` and runs under the policy as it is (`models.md`).
+ * The models are alphacephei's small ones, repacked deterministically as the `.tar.gz` that build loads.
+ *
+ * ⚠️ ONE MODEL PER LANGUAGE, like the reading: pt 30.9 MiB, en 39.2, es 37.9. A delivery carries the three unless
+ * `inclusionist-heavy --commands` narrows it, and the start asks for every language the page can switch to, the child's first
+ * (ADR-0225 erratum: a language changed mid-game must find its model), as it does for the reading. 📌 But unlike the reading,
+ * NO GAME DECLARES THIS: a child who speaks instead of pressing is using a transport, and a cartridge does not get to deny her
+ * one (ADR-0111).
+ *
+ * ⚠️ sha256 MEASURED on the mirror's own files (2026-09-21), each checked against the `SHA256SUMS` its folder publishes.
+ */
+const COMMANDS = Object.freeze([
+    { id: 'commands:runtime', url: `${READING_MIRROR}/vosk-browser-dynamic-execution-0/vosk.wasm.js`, bytes: 10_288,
+        sha256: 'a7ab48dcf72660ec79a493c37b9fd1d0b3c09c46968c6a1ebd06adb4d9a35ca6' },
+    { id: 'commands:runtime:worker', url: `${READING_MIRROR}/vosk-browser-dynamic-execution-0/vosk.worker.js`, bytes: 194_710,
+        sha256: 'cf84a33820a1634d6a8d11194f2bd04f871901bf630ba1423c24f6be13086b6a' },
+    { id: 'commands:runtime:wasm', url: `${READING_MIRROR}/vosk-browser-dynamic-execution-0/vosk.wasm`, bytes: 2_992_690,
+        sha256: 'e2a33196eacd6cd7d863392f877b9360664d7614ce97cddf9de5b5e637e2ccf9' },
+    { id: 'commands:model:pt', url: `${READING_MIRROR}/vosk-models/vosk-model-small-pt-0.3.tar.gz`, bytes: 32_358_733,
+        sha256: '4885a09d9cd3063bf991e2ae280f24eeee789410aaa05277a2e082cff0cf837d' },
+    { id: 'commands:model:en', url: `${READING_MIRROR}/vosk-models/vosk-model-small-en-us-0.15.tar.gz`, bytes: 41_116_539,
+        sha256: '61cf40721d255cccb9fe29bb059c6b3376b164c31f449d8143455ffbb86018cc' },
+    { id: 'commands:model:es', url: `${READING_MIRROR}/vosk-models/vosk-model-small-es-0.42.tar.gz`, bytes: 39_748_927,
+        sha256: '4ed16b681698db764ecb11996b1b4f74dd68f602213b36c17806a1398b26b162' },
+]);
+/**
+ * The language a command MODEL serves, or `null` for anything else — including the runtime, which serves every language.
+ * ⚠️ The middle word is read on purpose: `id.split(':')[1]` would call the runtime a language of its own and leave the three
+ * models behind it out of the start of every delivery.
+ */
+export function commandsLanguageOf(id) {
+    const parts = id.split(':');
+    return parts[0] === 'commands' && parts[1] === 'model' && parts[2] ? parts[2] : null;
+}
+/**
+ * WHERE THE DELIVERY PUTS THE LIBRAS PLAYER'S FILES (ADR-0234, route B, the engine's interpreter since phase B3): the avatar, its
+ * clips, their manifest and the build-time glosses, beside the game's page (`inclusionist-heavy --libras`). Written here, below
+ * the player that reads it (`ui/libras-avatar-plan` re-exports it), because the delivery's list of those files names it too.
+ *
+ * 📌 THERE IS NO CATALOGUE ENTRY FOR IT: the avatar and the clips are this project's own export of LAViD-UFPB's GPL-3.0 sign
+ * sources, pinned by sha256 in `scripts/libras-avatar.json`, and each delivery lists what it wrote (`DELIVERY_LISTS`). Nothing
+ * closed and nothing patched is served for it.
+ */
+export const LIBRAS_AVATAR_FOLDER = 'libras/avatar/';
+/**
+ * THE START OF THE FREE PLAYER'S STAGE CHUNK, under the page: `ui/libras-avatar-stage` and the three.js it carries, which the
+ * bundler emits as `assets/libras-avatar-stage-<content hash>.js`. The precache leaves it out on purpose (three.js is only a
+ * deaf-mode child's download), so the delivery finds the hashed name after the build and lists it; a NAME's start and not a
+ * folder, because the rest of `assets/` belongs to the precache.
+ */
+export const LIBRAS_AVATAR_STAGE_CHUNK = 'assets/libras-avatar-stage-';
+/**
+ * The lists a device may read, each asked for with deaf mode (`heavyAtBoot`) — one per delivery step that writes files of its own:
+ * · `libras:avatar:delivery`, the Libras player's avatar, clips, manifest and glosses and the stage chunk with three.js, written by
+ *   `--libras` (ADR-0234, phase B3). A delivery built without it has no such list: a quiet 404, and deaf mode says «signing
+ *   unavailable» when the sonar is pressed.
+ * 📌 THE RULE IS «WHAT THE DELIVERY CARRIES, DEAF MODE KEEPS»: the files are kept whichever interpreter the host lends.
+ */
+export const DELIVERY_LISTS = Object.freeze([
+    Object.freeze({ id: 'libras:avatar:delivery', path: 'libras/offline-avatar.json',
+        folders: Object.freeze([LIBRAS_AVATAR_FOLDER, LIBRAS_AVATAR_STAGE_CHUNK]) }),
+]);
+/**
+ * KOKORO (ADR-0186, ADR-0198; the Dev: «Faça»): the fp32 model, its tokenizer vocabulary and a style table per voice of the engine's
+ * languages. The engine loads them itself when a game declares `uses.neuralVoice` (ADR-0216); the phonemizer and the runtime that
+ * speak them are `VOICE_RUNTIME`, above.
+ */
+const KOKORO = Object.freeze([
+    { id: 'voz:kokoro:modelo', url: KOKORO_MODEL_URL, bytes: KOKORO_MODEL_BYTES, sha256: KOKORO_MODEL_SHA256 },
+    { id: 'voz:kokoro:tokenizador', url: URL_DO_TOKENIZADOR_KOKORO, bytes: BYTES_DO_TOKENIZADOR_KOKORO, sha256: SHA256_DO_TOKENIZADOR_KOKORO },
+    ...KOKORO_VOICES.map((v) => ({ id: `voz:kokoro:${v.voice}`, url: kokoroVoiceUrl(v.voice), bytes: KOKORO_VOICE_BYTES, sha256: KOKORO_VOICES_SHA256[v.voice] })),
+]);
+/**
+ * 📌 Every entry with an address needs its licence group in `scripts/licences/third-party.mjs`: the delivery writes that group's
+ * `LICENSE` and `NOTICE` beside the file, and refuses a file whose licence nobody recorded (ADR-0177).
+ */
+export const HEAVY_FILES = Object.freeze([
+    ...VOICE_RUNTIME,
+    ...KOKORO,
+    // what hears a child read aloud, one model per language (ADR-0216 §2); the runtime that runs them is the voice's, above
+    ...READING,
+    // what hears a child SAY a word of the game, one model per language, with a runtime of its own (issue #184)
+    ...COMMANDS,
+    // the vision runtime and its models: eye control reads the face (ADR-0213); WebGazer left (ADR-0214)
+    ...MEDIAPIPE,
+    /*
+     * 🔴 THE ART COLLECTION — the fourth heavy thing of ADR-0119, and the only one WITHOUT A SOURCE. Measured: `art/` has
+     * TWO files — a README and a 40-byte `ATTRIBUTION.csv`, the header only. No art.
+     *
+     * 📌 The reason is simple: no collection has been chosen. Art enters under CC0, CC BY 3.0, CC BY 4.0 or OGA-BY, with a
+     * ledger line per asset and its source URL — and none of that is one URL a fetcher can ask for. (The Liberated Pixel
+     * Cup was refused by ADR-0133: both its arms are share-alike or GPL, outside the closed list of four licences.) This
+     * line's source is the day there is a collection.
+     */
+    {
+        id: 'arte:acervo',
+        url: null,
+        whyNoSource: 'não há acervo escolhido: `art/` tem só README e cabeçalho do CSV. O ADR-0133 fechou '
+            + 'a lista em CC0, CC BY 3.0/4.0 e OGA-BY, e a arte entra recurso a recurso com autoria e URL de '
+            + 'origem — não por uma URL solta que este buscador possa pedir.',
+    },
+]);

package/dist-pkg/platform/heavy-mirror.d.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Upstream prefix → the path the mirror serves it under. Measured against the staging tree on 2026-09-21. */
+export declare const MIRROR_FOLDERS: ReadonlyArray<readonly [string, string]>;
+/**
+ * Addresses the project does NOT mirror, each with why — they go on being fetched upstream even when a base is set.
+ *
+ * 📌 EMPTY, and a line here is a written decision, never an omission. The last one was the npm build of eSpeak NG, kept upstream
+ * because the project could not name the source it was built from; the engine now pins its own build, whose folder carries that
+ * source (issue #192). ⚠️ Before adding a line, check what the bucket serves: the mirror answers 404 for a folder not uploaded.
+ */
+export declare const NOT_MIRRORED: ReadonlyArray<readonly [string, string]>;
+/** The path a mirror serves this upstream address under, or `null` when no mirror of this project holds it. */
+export declare function mirrorPathOf(url: string): string | null;
+/**
+ * Where to fetch this file from: the base's copy when there is a base and the file is mirrored, upstream otherwise.
+ * A base may be an address (`https://…`) or a folder on this machine — the caller knows how to open each.
+ */
+export declare function heavySourceOf(url: string, base?: string | null): string;
+/** Is this base an address, or a folder on the machine running the build? */
+export declare const baseIsRemote: (base: string) => boolean;

package/dist-pkg/platform/heavy-mirror.js

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/heavy-mirror — WHERE A HEAVY FILE IS FETCHED FROM, WHEN IT IS NOT FETCHED FROM UPSTREAM.
+//
+// The Dev, 2026-09-21: «Precisamos de um .env que aponte para local quando estivermos testando em local e em
+// <a conta R2> quando estivermos usando estes recursos na minha conta. Isso facilitaria quando tivermos que hospedar em
+// outros servidores.»
+//
+// The catalogue pins an upstream address AND the sha256 of the bytes (ADR-0177, issue #168). A mirror serves those same
+// bytes somewhere else — the project's Cloudflare, a school's own server, a folder on the build machine — so the only thing
+// that changes is the BASE. Everything else, including the check, stays: a base that serves other bytes fails the sha256 and
+// nothing is written. That is what makes pointing elsewhere safe, and it is why this module does not need to be trusted.
+//
+// The staging tree (`the-inclusionist-lfs`) lays each artefact out as its future Hugging Face repository, so the path under
+// the base is NOT the upstream host and path — it is the folder the mirror uses. That mapping is here, once.
+/** Upstream prefix → the path the mirror serves it under. Measured against the staging tree on 2026-09-21. */
+// ⚠️ Written WITHOUT a trailing slash, exactly as the network inventory (`tests/nothing-comes-from-outside`) already declares each of
+// them: an address that differs by one character reads as a new supplier entering without a decision.
+export const MIRROR_FOLDERS = [
+    ['https://huggingface.co/onnx-community/Kokoro-82M-v1.0-ONNX/resolve/main', 'kokoro-82m-v1.0-onnx'],
+    ['https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@1.0.1', 'mediapipe-tasks-vision-1.0.1/tasks-vision@1.0.1'],
+    ['https://storage.googleapis.com/mediapipe-models', 'mediapipe-tasks-vision-1.0.1/models'],
+    // 📌 The reading models have NO upstream: both exports were made by this project (ADR-0201 erratum, ADR-0203), so the address
+    // the catalogue pins is already the mirror's. They are listed all the same, and that is what lets a build read them from the
+    // staging tree on disk — 850 MiB that nobody should download twice.
+    ['https://lfs-oinclusionista.jrocha.dev.br/whisper-small-onnx', 'whisper-small-onnx'],
+    ['https://lfs-oinclusionista.jrocha.dev.br/moonshine-streaming-small-onnx', 'moonshine-streaming-small-onnx'],
+    ['https://lfs-oinclusionista.jrocha.dev.br/moonshine-streaming-small-es-onnx', 'moonshine-streaming-small-es-onnx'],
+    // The command models and the runtime that loads them (issue #184). The runtime has no upstream either — every published
+    // `vosk-browser` evaluates text as code, so this one was rebuilt with `-s DYNAMIC_EXECUTION=0` to run under the policy.
+    ['https://lfs-oinclusionista.jrocha.dev.br/vosk-browser-dynamic-execution-0', 'vosk-browser-dynamic-execution-0'],
+    ['https://lfs-oinclusionista.jrocha.dev.br/vosk-models', 'vosk-models'],
+    // The neural voice's phonemizer, the project's own build of eSpeak NG (issue #192): it has no upstream either, and its folder
+    // carries the Corresponding Source the GPL asks for — the pinned commit and the recipe, in `corresponding-source/`. The commit is in the folder
+    // name on purpose: a mirror that drops it cannot serve two builds during an upgrade.
+    ['https://lfs-oinclusionista.jrocha.dev.br/espeak-ng-530bf0a', 'espeak-ng-530bf0a'],
+    // The graph runtime the neural voice shares with the reading models (the Dev on 2026-09-22).
+    ['https://cdn.jsdelivr.net/npm/onnxruntime-web@1.27.0', 'onnxruntime-web-1.27.0'],
+    // The font library (ADR-0255): one folder per family under `fonts/`, catalogued in `platform/font-library.json`. It has no
+    // upstream either — the library IS the project's copy, and the reserved-name families in it are their authors' originals.
+    ['https://lfs-oinclusionista.jrocha.dev.br/fonts', 'fonts'],
+    // 📌 The Libras player's avatar and clips are not catalogue files: `--libras` reads them from `<base>/vlibras-avatar-<commit>/`
+    // by their own pins (`scripts/libras-avatar.mjs`), so no mapping for them lives here.
+];
+/**
+ * Addresses the project does NOT mirror, each with why — they go on being fetched upstream even when a base is set.
+ *
+ * 📌 EMPTY, and a line here is a written decision, never an omission. The last one was the npm build of eSpeak NG, kept upstream
+ * because the project could not name the source it was built from; the engine now pins its own build, whose folder carries that
+ * source (issue #192). ⚠️ Before adding a line, check what the bucket serves: the mirror answers 404 for a folder not uploaded.
+ */
+export const NOT_MIRRORED = [];
+/** The path a mirror serves this upstream address under, or `null` when no mirror of this project holds it. */
+export function mirrorPathOf(url) {
+    if (NOT_MIRRORED.some(([prefix]) => url.startsWith(prefix)))
+        return null;
+    for (const [upstream, folder] of MIRROR_FOLDERS)
+        if (url.startsWith(`${upstream}/`))
+            return folder + url.slice(upstream.length);
+    return null;
+}
+/**
+ * Where to fetch this file from: the base's copy when there is a base and the file is mirrored, upstream otherwise.
+ * A base may be an address (`https://…`) or a folder on this machine — the caller knows how to open each.
+ */
+export function heavySourceOf(url, base) {
+    const path = base ? mirrorPathOf(url) : null;
+    if (!path)
+        return url;
+    return `${base.replace(/[/\\]+$/, '')}/${path}`;
+}
+/** Is this base an address, or a folder on the machine running the build? */
+// ⚠️ `\/{2}` and not `\/\/`: a gate reads the tree as text, and two slashes in a row are how a line comment starts.
+export const baseIsRemote = (base) => /^https?:\/{2}/i.test(base);

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

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { CACHE_HEAVY, HEAVY_FILES, type HeavyFile } from './heavy-catalogue.js';
+export { CACHE_HEAVY, HEAVY_FILES };
+/** What happened to each entry, so the caller can tell a person. */
+export interface HeavyReport {
+    readonly id: string;
+    readonly outcome: 'ja-tinha' | 'baixado' | 'falhou' | 'sem-fonte';
+    readonly bytes?: number;
+    readonly error?: string;
+}
+/**
+ * 🔴 WHAT THE DOWNLOAD USES OF THE BROWSER, RECEIVED AND NEVER REACHED (ADR-0232 point 2): the root reads each from the host's
+ * window. Required, because a port that falls back to the global is a global reached one step later (ADR-0224/0227).
+ */
+export interface HeavyOptions {
+    /**
+     * The host's `caches`, as its window answers it: `undefined` where it has none (an insecure context), and then every file
+     * is reported and none fetched. Required all the same — the key is the root's statement of what it lent.
+     */
+    readonly cacheStorage: CacheStorage | undefined;
+    /** The host's `fetch`, `undefined` where it has none, with the same answer. */
+    readonly fetch: typeof fetch | undefined;
+    /** Called on each resolved entry — what lets the interface say what is happening. */
+    readonly onProgress?: (r: HeavyReport) => void;
+    /**
+     * The SHA-256 of a body, as lowercase hex (issue #168) — `sha256With(crypto.subtle)`. `null` (a host without
+     * `crypto.subtle`, which is an insecure context) keeps NOTHING: unverifiable is not verified.
+     */
+    readonly digest: ((payload: ArrayBuffer) => Promise<string>) | null;
+    /**
+     * Only these ids, when given, and IN THIS ORDER — the download is one at a time, so the order is who waits (`heavyAtBoot`
+     * puts everything of the child's language first). For a consumer that wants the voices and not the rest.
+     */
+    readonly only?: readonly string[];
+    /**
+     * Files OUTSIDE the catalogue, kept by the same rules and FIRST: the font library's faces a cartridge declared
+     * (`platform/font-library`, ADR-0255) — a few hundred KB the child sees, which should not wait behind 850 MiB of models.
+     */
+    readonly also?: readonly HeavyFile[];
+    /** The page's address the delivery's `heavy/` folder is resolved against (`document.baseURI`). */
+    readonly base: string;
+}
+/**
+ * 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 declare function heavyAtBoot(declared: {
+    readonly kokoro: boolean;
+    readonly reading?: string | readonly string[] | null;
+    readonly commands?: string | readonly string[] | null;
+    readonly libras?: boolean;
+}): readonly string[];
+/**
+ * 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 declare function deliveryPath(url: string): string;
+/**
+ * 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 declare function deliveryCacheKey(urlOrRequest: string | {
+    readonly request: {
+        readonly url: string;
+    };
+}): string | null;
+/**
+ * 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 declare function downloadHeavy(options: HeavyOptions): Promise<HeavyReport[]>;
+/**
+ * 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 declare function sha256With(subtle: Pick<SubtleCrypto, 'digest'> | null | undefined): ((payload: ArrayBuffer) => Promise<string>) | null;
+/**
+ * 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 declare function checkedCacheHas(cacheStorage: CacheStorage | undefined): (upstreamUrl: string) => Promise<boolean>;
+/** The size of what is still missing, in bytes — so a notice can say how much is left before it starts. */
+export declare function bytesLeftToDownload(soFar: readonly HeavyReport[]): number;