@the-inclusionist/engine 9.0.0 → 10.0.0

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

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { recognitionRoute, type RecognitionApi, type OnDeviceAvailability, type RecognitionInstance } from './speech-recognition.js';
+/** The browser's recognition object, with the parts a reading uses. Assigned handlers, as the API has them. */
+export interface ListeningSession extends RecognitionInstance {
+    start(): void;
+    stop(): void;
+    onresult: ((ev: {
+        readonly results: ArrayLike<ArrayLike<{
+            readonly transcript: string;
+        }> & {
+            readonly isFinal: boolean;
+        }>;
+    }) => void) | null;
+    onerror: ((ev: {
+        readonly error?: string;
+    }) => void) | null;
+    onend: (() => void) | null;
+}
+/** What a reading gives back. `route` is which recogniser heard it — for `problems` and for a lab, never for the game's logic. */
+export interface Heard {
+    readonly text: string;
+    readonly route: 'webspeech-local' | 'model';
+    /** The reading stopped because the child went quiet, because the time ran out, or because someone asked it to stop. */
+    readonly ended: 'silence' | 'timeout' | 'asked';
+}
+export interface ReadingDeps {
+    /** The BCP-47 tag of the child's language (`core/i18n.bcp47`). */
+    readonly language: () => string;
+    /** The browser's `SpeechRecognition` constructor, or nothing where there is none. */
+    readonly api?: RecognitionApi | null;
+    readonly now: () => number;
+    readonly every: (fn: () => void, ms: number) => unknown;
+    readonly stopEvery: (h: unknown) => void;
+    /** A line for `problems`, written once per reason (ADR-0169). */
+    readonly report: (line: string) => void;
+    /**
+     * The engine's own recogniser, when there is one to load — the models of ADR-0201, lazily (`platform/reading-runtime`).
+     * Absent: the refusal below.
+     */
+    readonly model?: (language: string) => Promise<{
+        transcribe(samples: Float32Array): Promise<string>;
+    }>;
+    /**
+     * The microphone, as 16 kHz mono samples. The model route needs sound, and the browser route does not: the browser's own
+     * recogniser opens the microphone itself. ⚠️ Absent with a model present is a reading that REFUSES and says which half is
+     * missing — never one that answers an empty sentence, which a game would show a child as «you read nothing».
+     */
+    readonly record?: (options: ListenOptions) => Promise<Float32Array>;
+    readonly route?: typeof recognitionRoute;
+    readonly createSession?: (api: RecognitionApi, language: string) => ListeningSession;
+}
+export interface ListenOptions {
+    /** How long a silence ends the reading. Default 1.5 s: shorter cuts a child who is thinking between words. */
+    readonly silenceMs?: number;
+    /** The ceiling, so a forgotten microphone does not listen for ever. Default 30 s, the window Whisper reads at once. */
+    readonly maxMs?: number;
+}
+export interface Reading {
+    /** Listens until the child goes quiet, and answers with what was read. */
+    listen(options?: ListenOptions): Promise<Heard>;
+    /** Gives the microphone back now; the reading in hand answers with what it has. */
+    stop(): void;
+    /** Can this device serve the child's language at all? Answers with the reason when it cannot. */
+    ready(): Promise<{
+        readonly can: boolean;
+        readonly why: OnDeviceAvailability | 'sem-api' | 'sem-processamento-local' | 'no-model';
+    }>;
+}
+export declare function createReading(d: ReadingDeps): Reading;

