@the-inclusionist/engine 10.0.0 → 11.0.0

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

@@ -24,6 +24,52 @@ export declare function readingLanguageOf(id: string): string | null;
  * 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).

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

@@ -52,21 +52,23 @@ const MEDIAPIPE = Object.freeze([
  * 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); the source travels beside the mirror (ADR-0203 erratum).
+ * · 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 the dev dependency already put on the build machine, not taken from a page; the first delivery run
- * is what proves jsDelivr serves the same bytes, because it refuses to write anything else.
+ * ⚠️ 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://cdn.jsdelivr.net/npm/espeak-ng@1.0.2';
+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}/dist/espeak-ng.js`, bytes: 178_386,
-        sha256: '406c6655a6cacf34d84fc69dc4478c81b71518809080ce2d05df1b706d76429d' },
-    { id: 'voz:runtime:fonemas:wasm', url: `${ESPEAK}/dist/espeak-ng.wasm`, bytes: 18_485_010,
-        sha256: '10d24bb7e4124e983aa9cd8cd96c52c8ea4b607d81956ec70846684e2827d532' },
+    { 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,
@@ -84,8 +86,9 @@ const VOICE_RUNTIME = Object.freeze([
  * 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. Nobody downloads all three — the start asks only for the child's
- * language (`heavyAtBoot`), and a game that does not declare `uses: { reading: true }` asks for none of them.
+ * ⚠️ 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.
@@ -152,9 +155,11 @@ export function readingLanguageOf(id) {
  * 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. The start asks for the child's, and a delivery
- * carries the ones it was built with (`inclusionist-heavy --commands pt`). 📌 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).
+ * ⚠️ 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.
  */
@@ -181,6 +186,34 @@ 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

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

@@ -4,15 +4,9 @@ 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.
  *
- * 🔴 AND THE ENTRY BELOW CAME BACK THE SAME DAY IT LEFT, which is worth writing rather than hiding. The Dev decided to mirror
- * both of the last two third-party addresses («Ok, vamos espelhar»), so this list was emptied — and 📏 measuring the bucket
- * after the upload showed `espeak-ng` answering **404** while the three `onnxruntime-web` files answer 200 with exactly the
- * catalogued byte counts. Nothing failed: the staging folder is marked «🔴 ON HOLD» and `upload-to-r2.ps1` skips it, because
- * espeak-ng is GPL-3.0-or-later and serving the binary obliges publishing the matching SOURCE beside it (ADR-0203 erratum,
- * issue #192). Emptying the list without checking what the bucket serves would have pointed every school at a 404.
- *
- * ⚠️ So it stays upstream until `espeak-ng-1.0.2/source/` exists. The decision to mirror it is unchanged; what is missing is
- * the obligation that decision carries, and a mirror is distribution.
+ * 📌 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. */

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

@@ -29,29 +29,26 @@ export const MIRROR_FOLDERS = [
     // `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 and the graph runtime it shares with the reading models (issue #192, the Dev on 2026-09-22).
-    // ⚠️ espeak-ng is GPL-3.0-or-later: the folder must carry the matching SOURCE beside the binary, and `docs/CREDITS.md` says
-    // where. The version is in the folder name on purpose — a mirror that drops it cannot serve two versions during an upgrade.
-    ['https://cdn.jsdelivr.net/npm/espeak-ng@1.0.2', 'espeak-ng-1.0.2'],
+    // 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.
  *
- * 🔴 AND THE ENTRY BELOW CAME BACK THE SAME DAY IT LEFT, which is worth writing rather than hiding. The Dev decided to mirror
- * both of the last two third-party addresses («Ok, vamos espelhar»), so this list was emptied — and 📏 measuring the bucket
- * after the upload showed `espeak-ng` answering **404** while the three `onnxruntime-web` files answer 200 with exactly the
- * catalogued byte counts. Nothing failed: the staging folder is marked «🔴 ON HOLD» and `upload-to-r2.ps1` skips it, because
- * espeak-ng is GPL-3.0-or-later and serving the binary obliges publishing the matching SOURCE beside it (ADR-0203 erratum,
- * issue #192). Emptying the list without checking what the bucket serves would have pointed every school at a 404.
- *
- * ⚠️ So it stays upstream until `espeak-ng-1.0.2/source/` exists. The decision to mirror it is unchanged; what is missing is
- * the obligation that decision carries, and a mirror is distribution.
+ * 📌 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 = [
-    ['https://cdn.jsdelivr.net/npm/espeak-ng@1.0.2',
-        'GPL: the mirror folder is ON HOLD until the matching source is published beside the build (issue #192)'],
-];
+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)))

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

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { CACHE_HEAVY, HEAVY_FILES, type HeavyFile } from './heavy-catalogue.js';
 export { CACHE_HEAVY, HEAVY_FILES };
-export type { HeavyFile };
 /** What happened to each entry, so the caller can tell a person. */
 export interface HeavyReport {
     readonly id: string;
@@ -28,8 +27,16 @@ export interface HeavyOptions {
      * `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. For a consumer that wants the voices and not the rest. */
+    /**
+     * 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;
 }
@@ -38,21 +45,43 @@ export interface HeavyOptions {
  *
  * · The neural voice — its model, its voices AND the runtime that speaks them: without that answer they are 372 MB taken from a
  *   school's link and a child's device for nothing.
- * · The reading models: 850 MiB for the three languages, so `reading` is not a yes or no but a LANGUAGE — the child's, known at
- *   boot. A delivery may carry more than one; a device downloads the one being read in. A game that never listens gets none.
+ * · The 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, 112 MiB for the three, and the runtime that loads them. Nothing in
+ * · 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). What decides is the delivery: `inclusionist-heavy --commands pt` puts Portuguese in it.
+ *   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 | null;
-    readonly commands?: string | null;
+    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
@@ -87,6 +116,9 @@ export declare function deliveryCacheKey(urlOrRequest: string | {
  * ⚠️ 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[]>;
 /**

package/dist-pkg/platform/heavy.js

@@ -16,43 +16,95 @@
 //     start over a resource it may not even use today.
 //  3. **IDEMPOTENT.** What is already in Cache Storage is not fetched again — which is what makes this safe to call on
 //     every start instead of only "on the first", which nobody can detect honestly.
-import { CACHE_HEAVY, HEAVY_FILES, readingLanguageOf, commandsLanguageOf } from './heavy-catalogue.js';
+import { CACHE_HEAVY, HEAVY_FILES, DELIVERY_LISTS, readingLanguageOf, commandsLanguageOf, } from './heavy-catalogue.js';
 export { CACHE_HEAVY, HEAVY_FILES };
+/**
+ * Who waits behind whom inside one language's position (`heavyAtBoot`): 0 the ways in (the command models and runtime, the
+ * camera's reader), 1 the reading and the graph runtime it opens its models with, 2 the rest — the neural voice, which the
+ * browser's voice covers until it lands.
+ */
+function waitsBehind(id) {
+    if (id.startsWith('commands:') || id.startsWith('visao:'))
+        return 0;
+    if (id.startsWith('reading:') || id.startsWith('voz:runtime:onnx'))
+        return 1;
+    return 2;
+}
 /**
  * WHAT A GAME'S START FETCHES (ADR-0216 §3): the catalogue, less what this game did not ask for.
  *
  * · The neural voice — its model, its voices AND the runtime that speaks them: without that answer they are 372 MB taken from a
  *   school's link and a child's device for nothing.
- * · The reading models: 850 MiB for the three languages, so `reading` is not a yes or no but a LANGUAGE — the child's, known at
- *   boot. A delivery may carry more than one; a device downloads the one being read in. A game that never listens gets none.
+ * · The 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, 112 MiB for the three, and the runtime that loads them. Nothing in
+ * · 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). What decides is the delivery: `inclusionist-heavy --commands pt` puts Portuguese in it.
+ *   one (ADR-0111). `commands` is a language or a LIST of them, and the models come in the list's order: the root asks for
+ *   every language the page can switch to, the child's first, because a language changed mid-game must find its model already
+ *   kept (ADR-0225 erratum, the Dev: «A entrega leva as três línguas.»). The delivery carries the three unless its
+ *   `--commands` list narrows it; a language it did not carry is a quiet 404 here and a line of `problems` when she speaks.
+ * · The Libras player (ADR-0234): the delivery's list of its avatar, clips, glosses and three.js chunk (34.9 MB in the engine's
+ *   delivery), only with `libras`: the root asks for it while deaf mode is on, so a device whose child never asks for signing
+ *   never downloads it. No game declares it either — deaf mode is the person's (ADR-0111) — and a delivery built without
+ *   `--libras` simply has none, the same quiet 404 as a missing command model. No catalogue file is the player's: it is all the
+ *   delivery's own, kept by what the delivery carries.
+ * The ids are the catalogue's files, then the delivery lists (`DELIVERY_LISTS`), by one rule.
+ *
+ * 🔴 THE ORDER IS WHO WAITS, because the download is one file at a time (rule 1): a file of a language takes that language's
+ * position in the list it was asked by, a file of no language (the runtimes, vision) takes the first, and the sort is stable. So
+ * everything of the child's language comes first, then each other language whole — her command model never waits behind 470 MiB
+ * of another language's reading.
+ * 🔴 AND WITHIN A POSITION, THE WAYS IN COME FIRST (`waitsBehind`): the command models and the camera's reader are how a child
+ * who does not press reaches the game at all (ADR-0111), and they have nothing to fall back on; the reading is the game's own
+ * listening, with nothing either; the neural voice comes last, because the browser's voice speaks meanwhile (ADR-0200). 📏 In
+ * the catalogue's order a 👄 turned on in a fresh install waited behind 336 MiB of neural voice and 378 MiB of reading for a
+ * 34 MiB model — seven seconds from a local disk, minutes on a school's link (measured on 2026-09-27).
  */
 export function heavyAtBoot(declared) {
-    const reading = declared.reading ? declared.reading.split('-')[0].toLowerCase() : null;
-    const commands = declared.commands ? declared.commands.split('-')[0].toLowerCase() : null;
-    return HEAVY_FILES.filter((p) => {
-        const language = readingLanguageOf(p.id);
+    const reading = languagesAsked(declared.reading);
+    const commands = languagesAsked(declared.commands);
+    const asked = (id) => {
+        const language = readingLanguageOf(id);
         if (language)
-            return language === reading;
+            return reading.includes(language);
         // 📌 THE COMMAND MODELS ARE A TRANSPORT'S, not a game's: no cartridge declares them, because a child who speaks instead of
-        // pressing is reaching the controller, and a cartridge does not get to deny her a way in (ADR-0111). The LANGUAGE is still
-        // asked — 112 MiB for the three — and the runtime comes with whichever one does.
-        const commanded = commandsLanguageOf(p.id);
+        // pressing is reaching the controller, and a cartridge does not get to deny her a way in (ADR-0111). The LANGUAGES are
+        // still asked, and the runtime comes with whichever one is.
+        const commanded = commandsLanguageOf(id);
         if (commanded)
-            return commanded === commands;
-        if (p.id.startsWith('commands:runtime'))
-            return !!commands;
-        if (p.id.startsWith('voz:runtime:onnx'))
-            return declared.kokoro || !!reading;
-        return declared.kokoro || !(p.id.startsWith('voz:kokoro:') || p.id.startsWith('voz:runtime:'));
-    }).map((p) => p.id);
+            return commands.includes(commanded);
+        if (id.startsWith('commands:runtime'))
+            return commands.length > 0;
+        if (id.startsWith('libras:'))
+            return !!declared.libras;
+        if (id.startsWith('voz:runtime:onnx'))
+            return declared.kokoro || reading.length > 0;
+        return declared.kokoro || !(id.startsWith('voz:kokoro:') || id.startsWith('voz:runtime:'));
+    };
+    const rank = (id) => {
+        const read = readingLanguageOf(id);
+        if (read)
+            return reading.indexOf(read);
+        const spoken = commandsLanguageOf(id);
+        return spoken ? commands.indexOf(spoken) : 0;
+    };
+    return [
+        // `Array.prototype.sort` is stable (ES2019): within a position and a kind, the catalogue's order — a runtime before its model
+        ...HEAVY_FILES.map((p) => p.id).filter(asked).sort((a, b) => rank(a) - rank(b) || waitsBehind(a) - waitsBehind(b)),
+        ...DELIVERY_LISTS.map((l) => l.id).filter(asked),
+    ];
+}
+/** The base languages asked — one tag or a list of them — without repeats, in the order asked (`es-MX` asks for `es`). */
+function languagesAsked(asked) {
+    const tags = asked == null ? [] : typeof asked === 'string' ? [asked] : asked;
+    return [...new Set(tags.filter(Boolean).map((tag) => tag.split('-')[0].toLowerCase()))];
 }
 /**
  * WHERE THE DELIVERY SERVES A HEAVY FILE (ADR-0177, issue #173): `heavy/<host><path>` beside the page. The child's device
@@ -91,20 +143,28 @@ export function deliveryCacheKey(urlOrRequest) {
  * ⚠️ ENTRIES WITHOUT A `url` ARE NOT SKIPPED IN SILENCE — they return `sem-fonte`. It is the difference between "this
  * subsystem has nowhere to come from yet" and "this subsystem is handled", exactly the distinction ADR-0119 measured as
  * missing: the engine PROMISED four things and delivered one, with nothing saying so.
+ *
+ * The files handed in `also` come first (the declared library fonts), then the catalogue's, then the delivery's lists
+ * (`DELIVERY_LISTS`), each list ONE report for all its files.
  */
 export async function downloadHeavy(options) {
-    const targets = options.only ? HEAVY_FILES.filter((p) => options.only.includes(p.id)) : HEAVY_FILES;
+    const targets = [...(options.also ?? []), ...(options.only
+            ? [...new Set(options.only)].flatMap((id) => HEAVY_FILES.filter((p) => p.id === id))
+            : HEAVY_FILES)];
+    const lists = DELIVERY_LISTS.filter((l) => !options.only || options.only.includes(l.id));
     const out = [];
     const record = (r) => { out.push(r); options.onProgress?.(r); };
     const { cacheStorage, fetch: fetchFile, digest, base } = options;
     if (!cacheStorage || !fetchFile) {
-        for (const p of targets)
+        for (const p of [...targets, ...lists])
             record({ id: p.id, outcome: 'falhou', error: 'sem Cache Storage ou sem fetch' });
         return out;
     }
     const tools = { cache: await cacheStorage.open(CACHE_HEAVY), fetchFile, digest, base };
     for (const p of targets)
         record(await fetchOne(p, tools));
+    for (const l of lists)
+        record(await keepListed(l, tools));
     return out;
 }
 /** One file's fate: already kept, fetched from the delivery and checked, or refused — always with the reason. */
@@ -142,6 +202,101 @@ async function keepIfChecked(p, url, resp, t) {
     await t.cache.put(url, new Response(body, { status: resp.status, statusText: resp.statusText, headers: resp.headers }));
     return { id: p.id, outcome: 'baixado', bytes: p.bytes };
 }
+/** The header a file kept from a delivery's list carries its listed sha256 in: how a later start knows it is kept, and current. */
+const LISTED_SHA256 = 'x-inclusionist-sha256';
+/**
+ * The files a delivery's list names, or a THROW saying why the list is refused whole: a list with no `files`, an entry without a
+ * path or a sha256, or one whose address falls outside the list's folders (a `..`, another origin, a query) — the list may only
+ * put the player's own files in the checked cache, never the game's page nor anything a route outside those folders serves.
+ */
+function listedFiles(data, l, base) {
+    const files = data?.files;
+    if (!Array.isArray(files))
+        throw new Error('its `files` is missing');
+    const folders = l.folders.map((folder) => new URL(folder, base).href);
+    return files.map((f) => {
+        const { path, sha256 } = (f ?? {});
+        if (typeof path !== 'string' || typeof sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(sha256)) {
+            throw new Error(`a listed file is malformed: ${JSON.stringify(f)}`);
+        }
+        const at = new URL(path, base);
+        const url = at.href;
+        if (at.search || at.hash || !folders.some((folder) => url.startsWith(folder) && url.length > folder.length)) {
+            throw new Error(`it names ${path}, outside ${l.folders.join(' and ')}`);
+        }
+        return { path, url, sha256 };
+    });
+}
+/**
+ * A DELIVERY'S LIST, KEPT FILE BY FILE (ADR-0234, pillar 8): the list is read from the page's origin, and each file it names is
+ * fetched from there, CHECKED against its listed sha256, and kept under its own address, where the service worker answers it
+ * offline. A file already kept with that sha256 is not fetched again; a body that is not the listed one is never kept, and the
+ * report names it. One report for the list: `baixado` with the bytes fetched, `ja-tinha`, or `falhou` with the files refused.
+ */
+async function keepListed(l, t) {
+    const failed = (error) => ({ id: l.id, outcome: 'falhou', error });
+    const digest = t.digest;
+    if (!digest)
+        return failed('this host cannot compute a sha256 (crypto.subtle needs a secure context)');
+    const files = await readList(l, t);
+    if (typeof files === 'string')
+        return failed(files);
+    const refused = [];
+    let bytes = 0;
+    let fetched = 0;
+    for (const f of files) {
+        const kept = await keepListedFile(f, t, digest);
+        if (typeof kept === 'string')
+            refused.push(`${f.path}: ${kept}`);
+        else if (kept !== null) {
+            bytes += kept;
+            fetched += 1;
+        }
+    }
+    if (!refused.length)
+        return fetched ? { id: l.id, outcome: 'baixado', bytes } : { id: l.id, outcome: 'ja-tinha' };
+    const more = refused.length > 5 ? `; and ${refused.length - 5} more` : '';
+    return failed(`${refused.length} of ${files.length} files of ${l.path} not kept: ${refused.slice(0, 5).join('; ')}${more}`);
+}
+/** The list's files, or why it is refused whole (not there, not JSON, or naming what it may not). */
+async function readList(l, t) {
+    try {
+        // never an old copy of the list: it is what says which files are current
+        const resp = await t.fetchFile(new URL(l.path, t.base).href, { cache: 'no-store' });
+        if (!resp.ok)
+            return `HTTP ${resp.status} — ${l.path}`;
+        return listedFiles(await resp.json(), l, t.base);
+    }
+    catch (e) {
+        return `the list ${l.path} is refused: ${e instanceof Error ? e.message : String(e)}`;
+    }
+}
+/** One listed file: `null` when it is already kept with its listed hash, the bytes kept, or why it was not kept. */
+async function keepListedFile(f, t, digest) {
+    try {
+        if ((await t.cache.match(f.url))?.headers.get(LISTED_SHA256) === f.sha256)
+            return null;
+        /*
+         * 📌 THE LISTED HASH GOES IN THE QUERY: the service worker answers these folders from this cache by their address, so a file
+         * the list CHANGED would be answered with the copy it replaces. Another address reaches the delivery, and the old copy stays
+         * kept until the new one is checked — offline a child keeps the player she had.
+         */
+        const resp = await t.fetchFile(`${f.url}?sha256=${f.sha256}`);
+        if (!resp.ok)
+            return `HTTP ${resp.status}`;
+        const body = await resp.arrayBuffer();
+        const got = await digest(body);
+        if (got !== f.sha256)
+            return `sha256 mismatch: expected ${f.sha256}, got ${got} — not kept`;
+        const headers = new Headers(resp.headers);
+        headers.set(LISTED_SHA256, f.sha256);
+        await t.cache.put(f.url, new Response(body, { status: resp.status, statusText: resp.statusText, headers }));
+        return body.byteLength;
+    }
+    catch (e) {
+        return e instanceof Error ? e.message : String(e);
+    }
+}
 /**
  * THE SHA-256 OF A BODY AS LOWERCASE HEX, by the `crypto.subtle` it is handed (issue #168) — or `null` when there is none,
  * which is a host outside a secure context: the answer `HeavyOptions.digest` reads as «cannot hash, so keep nothing».

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

@@ -1,19 +1,26 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** What the caller provides. Nothing here knows the neural engine, Web Audio or the browser. */
-export interface SpeechEngine<Audio, Fonte> {
-    /** Text → audio. ASYNCHRONOUS on purpose: it is where neural synthesis spends its time. */
-    synthesize(text: string): Promise<Audio>;
+/**
+ * What the caller provides. Nothing here knows the neural engine, Web Audio or the browser. `Request` is what one utterance
+ * asks for: a text by default, or a text with the voice that reads it (ADR-0243 §2).
+ */
+export interface SpeechEngine<Audio, Fonte, Request = string> {
+    /** Request → audio. ASYNCHRONOUS on purpose: it is where neural synthesis spends its time. */
+    synthesize(request: Request): Promise<Audio>;
     /** Starts playing and returns the source, so it can be stopped. `null` = it could not play right now. */
     play(audio: Audio, onEnded: () => void): Fonte | null;
     /** Silences the source. Called with what `play` returned, and never with `null`. */
     stop(playing: Fonte): void;
 }
-export interface InterruptibleSpeech {
-    /** Speaks `text`, SILENCING at once whatever is speaking. It does not queue: the latest request is the one that counts. */
-    speak(text: string): void;
+export interface InterruptibleSpeech<Request = string> {
+    /**
+     * Speaks `request`, SILENCING at once whatever is speaking. It does not queue: the latest request is the one that counts.
+     * `finished` is called ONCE, when this utterance is over for any reason — it ended, it was silenced or overtaken, or it could
+     * not be synthesised or played — so a caller speaking parts in order (ADR-0243 §1) knows when to go on, and never waits forever.
+     */
+    speak(request: Request, finished?: () => void): void;
     /** Silences and forgets. Used when a menu closes or narration is switched off. */
     silence(): void;
     /** Is anything playing? For tests and debugging only — the policy does not depend on it. */
     speaking(): boolean;
 }
-export declare function createInterruptibleSpeech<Audio, Fonte>(engine: SpeechEngine<Audio, Fonte>): InterruptibleSpeech;
+export declare function createInterruptibleSpeech<Audio, Fonte, Request = string>(engine: SpeechEngine<Audio, Fonte, Request>): InterruptibleSpeech<Request>;