package/dist-pkg/platform/reading.js

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/reading — THE CHILD READS ALOUD, AND THE GAME RECEIVES TEXT (ADR-0216, issue #200).
+//
+// The Dev, 2026-09-21: «a engine deve oferecer objetos de leitura e TTS. O jogo não deve precisar saber como isso funciona, apenas
+// deve pedir para ouvir e receber o texto.» So this module answers ONE question — what did the child say — and keeps the rest:
+// which recogniser heard it, in which language, and whether it may run at all.
+//
+// · ON THE DEVICE OR NOT AT ALL (ADR-0200 erratum). The browser's recogniser is used only where it says it recognises on the device
+//   AND the language is installed there (`platform/speech-recognition`). Anything else waits for the models the project carries
+//   (Whisper for pt, Moonshine for en and es — ADR-0201), which arrive through `engine` below and are not built yet: until then a
+//   request is REFUSED with its reason, never answered by a recogniser that would send a child's voice to a server.
+// · A reading ends when the child stops talking (`silenceMs`) or when the time runs out (`maxMs`), whichever comes first, and what
+//   was heard so far is what the game gets — a child who stops mid-sentence is not an error.
+// · Asking twice does not open two microphones: the second caller waits on the same reading.
+import { recognitionRoute, createOnDeviceRecognition } from './speech-recognition.js';
+const SILENCE_MS = 1500;
+const MAX_MS = 30_000;
+export function createReading(d) {
+    const routeOf = d.route ?? recognitionRoute;
+    const make = d.createSession ?? ((api, language) => createOnDeviceRecognition(api, language));
+    const said = new Set();
+    const once = (key, line) => { if (!said.has(key)) {
+        said.add(key);
+        d.report(line);
+    } };
+    let inFlight = null;
+    let askToStop = null;
+    async function ready() {
+        const { route: route, status: state } = await routeOf(d.language(), d.api);
+        if (route === 'webspeech-local')
+            return { can: true, why: state };
+        return { can: !!d.model, why: d.model ? state : 'no-model' };
+    }
+    function byBrowser(api, options) {
+        const silenceMs = options.silenceMs ?? SILENCE_MS;
+        const maxMs = options.maxMs ?? MAX_MS;
+        return new Promise((resolve, reject) => {
+            let session;
+            try {
+                session = make(api, d.language());
+            }
+            catch (e) {
+                reject(e instanceof Error ? e : new Error(String(e)));
+                return;
+            }
+            let text = '', lastSound = d.now(), done = false;
+            const ticker = d.every(() => {
+                if (done)
+                    return;
+                const quietFor = d.now() - lastSound;
+                if (quietFor >= silenceMs && text)
+                    finish('silence');
+                else if (d.now() - startedAt >= maxMs)
+                    finish('timeout');
+            }, 100);
+            const startedAt = d.now();
+            const finish = (ended) => {
+                if (done)
+                    return;
+                done = true;
+                d.stopEvery(ticker);
+                askToStop = null;
+                try {
+                    session.stop();
+                }
+                catch { /* a session that already ended is not a failure */ }
+                resolve({ text: text.trim(), route: 'webspeech-local', ended });
+            };
+            askToStop = () => finish('asked');
+            session.onresult = (ev) => {
+                let together = '';
+                for (let i = 0; i < ev.results.length; i++)
+                    together += `${ev.results[i][0].transcript} `;
+                text = together;
+                lastSound = d.now();
+            };
+            session.onerror = (ev) => {
+                // ⚠️ A refusal is not a silence: a child waiting to be heard must not wait for ever, and the adult must read why.
+                once('error', `reading: the browser's recogniser stopped (${ev.error ?? 'unknown'}) — the child reads and nothing is heard; `
+                    + 'allow the microphone for this page, or install the language on the device');
+                if (!done) {
+                    done = true;
+                    d.stopEvery(ticker);
+                    askToStop = null;
+                    reject(new Error(ev.error ?? 'recognition failed'));
+                }
+            };
+            session.onend = () => { if (!done)
+                finish(text ? 'silence' : 'asked'); };
+            session.start();
+        });
+    }
+    return {
+        ready,
+        stop() { askToStop?.('asked'); },
+        async listen(options = {}) {
+            if (inFlight)
+                return inFlight; // one microphone, one reading: the second caller waits on the first
+            const { route: route, status: state } = await routeOf(d.language(), d.api);
+            if (route !== 'webspeech-local') {
+                if (!d.model) {
+                    once('sem-route', `reading: nothing on this device can hear ${d.language()} (${state}) — the child's reading is not assessed; `
+                        + 'install the language in the browser, or build a delivery that carries the reading model for this language');
+                    throw new Error(`reading is not available here: ${state}`);
+                }
+                if (!d.record) {
+                    once('sem-microfone', `reading: the model for ${d.language()} is here and nothing captures the child's voice — `
+                        + 'the reading cannot run; pass `record`, the 16 kHz samples the model reads');
+                    throw new Error('reading has no microphone here');
+                }
+                const capture = d.record;
+                inFlight = (async () => {
+                    const [transcriber, samples] = await Promise.all([d.model(d.language()), capture(options)]);
+                    return { text: (await transcriber.transcribe(samples)).trim(), route: 'model', ended: 'silence' };
+                })();
+            }
+            else {
+                inFlight = byBrowser(d.api, options);
+            }
+            try {
+                return await inFlight;
+            }
+            finally {
+                inFlight = null;
+            }
+        },
+    };
+}

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

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** What the browser answers about recognising a language on the device (Chrome's `SpeechRecognition.available`). */
+export type OnDeviceAvailability = 'available' | 'downloadable' | 'downloading' | 'unavailable';
+/** The part of the browser's `SpeechRecognition` constructor this module reads. */
+export interface RecognitionApi {
+    new (): RecognitionInstance;
+    readonly prototype: object;
+    readonly available?: (options: {
+        langs: readonly string[];
+        processLocally: boolean;
+    }) => Promise<OnDeviceAvailability>;
+}
+export interface RecognitionInstance {
+    lang: string;
+    processLocally?: boolean;
+    continuous: boolean;
+    interimResults: boolean;
+}
+export interface RecognitionRoute {
+    /** `webspeech-local`: the browser recognises on the device. `recuo`: the engine's own recogniser. */
+    readonly route: 'webspeech-local' | 'recuo';
+    /** Why: the browser's answer, or what is missing. */
+    readonly status: OnDeviceAvailability | 'sem-api' | 'sem-processamento-local';
+}
+/**
+ * THE ROUTE, measured on the device (ADR-0200 §3). ⚠️ A browser whose recognition object has no `processLocally` would take the
+ * flag as an unknown property and recognise on its servers — it is never the route, whatever it says about availability.
+ */
+export declare function recognitionRoute(language: string, api: RecognitionApi | null | undefined): Promise<RecognitionRoute>;
+/** A recognition object set to recognise on the device, continuously, with partial hypotheses. Refuses a browser that cannot. */
+export declare function createOnDeviceRecognition(api: RecognitionApi, language: string): RecognitionInstance;
+/** A command heard: a direction word, or the name of an item of the open menu. */
+export type HeardCommand = {
+    readonly kind: 'palavra';
+    readonly word: string;
+} | {
+    readonly kind: 'item';
+    readonly name: string;
+};
+/** How a heard text is compared: lower case, letters and spaces only. */
+export declare const spokenText: (t: string) => string;
+export interface CommandReader {
+    /** The menu's item names now on screen (already as spoken). */
+    items(names: readonly string[]): void;
+    /**
+     * One hypothesis of utterance `index`: returns the commands it completes that were not returned before for that utterance. A
+     * partial one holds back its last name while another item's name continues it («voltar» may become «voltar ao jogo»).
+     */
+    read(index: number, text: string, final: boolean): readonly HeardCommand[];
+}
+export declare function createCommandReader(vocabulary: readonly string[]): CommandReader;

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

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/speech-recognition — which recogniser hears the child, and what a command is in what was heard (ADR-0200 and its
+// erratum, ADR-0193, ADR-0194; issue #190).
+//
+// The browser's recognition comes first, and ONLY on the device: the Dev, «Só local, voz da criança não deve sair do aparelho». So
+// Web Speech is the route only where the browser can say it recognises on the device (`processLocally`) AND the language is
+// installed there; anything else — no API, a browser that would ignore the flag and send the voice to its servers, a language to
+// download — falls back to the recognisers the engine carries (Vosk for commands). The words heard, whoever heard them, become
+// commands the same way: the direction words and the open menu's item names, the longest name first, a partial hypothesis firing
+// what it already holds and a name another item's name continues waiting for the end (ADR-0194 §3).
+/**
+ * THE ROUTE, measured on the device (ADR-0200 §3). ⚠️ A browser whose recognition object has no `processLocally` would take the
+ * flag as an unknown property and recognise on its servers — it is never the route, whatever it says about availability.
+ */
+export async function recognitionRoute(language, api) {
+    if (!api)
+        return { route: 'recuo', status: 'sem-api' };
+    if (!('processLocally' in api.prototype) || typeof api.available !== 'function')
+        return { route: 'recuo', status: 'sem-processamento-local' };
+    let availability;
+    try {
+        availability = await api.available({ langs: [language], processLocally: true });
+    }
+    catch {
+        return { route: 'recuo', status: 'unavailable' };
+    }
+    return { route: availability === 'available' ? 'webspeech-local' : 'recuo', status: availability };
+}
+/** A recognition object set to recognise on the device, continuously, with partial hypotheses. Refuses a browser that cannot. */
+export function createOnDeviceRecognition(api, language) {
+    if (!('processLocally' in api.prototype))
+        throw new Error('speech recognition on the device is not supported here: the voice would leave the device');
+    const rec = new api();
+    rec.lang = language;
+    rec.processLocally = true;
+    rec.continuous = true;
+    rec.interimResults = true;
+    return rec;
+}
+/** How a heard text is compared: lower case, letters and spaces only. */
+export const spokenText = (t) => t.toLowerCase().normalize('NFC').replace(/[^\p{L}\s]/gu, ' ').replace(/\s+/g, ' ').trim();
+export function createCommandReader(vocabulary) {
+    const spokenForms = vocabulary.map(spokenText);
+    let spokenItems = [];
+    const firedCount = new Map();
+    const phrasesIn = (text) => {
+        const p = spokenText(text).split(' ').filter(Boolean);
+        const found = [];
+        for (let i = 0; i < p.length;) {
+            let matched = null;
+            for (let n = p.length - i; n >= 1; n--) {
+                const f = p.slice(i, i + n).join(' ');
+                if (spokenItems.includes(f) || spokenForms.includes(f)) {
+                    matched = f;
+                    i += n;
+                    break;
+                }
+            }
+            if (matched)
+                found.push(matched);
+            else
+                i++;
+        }
+        return found;
+    };
+    return {
+        items(names) { spokenItems = names.map(spokenText); },
+        read(index, text, final) {
+            const found = phrasesIn(text);
+            const alreadyFired = firedCount.get(index) ?? 0;
+            const newCommands = [];
+            for (let i = alreadyFired; i < found.length; i++) {
+                const f = found[i];
+                if (!final && i === found.length - 1 && spokenItems.some((o) => o !== f && o.startsWith(f + ' ')))
+                    break;
+                newCommands.push(spokenItems.includes(f) ? { kind: 'item', name: f } : { kind: 'palavra', word: f });
+                firedCount.set(index, i + 1);
+            }
+            if (final)
+                firedCount.delete(index);
+            return newCommands;
+        },
+    };
+}

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

@@ -1,2 +1,15 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-export declare function gameSay(text: string): void;
+/**
+ * THE BROWSER'S SPEECH, lent by whoever holds the window (the composition root, from `host.win`). The same port
+ * `platform/tts` receives. `synth()` is asked at every utterance and may answer `null`: a browser without speech synthesis.
+ */
+export interface SpeechPort {
+    synth(): SpeechSynthesis | null;
+    utterance(text: string): SpeechSynthesisUtterance;
+}
+/** What the literacy voice reads: the browser's speech, and the master sound it obeys. */
+export interface GameVoice extends SpeechPort {
+    soundOn(): boolean;
+    volume(): number;
+}
+export declare function gameSay(voice: GameVoice, text: string): void;

package/dist-pkg/platform/speech.js

@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// platform/speech.ts — voz do LETRAMENTO (gameSay): fala pt-BR SEMPRE-ativa (independe do toggle 'Narração
-// (TTS)' do mixer), pela voz nativa do navegador. Escolhe uma voz pt-BR e evita pt-PT. Módulo-folha (só áudio).
-// O TTS do MENU (narrate/ttsSpeak + motores neurais Piper/Kokoro/…) é outro caminho, gated pelo mixer — fica no game.js.
-import { soundOn, volume } from './audio.js';
-function ptbrVoice() {
+// platform/speech.ts — the LITERACY voice (gameSay): pt-BR speech that is ALWAYS on (independent of the mixer's
+// narration toggle), through the browser's native voice. It picks a pt-BR voice and avoids pt-PT. A helper that holds nothing:
+// it takes the browser's speech and the master sound as a parameter (ADR-0232 D4, erratum D3 point 2).
+// The MENU's TTS (narrate/ttsSpeak and the Kokoro neural engine) is another path, gated by the mixer — `platform/tts`.
+function ptbrVoice(ss) {
     try {
-        const vs = (window.speechSynthesis && window.speechSynthesis.getVoices()) || [];
+        const vs = ss.getVoices() || [];
         if (!vs.length)
             return null;
         return vs.find((v) => /pt[-_]?br/i.test(v.lang)) || vs.find((v) => /pt/i.test(v.lang) && /bras|brazil/i.test(v.name)) || vs.find((v) => /pt/i.test(v.lang) && !/pt[-_]?pt/i.test(v.lang)) || null;
@@ -14,21 +14,21 @@ function ptbrVoice() {
         return null;
     }
 }
-// FORÇA pt-BR (não usa a voz do mixer, que pode ser pt-PT). Volume ×1.4 para a fala soar acima dos efeitos.
-export function gameSay(text) {
-    if (!text || !soundOn)
+// FORCES pt-BR (not the mixer's voice, which may be pt-PT). Volume ×1.4 so the speech sits above the effects.
+export function gameSay(voice, text) {
+    if (!text || !voice.soundOn())
         return;
     try {
-        const ss = window.speechSynthesis;
+        const ss = voice.synth();
         if (!ss)
             return;
         ss.cancel();
-        const u = new SpeechSynthesisUtterance(text);
+        const u = voice.utterance(text);
         u.lang = 'pt-BR';
-        const v = ptbrVoice();
+        const v = ptbrVoice(ss);
         if (v)
             u.voice = v;
-        u.volume = Math.min(1, volume * 1.4);
+        u.volume = Math.min(1, voice.volume() * 1.4);
         ss.speak(u);
     }
     catch (e) { /* noop */ }

package/dist-pkg/platform/storage-keys.d.ts

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * The full name of a key in the GAME's scope.
+ *
+ * ⚠️ THE ID COMES IN AS AN ARGUMENT; it was once a constant. By ADR-0080's test — *would a second game want a different
+ * value here?* — the answer is yes, at once: two games in the same browser profile collided on every game-scoped key, and
+ * one overwrote the other's progress with no error at all.
+ *
+ * ⚠️ AND THE ID DOES NOT COME FROM THE DECLARATION, the obvious design. It cannot: a game's state is read before any
+ * `createGame()`, so an id from the declaration would arrive after the keys were resolved — against nothing, in silence.
+ * Whoever knows its own id is the GAME, which passes it as its own constant; ADR-0080 forbids the ENGINE from knowing it,
+ * not the game.
+ */
+export declare function gameKey(gameId: string, keyName: string): string;
+export declare const KEYS: {
+    onebtn: string;
+    wheelchair: string;
+    modocego: string;
+    caneDiv: string;
+    hearingloss: string;
+    activity: (gameId: string) => string;
+    activityLegado: string;
+    quizlevel: (gameId: string) => string;
+    quizlevelLegado: string;
+    cenario: (gameId: string) => string;
+    cenarioLegado: string;
+    tabsel: (gameId: string) => string;
+    tabselLegado: string;
+    fracnot: (gameId: string) => string;
+    fracnotLegado: string;
+    viz: string;
+    lq: string;
+    cbsafe: string;
+    ownercolors: string;
+    outfg: string;
+    outbg: string;
+    hcrole: string;
+    juice: string;
+    crt: string;
+    crtLegacy: string;
+    ttsEngine: string;
+    ttsVoice: string;
+    ttsVoz: string;
+    lang: string;
+    letterCase: string;
+    captions: string;
+    tea: string;
+    menuIndex: string;
+    fontKey: string;
+    padDesign: string;
+    padDir: string;
+    touchmap: string;
+    padBtnMm: string;
+    padGapMm: string;
+    padStickMm: string;
+    padTravelMm: string;
+    padDpadMm: string;
+    reducedMotion: string;
+    toggleMoveLegacy: string;
+    /**
+     * @deprecated ⚠️ THE LEGACY visual-mode KEY — ONE value, from when only one fitted (issue #104).
+     *
+     * It is still READ, which is what keeps the child from losing what they chose; it is still WRITTEN while the controls
+     * write one value at a time, because an old reader does `if (v && VIZ_BY_KEY[v])` and would reject a JSON — writing
+     * the new shape HERE would erase their setting in silence, exactly the defect the migration exists not to commit.
+     */
+    vizP: (i: number) => string;
+    /**
+     * The two-axis VISUAL STATE, in JSON (ADR-0076, issue #104).
+     *
+     * ⚠️ A NEW KEY BESIDE THE OLD ONE, not the same key with new content. The same design as the `visual` field beside
+     * `viz`: both shapes coexist while both have readers, each reads the one it understands, and the old one dies only
+     * when nobody reads it. `migrateVisual` accepts both, so the fallback — new key absent, old key present — returns
+     * exactly what the child chose.
+     */
+    visualP: (i: number) => string;
+    sinkP: (i: number) => string;
+    easyP: (i: number) => string;
+    /**
+     * ⚠️ THE TWO BELOW ARE LEGACY KEYS (ADR-0104 §C, issue #114). They are still READ — it is the child's setting, and
+     * inheriting it keeps them from losing it — and never written again. What is written is the key WITH A TRANSPORT,
+     * because the toggle belongs to the DEVICE and not the person: turning it on for the touch pad, where nobody holds a
+     * virtual button comfortably, turned it on for the keyboard too, where holding a key is exactly what the child can do.
+     *
+     * ⚠️ AND THE NEW KEY DOES NOT LIVE HERE, on purpose. It is `latchKey`, in `input/latch-scope` — `platform/` does not
+     * import `input/`, the layer above. Building it here would need either a backwards edge or a second copy of the name.
+     * Whoever owns the name is whoever knows the transport rule.
+     */
+    toggleMoveP: (i: number) => string;
+    toggleRunP: (i: number) => string;
+    rmWalkP: (i: number) => string;
+    rmBreathP: (i: number) => string;
+    rmFlavorP: (i: number) => string;
+    attract: (gameId: string, scenery: string) => string;
+    attractLegado: (scenery: string) => string;
+};

package/dist-pkg/platform/storage-keys.js

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/storage-keys.ts — THE NAMES OF WHAT IS STORED: the register of known keys and the rule that scopes a game's key.
+//
+// 📌 A STATELESS MODULE ON PURPOSE (ADR-0232, issue #207): a key is a string, and a module that only needs the NAME must not
+// import `platform/storage`, which reaches `localStorage`, to get it. `input/touch` and `ui/settings-mobility` read and write
+// through an injected store and import only these names.
+//
+// 📌 WHY `platform/` AND NOT `core/` (ADR-0173): the table names places in the browser's persistent storage, and every module
+// that reads it is at `platform` or above — the storage itself, the input, the renderer, the panels, and the games. `core/`
+// reaches storage only through the port `core/state.createSettingsStore` receives (ADR-0178), which carries the keys it needs; putting
+// the table in `core/` would invite the core to name storage places again, the dependency ADR-0178 took out.
+//
+// 📌 THIS IS THE ONLY HOME OF `KEYS` (ADR-0232 D2b): `platform/storage` is a factory now and publishes no key table. The
+// port `core/state.createSettingsStore` receives carries the table beside the store — the root passes `{ ...store, KEYS }`.
+/**
+ * The full name of a key in the GAME's scope.
+ *
+ * ⚠️ THE ID COMES IN AS AN ARGUMENT; it was once a constant. By ADR-0080's test — *would a second game want a different
+ * value here?* — the answer is yes, at once: two games in the same browser profile collided on every game-scoped key, and
+ * one overwrote the other's progress with no error at all.
+ *
+ * ⚠️ AND THE ID DOES NOT COME FROM THE DECLARATION, the obvious design. It cannot: a game's state is read before any
+ * `createGame()`, so an id from the declaration would arrive after the keys were resolved — against nothing, in silence.
+ * Whoever knows its own id is the GAME, which passes it as its own constant; ADR-0080 forbids the ENGINE from knowing it,
+ * not the game.
+ */
+export function gameKey(gameId, keyName) { return 'incl.' + gameId + '.' + keyName; }
+// The register of known keys (documentation in ONE place; the source of truth is still their use). Keys taking an
+// argument are parameterised by player, scenery or game. The two scopes — the CHILD's `incl_*` and the GAME's
+// `incl.<game>.*` — are explained in `platform/storage`.
+export const KEYS = {
+    // motor/hearing empathy
+    onebtn: 'incl_onebtn', wheelchair: 'incl_wheelchair', modocego: 'incl_modocego', caneDiv: 'incl_cane_div',
+    hearingloss: 'incl_hearingloss',
+    // activity / quiz / scenery — the GAME's SCOPE (see the two scopes in `platform/storage`). `*Legado` is the old name, which
+    // the read inherits from once; the write goes to the new one only.
+    //
+    // ⚠️ THEY ARE FUNCTIONS OF THE GAME'S ID, and the child's are strings. The difference of SHAPE is what prevents the
+    // mistake: a child's preference cannot be prefixed by accident, because it has nowhere to take the id — and a
+    // play-through's key cannot be left unscoped, because without the argument it does not compile. The rule that once
+    // lived only in a comment lives in the type.
+    activity: (gameId) => gameKey(gameId, 'activity'), activityLegado: 'incl_activity',
+    quizlevel: (gameId) => gameKey(gameId, 'quizlevel'), quizlevelLegado: 'incl_quizlevel',
+    cenario: (gameId) => gameKey(gameId, 'cenario'), cenarioLegado: 'incl_cenario',
+    tabsel: (gameId) => gameKey(gameId, 'tabsel'), tabselLegado: 'incl_tabsel',
+    fracnot: (gameId) => gameKey(gameId, 'fracnot'), fracnotLegado: 'incl_fracnot',
+    // visual / contrast / colour
+    viz: 'incl_viz', lq: 'incl_lq', cbsafe: 'incl_cbsafe', ownercolors: 'incl_ownercolors',
+    outfg: 'incl_outfg', outbg: 'incl_outbg', hcrole: 'incl_hcrole', juice: 'incl_juice', crt: 'incl_crt2',
+    crtLegacy: 'incl_crt', // the old (boolean) format; render/crt migrates it to incl_crt2 on the first read
+    // audio / voice / i18n
+    ttsEngine: 'incl_tts_engine', ttsVoice: 'incl_tts_voice', ttsVoz: 'incl_tts_voz', lang: 'incl_lang', // audiocat_{k}
+    // communication / captions (ADR-0028: every panel persists)
+    letterCase: 'incl_lettercase', captions: 'incl_captions',
+    // ⚠️ THE AUTISM-SUPPORT LEVEL (calm / quiet) PERSISTS. It used not to: the extraction from the monolith PRESERVED "never
+    // written to storage" verbatim, which is not the same as deciding it. The cost fell on the child who needs it most —
+    // whoever uses quiet mode set it again every session, and unexpected noise costs them most. ADR-0028: every panel persists.
+    tea: 'incl_tea',
+    menuIndex: 'incl_menuindex', // the "6 of 10" at the end of an item's announcement (ADR-0044, item 3)
+    // typography / controls / touch
+    fontKey: 'incl_font_k', padDesign: 'incl_paddesign', padDir: 'incl_paddir', touchmap: 'incl_touchmap',
+    padBtnMm: 'incl_padbtnmm', padGapMm: 'incl_padgapmm', padStickMm: 'incl_padstickmm',
+    padTravelMm: 'incl_padtravelmm', padDpadMm: 'incl_paddpadmm',
+    // reduced motion (the whole object in one JSON) + the old toggle-movement key, still read once to migrate whoever came
+    // from the previous version
+    reducedMotion: 'inclusionist.reducedmotion.v1', toggleMoveLegacy: 'inclusionist.togglemove',
+    // PER PLAYER — parameterised by the screen's index. As functions here, no call site can write a crooked name.
+    /**
+     * @deprecated ⚠️ THE LEGACY visual-mode KEY — ONE value, from when only one fitted (issue #104).
+     *
+     * It is still READ, which is what keeps the child from losing what they chose; it is still WRITTEN while the controls
+     * write one value at a time, because an old reader does `if (v && VIZ_BY_KEY[v])` and would reject a JSON — writing
+     * the new shape HERE would erase their setting in silence, exactly the defect the migration exists not to commit.
+     */
+    vizP: (i) => 'incl_viz_p' + i,
+    /**
+     * The two-axis VISUAL STATE, in JSON (ADR-0076, issue #104).
+     *
+     * ⚠️ A NEW KEY BESIDE THE OLD ONE, not the same key with new content. The same design as the `visual` field beside
+     * `viz`: both shapes coexist while both have readers, each reads the one it understands, and the old one dies only
+     * when nobody reads it. `migrateVisual` accepts both, so the fallback — new key absent, old key present — returns
+     * exactly what the child chose.
+     */
+    visualP: (i) => 'incl_visual_p' + i,
+    sinkP: (i) => 'incl_sink_p' + i,
+    easyP: (i) => 'incl_easy_p' + i,
+    /**
+     * ⚠️ THE TWO BELOW ARE LEGACY KEYS (ADR-0104 §C, issue #114). They are still READ — it is the child's setting, and
+     * inheriting it keeps them from losing it — and never written again. What is written is the key WITH A TRANSPORT,
+     * because the toggle belongs to the DEVICE and not the person: turning it on for the touch pad, where nobody holds a
+     * virtual button comfortably, turned it on for the keyboard too, where holding a key is exactly what the child can do.
+     *
+     * ⚠️ AND THE NEW KEY DOES NOT LIVE HERE, on purpose. It is `latchKey`, in `input/latch-scope` — `platform/` does not
+     * import `input/`, the layer above. Building it here would need either a backwards edge or a second copy of the name.
+     * Whoever owns the name is whoever knows the transport rule.
+     */
+    toggleMoveP: (i) => 'incl_togglemove_p' + i,
+    toggleRunP: (i) => 'incl_togglerun_p' + i, // the RUN-button toggle (the movement one's sibling)
+    rmWalkP: (i) => 'incl_rmWalk_p' + i,
+    rmBreathP: (i) => 'incl_rmBreath_p' + i,
+    rmFlavorP: (i) => 'incl_rmFlavor_p' + i,
+    // demo/attract: one recording per scenery (a function, not a string — a parameterised key). The GAME's SCOPE: the
+    // recording is of a level of THIS game and means nothing in another.
+    attract: (gameId, scenery) => gameKey(gameId, 'attract_' + scenery),
+    attractLegado: (scenery) => 'incl_attract_' + scenery,
+};