@the-inclusionist/engine 10.0.0 → 11.0.0

package/dist-pkg/ui/audio-choices.js

@@ -13,11 +13,14 @@
 // 📌 WHY IT IS `ui/` AND NOT `core/`: half of these resolve i18n KEYS (`t`) into the words a child reads, and a label is
 // interface. What is genuinely free of language — the category lists and the volume arithmetic — stays here beside the rest
 // rather than being split again for the sake of a layer.
-/** The SOUND-NAVIGATION categories (cane/sonar/guard/guide) — their master volume is separate from the game's sound. */
-export const NAV_CATS = ['sonar', 'guard', 'guide'];
+/**
+ * The SOUND-NAVIGATION categories — their master volume is separate from the game's sound. Only the sonar since `guard` and
+ * `guide` left (ADR-0258): the engine plays nothing in them since the guide moved to the platformer.
+ */
+export const NAV_CATS = ['sonar'];
 /** The game's GENERAL categories (TTS lives in the Voice section, outside this list). */
 // ⚠️ THEY BELONG TO THE «AUDIO» PANEL since ADR-0151, not to the hearing one: what is taste (music, ambience) does not live
-// beside what is accessibility (sonar, guard, guide). And `other` left — it controlled no sound at all.
+// beside what is accessibility (the sonar). And `other` left — it controlled no sound at all.
 export const GEN_CATS = ['music', 'ambient', 'interact', 'earcons'];
 /** 0..1 -> 0..100 rounded (slider display value). */
 export function volPercent(v) {
@@ -28,8 +31,8 @@ export function volPercent(v) {
  * `ui/settings-audio.buildCatRow`, where the row is also RECONCILED instead of reborn. A markup builder with no consumer is
  * published debt — it is deleted, not moved.
  *
- * 📌 And no alias is left: a re-export would keep alive a path nothing imports and make the surface snapshot lie, because
- * it does not see re-exports (issue #204).
+ * 📌 And no alias is left: a re-export would keep alive a published path nothing imports — surface with no consumer
+ * (issue #204).
  */
 /** #navsound-master's value: the loudest of the nav categories, as a 0..100 slider value. */
 export function navMasterVolume(state, navCats = NAV_CATS) {
@@ -61,19 +64,20 @@ export function voiceEngineOptions(neuralAvailable) {
     return neuralAvailable ? TTS_ENGINE_OPTIONS : TTS_ENGINE_OPTIONS.filter(([v]) => v !== 'kokoro');
 }
 /**
- * The system voices in the language asked for; with none of them, the whole list.
+ * The system voices in the language asked for, and ONLY those (ADR-0185): with none of them, none — the list then says there is
+ * no voice, and the speech rows lock.
  *
  * It was called `pickPtVoices` and filtered a hard-coded `/^pt/i`, so a game in English offered a child a list of PORTUGUESE
  * voices to read English text. The name told the truth about what it did and lied about what it should do.
  *
  * The comparison is by language PREFIX and not by the whole tag: a child playing in pt-BR should also be able to choose a
- * pt-PT voice if that is the only one installed, and a school's browser rarely has the exact variant. The fallback to the
- * whole list stays: an empty list would be worse than a list in the wrong language, which at least she can hear and reject.
+ * pt-PT voice if that is the only one installed, and a school's browser rarely has the exact variant. 🔴 There is no fallback
+ * to the whole list: a voice of another language reads the text with the wrong phonetics, and ADR-0243 §3 decided that a wrong
+ * voice is worse than none — silence is noticed, a wrong accent is learned.
  */
 export function pickVoicesFor(voices, lang) {
     const pref = lang.slice(0, 2).toLowerCase();
-    const sameTag = voices.filter((v) => v.lang.slice(0, 2).toLowerCase() === pref);
-    return sameTag.length ? sameTag : voices;
+    return voices.filter((v) => v.lang.slice(0, 2).toLowerCase() === pref);
 }
 /** "<name> (<lang>)" option label. */
 export function voiceLabel(v) {

package/dist-pkg/ui/camera-control.d.ts

@@ -4,3 +4,50 @@ import type { SwitchableControl } from './switchable-control.js';
 export declare function followCameraMode(mode: CameraControl, controls: {
     readonly [M in Exclude<CameraControl, 'off'>]: SwitchableControl;
 }): void;
+/** Why a camera mode did not start: its files are not on the device, its runtime did not load, or the camera did not open. */
+export type CameraStartFailure = 'files' | 'runtime' | 'camera';
+/** How one camera mode names itself when it cannot start. */
+export interface CameraWords {
+    /** Its name in `problems`: «gesture control». */
+    readonly subject: string;
+    /** What the child loses, after «the child cannot»: «play with gestures». */
+    readonly loses: string;
+    /**
+     * What the child hears for each failure, in the page's language at the moment it happens. Each is the mode's own `t('…')`
+     * with a literal key, so `tests/no-key-reaches-the-child-unresolved` still reads it — a key built here would not be checked.
+     */
+    readonly spoken: {
+        readonly [K in CameraStartFailure]: () => string;
+    };
+}
+export interface CameraStartDeps<T extends {
+    close(): void;
+}, F> {
+    /** The reader's loader (`platform/vision`), already given the page and the checked cache. */
+    readonly load: () => Promise<{
+        readonly ok: true;
+        readonly tracker: T;
+    } | {
+        readonly ok: false;
+        readonly missing: readonly string[];
+    }>;
+    readonly openFeed: () => Promise<F>;
+    /** Nothing started: the control says it, writes it once, and puts the 📷 back to off — if it is still wanted. */
+    readonly failed: (kind: CameraStartFailure, line: string, spoken: string) => void;
+}
+/**
+ * THE READER, THEN THE CAMERA — or the reason neither is running, said through `failed`; `null` when nothing started.
+ *
+ * 🔴 A LOADER THAT REJECTS IS A FAILURE LIKE ANY OTHER (ADR-0169). `platform/vision` answers the files it cannot find, but a
+ * runtime that cannot be IMPORTED (a server that sends `.mjs` as `text/plain`, an address that answers 404) or a vision task
+ * that cannot be built on the GPU nor on the CPU rejects instead, and the three controls awaited it with nothing around it: the
+ * rejection went up through `apply` into `followCameraMode`'s `void` and died unhandled, with the 📷 lit, nothing said and
+ * nothing in `problems` — measured in a real page on 2026-09-25. The 👄 had met the same defect on 2026-09-21
+ * (`ui/voice-control`); this is the one place the three camera modes now start through, so a fourth cannot miss it.
+ */
+export declare function startCameraReader<T extends {
+    close(): void;
+}, F>(words: CameraWords, d: CameraStartDeps<T, F>): Promise<{
+    tracker: T;
+    feed: F;
+} | null>;

package/dist-pkg/ui/camera-control.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/camera-control — THE 📷 POSITION TO THE THREE CAMERA CONTROLS (ADR-0215; issue #199).
+// ui/camera-control — THE 📷 POSITION TO THE THREE CAMERA CONTROLS (ADR-0215; issue #199), AND HOW EACH ONE STARTS.
 //
 // One stored position (`core/state.cameraControl`): off · hands · face · eyes. Each control starts only at its own position, so one camera
 // mode at a time holds by construction (ADR-0197). The ones turning off are told first, so a camera is let go before the next mode asks.
@@ -12,3 +12,37 @@ export function followCameraMode(mode, controls) {
         if (m === mode)
             void c.apply(true);
 }
+/**
+ * THE READER, THEN THE CAMERA — or the reason neither is running, said through `failed`; `null` when nothing started.
+ *
+ * 🔴 A LOADER THAT REJECTS IS A FAILURE LIKE ANY OTHER (ADR-0169). `platform/vision` answers the files it cannot find, but a
+ * runtime that cannot be IMPORTED (a server that sends `.mjs` as `text/plain`, an address that answers 404) or a vision task
+ * that cannot be built on the GPU nor on the CPU rejects instead, and the three controls awaited it with nothing around it: the
+ * rejection went up through `apply` into `followCameraMode`'s `void` and died unhandled, with the 📷 lit, nothing said and
+ * nothing in `problems` — measured in a real page on 2026-09-25. The 👄 had met the same defect on 2026-09-21
+ * (`ui/voice-control`); this is the one place the three camera modes now start through, so a fourth cannot miss it.
+ */
+export async function startCameraReader(words, d) {
+    const { subject, loses, spoken } = words;
+    let load;
+    try {
+        load = await d.load();
+    }
+    catch (e) {
+        const why = e instanceof Error ? e.message : String(e);
+        d.failed('runtime', `${subject}: the vision runtime did not load (${why}) — the child cannot ${loses}; check that the delivery carries the vision files and that the server serves .mjs files with the MIME type text/javascript`, spoken.runtime());
+        return null;
+    }
+    if (!load.ok) {
+        d.failed('files', `${subject}: ${load.missing.join(', ')} not on this device — the child cannot ${loses}; open the game once online so the install fetches them`, spoken.files());
+        return null;
+    }
+    try {
+        return { tracker: load.tracker, feed: await d.openFeed() };
+    }
+    catch {
+        load.tracker.close();
+        d.failed('camera', `${subject}: the camera did not open — the child cannot ${loses}; allow the camera for this page, or plug one in`, spoken.camera());
+        return null;
+    }
+}

package/dist-pkg/ui/declared-words.d.ts

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { ActionPreset } from '../core/actions.js';
+import type { AccommodationAnswers } from '../core/accommodations.js';
+import type { GameOption } from './game-options.js';
+import type { HowToPlaySlide } from './help-panel.js';
+import type { HudNumber } from './hud-bands.js';
+/** The game's fields that carry declared words — a `Pick` of `CreateGameOptions`, written here so `ui` does not import `boot`. */
+interface DeclaredWords {
+    readonly preset?: ActionPreset;
+    readonly accommodations?: AccommodationAnswers;
+    readonly gameOptions?: readonly GameOption[];
+    readonly howToPlay?: readonly HowToPlaySlide[];
+    readonly hud?: readonly HudNumber[];
+}
+/**
+ * THE DECLARED KEYS THIS GAME'S DICTIONARIES LACK, one line each for `problems` (ADR-0169). `declares` is the root's
+ * translator's (`Translator.declares`): a key in ANY language counts as present, because a key given in one language and not
+ * another is already a line of its own (`Translator.dictionaryGaps`).
+ */
+export declare function missingDeclaredKeys(declared: DeclaredWords, declares: (key: string) => boolean): string[];
+export {};

package/dist-pkg/ui/declared-words.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+const ACTION_NAME = 'the child sees this button unnamed: the help, the remap screen, the pad and the scan leave it out';
+const ACTION_SHORT = 'the pad shows the long name squeezed under the glyph';
+const ACTION_HINT = 'the help shows this button without its sentence';
+const ACCOMMODATION_NAME = 'this accommodation has its row left out, and the child who needs it cannot reach it';
+const ACCOMMODATION_SHORT = 'where only a short name fits, the long one is squeezed';
+const ACCOMMODATION_HINT = 'the row explains itself in the engine\'s general words, or not at all';
+const OPTION_NAME = 'this option has its row left out, and the child cannot change it';
+const OPTION_HINT = 'the row shows without its explanation';
+const SLIDE_TEXT = 'this slide is left out of the help';
+const HUD_NAME = 'this number is hidden from the child';
+function presetKeys(preset) {
+    if (!preset)
+        return [];
+    return Object.entries(preset).flatMap(([action, keys]) => (keys ? [
+        { subject: `preset.${action}.labelKey`, key: keys.labelKey, cost: ACTION_NAME, optional: false },
+        { subject: `preset.${action}.shortKey`, key: keys.shortKey, cost: ACTION_SHORT, optional: true },
+        { subject: `preset.${action}.hintKey`, key: keys.hintKey, cost: ACTION_HINT, optional: true },
+    ] : []));
+}
+function accommodationKeys(answers) {
+    if (!answers)
+        return [];
+    return Object.entries(answers).flatMap(([accommodation, keys]) => (keys ? [
+        { subject: `accommodations.${accommodation}.labelKey`, key: keys.labelKey, cost: ACCOMMODATION_NAME, optional: false },
+        { subject: `accommodations.${accommodation}.shortKey`, key: keys.shortKey, cost: ACCOMMODATION_SHORT, optional: true },
+        { subject: `accommodations.${accommodation}.hintKey`, key: keys.hintKey, cost: ACCOMMODATION_HINT, optional: true },
+    ] : []));
+}
+function optionKeys(options) {
+    return (options ?? []).flatMap((o) => [
+        { subject: `gameOptions «${o.id}».labelKey`, key: o.labelKey, cost: OPTION_NAME, optional: false },
+        { subject: `gameOptions «${o.id}».hintKey`, key: o.hintKey, cost: OPTION_HINT, optional: true },
+        ...(o.kind === 'switch' ? [] : o.values.map((v) => ({ subject: `gameOptions «${o.id}».values «${v.value}».labelKey`, key: v.labelKey, cost: OPTION_NAME, optional: false }))),
+    ]);
+}
+function slideKeys(slides) {
+    return (slides ?? []).map((s, i) => ({ subject: `howToPlay[${i}].textKey`, key: s.textKey, cost: SLIDE_TEXT, optional: false }));
+}
+function hudKeys(numbers) {
+    return (numbers ?? []).map((n, i) => ({ subject: `hud[${i}].nameKey`, key: n.nameKey, cost: HUD_NAME, optional: false }));
+}
+/** What is wrong with ONE declared key, or `null`: it must be text, and it must be in the game's dictionaries. */
+function keyProblem(k, declares) {
+    if (k.optional && k.key === undefined)
+        return null;
+    const fix = 'add it to CreateGameOptions.dictionaries, in pt, en and es';
+    if (typeof k.key !== 'string' || !k.key.trim()) {
+        return `${k.subject} is not a key (since ADR-0232 D3 a game declares the KEY of each word, never the word): ${k.cost} — name a key, and ${fix}`;
+    }
+    return declares(k.key) ? null : `${k.subject} «${k.key}» is in none of this game's dictionaries: ${k.cost} — ${fix}`;
+}
+/**
+ * THE DECLARED KEYS THIS GAME'S DICTIONARIES LACK, one line each for `problems` (ADR-0169). `declares` is the root's
+ * translator's (`Translator.declares`): a key in ANY language counts as present, because a key given in one language and not
+ * another is already a line of its own (`Translator.dictionaryGaps`).
+ */
+export function missingDeclaredKeys(declared, declares) {
+    return [
+        ...presetKeys(declared.preset),
+        ...accommodationKeys(declared.accommodations),
+        ...optionKeys(declared.gameOptions),
+        ...slideKeys(declared.howToPlay),
+        ...hudKeys(declared.hud),
+    ].map((k) => keyProblem(k, declares)).filter((line) => line !== null);
+}

package/dist-pkg/ui/drawing-problems.js

@@ -12,7 +12,7 @@
 // because a stale element still answers `getBoundingClientRect()`.
 import { barIntruders, belowFloor, minimumTarget } from './layout.js';
 /** The engine's OWN nodes inside the region — their sizes are held by their own gates — and what is not drawn for the eye. */
-const ENGINE_NODES = '#title-icons, .screen-pause, .overlay, #touch-controls, .rodape-da-tela, .pausa-rapida, #incl-parou, .sr-only, .hud-faixa';
+const ENGINE_NODES = '#title-icons, .screen-pause, .overlay, #touch-controls, .rodape-da-tela, .pausa-rapida, #incl-parou, .sr-only, .hud-faixa, .hud-row';
 /** What a finger is meant to hit; anything else has no target floor to fail. */
 const TOUCH_TARGET = 'button, a[href], input:not([type="hidden"]), select, textarea, [role="button"], [tabindex]:not([tabindex="-1"])';
 /**
@@ -86,8 +86,9 @@ export function barIntruderProblems(ctx) {
     const nodes = [...region.querySelectorAll('*')].filter((el) => paints(el)).map((el) => ({
         name: nodeName(el),
         box: boxOf(el),
-        // the engine's HUD bands are placed by the ENGINE: if one reaches the bar, that is the engine's defect and not the game's
-        isBar: el === bar || bar.contains(el) || el.closest('.hud-faixa') !== null,
+        // the engine's HUD bands and HUD row are placed by the ENGINE: if one reaches the bar, that is the engine's defect and
+        // not the game's
+        isBar: el === bar || bar.contains(el) || el.closest('.hud-faixa, .hud-row') !== null,
     }));
     return barIntruders(boxOf(bar), nodes);
 }

package/dist-pkg/ui/eye-control.js

@@ -9,14 +9,15 @@
 // · Nothing commands before the rest is measured: until then, and on a frame with no face or a head turning fast, the cycle is frozen.
 // · A reading that re-centres itself cancels the gesture in hand.
 // · Only the RIGHT eye is read (ADR-0213): the Dev's brain suppresses the left one, and a child's may too.
-// · What cannot work is said to the child and written in `problems`, once: the files not on the device, the camera refused, frames that
-//   stop or crawl. A 📷 that is on and does nothing is the defect this module exists not to ship.
+// · What cannot work is said to the child and written in `problems`, once: the files not on the device, a runtime that does not load,
+//   the camera refused, frames that stop or crawl (`ui/camera-control.startCameraReader` for the first three). A 📷 that is on and does nothing is the defect this module exists not to ship.
 import { headPoseFromMatrix, scoresFromCategories, eyeGazeFromScores, bothEyesClosed } from '../input/face-signals.js';
 import { createGazeReader, GAZE_DEFAULTS } from '../input/gaze-relative.js';
 import { createGazeCycle } from '../input/gaze-cycle.js';
 import { loadFaceTracker, openCamera, closeCamera } from '../platform/vision.js';
 import { createVisionLoop } from '../platform/vision-loop.js';
 import { drawGazeOverlay } from './gaze-overlay.js';
+import { startCameraReader } from './camera-control.js';
 // 📌 THE SHAPE IS THE FAMILY'S (ADR-0221 step 7f): what this module returns IS a SwitchableControl — following the 📷: on in
 // the eyes position it opens the camera and the drawing, off it lets go of everything.
 export function videoFeed(doc, media) {
@@ -127,23 +128,22 @@ export function createEyeControl(d) {
         running = false;
         wasReady = false;
     };
-    const start = async () => {
-        const load = await loadTracker({ base: d.base, hasFile: d.hasFile });
-        if (!load.ok) {
-            once('files', `eye control: ${load.missing.join(', ')} not on this device — the child cannot play with the eyes; open the game once online so the install fetches them`, t('sr.eyes.needsInternet'));
-            d.turnOff();
+    /** Nothing started: said, written once, and the 📷 back to off — unless it already moved on, and then nobody is waiting (as the 👄). */
+    const failed = (kind, line, spoken) => {
+        if (!current())
             return;
-        }
-        try {
-            feed = await openFeed();
-        }
-        catch {
-            load.tracker.close();
-            once('camera', 'eye control: the camera did not open — the child cannot play with the eyes; allow the camera for this page, or plug one in', t('sr.eyes.noCamera'));
-            d.turnOff();
+        once(kind, line, spoken);
+        d.turnOff();
+    };
+    const start = async () => {
+        const opened = await startCameraReader({
+            subject: 'eye control', loses: 'play with the eyes',
+            spoken: { files: () => t('sr.eyes.needsInternet'), runtime: () => t('sr.eyes.failed'), camera: () => t('sr.eyes.noCamera') },
+        }, { load: () => loadTracker({ base: d.base, hasFile: d.hasFile }), openFeed, failed });
+        if (!opened)
             return;
-        }
-        tracker = load.tracker;
+        tracker = opened.tracker;
+        feed = opened.feed;
         canvas = d.doc.createElement('canvas');
         canvas.className = 'gaze-overlay';
         canvas.setAttribute('aria-hidden', 'true');

package/dist-pkg/ui/face-control.js

@@ -13,6 +13,7 @@ import { faceScoresFromCategories, headTurn, createFaceMapReader, createFaceRest
 import { loadFaceTracker } from '../platform/vision.js';
 import { createVisionLoop } from '../platform/vision-loop.js';
 import { gazeFontPx } from './gaze-overlay.js';
+import { startCameraReader } from './camera-control.js';
 // 📌 THE SHAPE IS THE FAMILY'S (ADR-0221 step 7f): this module declares no `FaceControl` of its own — what it returns IS a
 // `SwitchableControl`, and the compiler sees it.
 const REST_MS = 3000;
@@ -132,23 +133,22 @@ export function createFaceControl(d) {
         rest = null;
         read = null;
     };
-    const start = async () => {
-        const load = await loadTracker({ base: d.base, hasFile: d.hasFile });
-        if (!load.ok) {
-            once('files', `face control: ${load.missing.join(', ')} not on this device — the child cannot play with the face; open the game once online so the install fetches them`, t('sr.face.needsInternet'));
-            d.turnOff();
+    /** Nothing started: said, written once, and the 📷 back to off — unless it already moved on, and then nobody is waiting (as the 👄). */
+    const failed = (kind, line, spoken) => {
+        if (!current())
             return;
-        }
-        try {
-            feed = await d.openFeed();
-        }
-        catch {
-            load.tracker.close();
-            once('camera', 'face control: the camera did not open — the child cannot play with the face; allow the camera for this page, or plug one in', t('sr.face.noCamera'));
-            d.turnOff();
+        once(kind, line, spoken);
+        d.turnOff();
+    };
+    const start = async () => {
+        const opened = await startCameraReader({
+            subject: 'face control', loses: 'play with the face',
+            spoken: { files: () => t('sr.face.needsInternet'), runtime: () => t('sr.face.failed'), camera: () => t('sr.face.noCamera') },
+        }, { load: () => loadTracker({ base: d.base, hasFile: d.hasFile }), openFeed: d.openFeed, failed });
+        if (!opened)
             return;
-        }
-        tracker = load.tracker;
+        tracker = opened.tracker;
+        feed = opened.feed;
         canvas = d.doc.createElement('canvas');
         canvas.className = 'face-overlay';
         canvas.setAttribute('aria-hidden', 'true');

package/dist-pkg/ui/fonts.d.ts

@@ -85,6 +85,12 @@ export type FontItem = {
     fb: string;
     d?: string;
     off?: string;
+    /**
+     * The i18n KEY of a sentence ALWAYS shown after the description — unlike `off`, which only speaks while the face is
+     * disabled. It is for a stack whose preferred faces the device may lack: the ronde's names the three to install, because
+     * without them the child sees Cookie, a related hand that is not the one taught at school (ADR-0154).
+     */
+    notice?: string;
     /** Absent = `geral`. Only the handwriting faces declare it, because they are the exception. */
     role?: FontRole;
     /**
@@ -100,6 +106,16 @@ export type FontGroup = {
     g: string;
     items: FontItem[];
 };
+/**
+ * THE TYPOGRAPHY PANEL'S KIT — every face a panel may list, grouped. The engine mounts no panel since ADR-0151 («quem escolhe a
+ * tipografia é o jogo»), and the kit stays for whoever mounts one (`ui/settings-typo`), because the eleventh button's cycle and
+ * the boot's stored choice go through its writer.
+ *
+ * 📌 MOST OF THESE FACES ARE THE FONT LIBRARY'S, not the engine's (ADR-0255): only the cycle's faces are packaged. A library face
+ * reaches a page when its cartridge declares the family in `uses.fonts` and the delivery carries it, so `faceAvailable` answers
+ * for it through the host's detector — a row whose family nobody declared is shown disabled, never offered and then drawn in the
+ * system font. Keeping the rows is what lets a game that declares its families offer them with no list of its own.
+ */
 export declare const FONT_GROUPS: FontGroup[];
 /**
  * How much larger the text is drawn with this face: enough to reach its `minPx` from the document's base, never smaller.
@@ -112,23 +128,39 @@ export declare function fontRole(it: FontItem): FontRole;
 /**
  * THE FAMILIES A FACE ACCEPTS, from a `fam` that may be a STACK.
  *
- * 📌 The Ronde declares three (`'Ronde Script, OPTIFrench-Script, Merveille'`) because any of them will do — three
- * drawings of the same hand, and an adult installs whichever they find. The other faces declare one, and for them this
+ * 📌 The ronde declares four (`'Ronde Script, OPTIFrench-Script, Merveille, Cookie'`): the three drawings of the same
+ * hand an adult may install, then the packaged fallback (ADR-0154). The other faces declare one, and for them this
  * returns a list of one.
  */
 export declare function faceFamilies(it: FontItem): string[];
+/**
+ * A `fam` as a CSS `font-family` value — each family quoted on its own: `'Ronde Script','OPTIFrench-Script',…,'Cookie'`.
+ *
+ * 🔴 QUOTING THE WHOLE STRING ONCE NAMES ONE FAMILY THAT DOES NOT EXIST. `'Ronde Script, …, Cookie'` is a single name with
+ * commas in it, so the browser skips it and draws the generic fallback — the stack would never reach Cookie, and the
+ * fallback ADR-0154 decided would exist only in the catalogue. For a one-family `fam` the result is the same `'Inter'`.
+ */
+export declare function familyStack(fam: string): string;
+/**
+ * THE FACES THE ENGINE DRAWS WITH ITSELF, by key — the eleventh button's cycle over EVERY hand a tag can pick (ADR-0149,
+ * ADR-0150). With the mathematics face (`MATHEMATICS_FAMILY`) they are the only faces packaged and precached (ADR-0255 §1); every
+ * other face of the kit is the font library's. `tests/what-fonts-the-package-carries.node.test.js` holds `fonts.css` to this list.
+ */
+export declare const ENGINE_FACE_KEYS: readonly string[];
+/** The face the engine draws mathematics in (`--font-math` in `style.css`): packaged, never a typography choice (ADR-0012). */
+export declare const MATHEMATICS_FAMILY = "Atkinson Hyperlegible Mono";
 /**
  * CAN THIS FACE BE USED NOW? — `off` stops being a sentence and becomes a CONDITION.
  *
- * ADR-0012 decided the ronde option stays DISABLED WHILE no font is present, and ADR-0108 §4 added what it says. The word
- * "while" is what this function builds: an `off` face becomes available again the instant the adult installs one of the
- * ones the message names.
+ * An engine face is always there: it is packaged and precached (ADR-0255 §1). Any other face is used WHILE one of its families
+ * is present — a library family its cartridge declared in `uses.fonts` (the root's detector answers for those), or, for an `off`
+ * face, one the adult installed from the ones its message names (ADR-0012's «enquanto»). The ronde's stack ends in Cookie, a
+ * library family, so it is available where the game declares Cookie (ADR-0154, ADR-0255).
  *
  * ⚠️ THE DETECTOR IS INJECTED, and `document.fonts` is never read here: this module is the catalogue, it runs in node in
  * the gates, and reading a browser global here would be a boot waiting to crash against an injected document.
- * 📌 And the DEFAULT is not installed, which is safe for a reason that does not hold for every default in this repository:
- * with no detector the option stays disabled WITH the message, and the message tells the adult exactly what to do. The
- * silence decides nothing against the child — it keeps a state that already existed and is actionable.
+ * 📌 And the DEFAULT is not present, which is safe: with no detector a library row stays disabled, never offered and then drawn
+ * in the system font, and an `off` row keeps the message that tells the adult exactly what to do.
  */
 export declare function faceAvailable(it: FontItem, installed?: (family: string) => boolean): boolean;
 /** The faces the MENU may offer: only the general ones (ADR-0012 amendment). */
@@ -138,6 +170,8 @@ export declare const OFERECIVEIS: FontItem[];
  * module wrote into at import, which the code-health measure reads as module state. The last item with a key wins, as it did.
  */
 export declare const FONT_BY_KEY: Record<string, FontItem>;
+/** The families `vendor/fonts.css` declares — the engine's faces and the mathematics face. A cartridge never declares these. */
+export declare const ENGINE_FAMILIES: ReadonlySet<string>;
 /** Narrow store shape these need — lets a caller inject a fake without touching real storage. */
 export interface FontStore {
     get(key: string, fallback: string | null): string | null;

package/dist-pkg/ui/fonts.js

@@ -87,11 +87,20 @@ export function handsForTag(tag) {
         return HAND_BY_COUNTRY[region];
     return HAND_BY_LANGUAGE[language] ?? [];
 }
+/**
+ * THE TYPOGRAPHY PANEL'S KIT — every face a panel may list, grouped. The engine mounts no panel since ADR-0151 («quem escolhe a
+ * tipografia é o jogo»), and the kit stays for whoever mounts one (`ui/settings-typo`), because the eleventh button's cycle and
+ * the boot's stored choice go through its writer.
+ *
+ * 📌 MOST OF THESE FACES ARE THE FONT LIBRARY'S, not the engine's (ADR-0255): only the cycle's faces are packaged. A library face
+ * reaches a page when its cartridge declares the family in `uses.fonts` and the delivery carries it, so `faceAvailable` answers
+ * for it through the host's detector — a row whose family nobody declared is shown disabled, never offered and then drawn in the
+ * system font. Keeping the rows is what lets a game that declares its families offer them with no list of its own.
+ */
 export const FONT_GROUPS = [
     { g: 'font.group.sans', items: [
             { k: 'atkinson', id: 'atkinson_hyperlegible', fam: 'Atkinson Hyperlegible', fb: 'sans', d: 'font.desc.atkinson' },
             { k: 'lexend', id: 'lexend', fam: 'Lexend', fb: 'sans', d: 'font.desc.lexend' },
-            { k: 'quattro', id: 'ia_writer_quattro', fam: 'iA Writer Quattro', fb: 'sans', d: 'font.desc.quattro' },
             { k: 'andika', id: 'andika', fam: 'Andika', fb: 'sans', d: 'font.desc.andika' },
             // ⚠️ OPENDYSLEXIC IS OFFERED WITH NO CLAIM OF EFFICACY — issue #87 item 3 and `docs/game-design/typography.md`: offer
             // Dyslexie and OpenDyslexic only as a user's choice, because research shows no reading gain from them. Its description
@@ -140,8 +149,8 @@ export const FONT_GROUPS = [
             { k: 'literata', id: 'literata', fam: 'Literata', fb: 'serif' },
             { k: 'sourceserif', id: 'source_serif_4', fam: 'Source Serif 4', fb: 'serif' },
             { k: 'newsreader', id: 'newsreader', fam: 'Newsreader', fb: 'serif' },
-            // Five READING faces: serifs for running text, like the three above.
-            { k: 'merriweather', id: 'merriweather', fam: 'Merriweather', fb: 'serif' },
+            // Four READING faces: serifs for running text, like the three above. (Merriweather left: its author's original is a 4.5 MB
+            // variable font, and the library carries only originals of a reserved name — ADR-0254.)
             { k: 'lora', id: 'lora', fam: 'Lora', fb: 'serif' },
             { k: 'spectral', id: 'spectral', fam: 'Spectral', fb: 'serif' },
             { k: 'domine', id: 'domine', fam: 'Domine', fb: 'serif' },
@@ -171,18 +180,17 @@ export const FONT_GROUPS = [
             // the menu — it is for the buttons INSIDE school activities, not for the interface.
             { k: 'fondamento', id: 'fondamento', fam: 'Fondamento', fb: 'cursive', d: 'font.desc.fondamento', role: 'caligrafica', minPx: 20 },
             /*
-             * THE FRENCH RONDE — #87 item 4, decided in ADR-0108 §4. It is NEVER bundled: the three faces are free for PERSONAL
-             * use only (ADR-0012), and distributing them would distribute what was not licensed for distribution. What the entry
-             * does is SPEAK.
+             * THE FRENCH RONDE, AND ITS FALLBACK (ADR-0154). The three ronde faces are NEVER bundled: they are free for PERSONAL
+             * use only (ADR-0012), and distributing them would distribute what was not licensed for distribution. So the stack is
+             * the three the device may have, in the Dev's order, and then COOKIE, which the engine packages (OFL): the first one
+             * the device has wins, and Cookie answers when it has none. The option is therefore never disabled.
              *
-             * ⚠️ AND IT IS NOT A "NOT YET" ROW. The difference is ACTIONABILITY, the reason ADR-0108 gives in full: a "not yet"
-             * nobody can resolve; this names WHICH THREE FONTS TO INSTALL, which an adult resolves in an afternoon. 📌 "Install a
-             * ronde font" would be the defect back — an adult does not act on a category —, which is why the message names all
-             * three.
+             * 🔴 COOKIE IS NOT THE RONDE — a joined brush script, not the hand a French classroom teaches. That is why the entry
+             * keeps a `notice` naming the three: it is the remedy for a hand that is close but not hers. 📌 "Install a ronde font"
+             * would not do — an adult does not act on a category —, so the sentence names all three (ADR-0108 §4).
              *
              * ⚠️ `role` ABSENT, so `geral`, deliberately, although the ronde is handwriting by nature: handwriting faces are
-             * filtered out of the menu (`fontRole === 'geral'`), and a filtered row can say nothing to anyone. Marking the
-             * "right" role here would erase the one thing this entry exists to do.
+             * filtered out of the menu (`fontRole === 'geral'`), and a filtered row can say nothing to anyone.
              */
             /*
              * THE PLAYWRITE FACES — #87 item 3, decided in ADR-0108 §2.
@@ -224,8 +232,8 @@ export const FONT_GROUPS = [
             { k: 'pwgbs', id: 'playwrite_gb_s', fam: 'Playwrite GB S', fb: 'cursive', role: 'caligrafica', minPx: 20 },
             { k: 'pwcu', id: 'playwrite_cu', fam: 'Playwrite CU', fb: 'cursive', role: 'caligrafica', minPx: 20 },
             { k: 'pwpe', id: 'playwrite_pe', fam: 'Playwrite PE', fb: 'cursive', role: 'caligrafica', minPx: 20 },
-            { k: 'ronde', id: 'ronde_script', fam: 'Ronde Script, OPTIFrench-Script, Merveille', fb: 'cursive',
-                d: 'font.desc.ronde', off: 'font.off.ronde', minPx: 18 }
+            { k: 'ronde', id: 'ronde_script', fam: 'Ronde Script, OPTIFrench-Script, Merveille, Cookie', fb: 'cursive',
+                d: 'font.desc.ronde', notice: 'font.notice.ronde', minPx: 18 }
         ] },
     // ⚠️ THE GAME'S FACE has its own group because it is neither sans, nor serif, nor handwriting — it is a PIXEL face,
     // and putting it in any of the three would say the wrong thing about it in the list.
@@ -244,31 +252,55 @@ export const FONT_GROUPS = [
 export function faceScale(it) { return Math.max(1, (it.minPx ?? BASE_EM_PX) / BASE_EM_PX); }
 /** A face's role; absent in the catalogue means `geral`. */
 export function fontRole(it) { return it.role ?? 'geral'; }
+/** The family names in a `fam` string, unquoted, in stack order. */
+function familiesIn(fam) {
+    return fam.split(',').map((f) => f.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
+}
 /**
  * THE FAMILIES A FACE ACCEPTS, from a `fam` that may be a STACK.
  *
- * 📌 The Ronde declares three (`'Ronde Script, OPTIFrench-Script, Merveille'`) because any of them will do — three
- * drawings of the same hand, and an adult installs whichever they find. The other faces declare one, and for them this
+ * 📌 The ronde declares four (`'Ronde Script, OPTIFrench-Script, Merveille, Cookie'`): the three drawings of the same
+ * hand an adult may install, then the packaged fallback (ADR-0154). The other faces declare one, and for them this
  * returns a list of one.
  */
 export function faceFamilies(it) {
-    return it.fam.split(',').map((f) => f.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
+    return familiesIn(it.fam);
+}
+/**
+ * A `fam` as a CSS `font-family` value — each family quoted on its own: `'Ronde Script','OPTIFrench-Script',…,'Cookie'`.
+ *
+ * 🔴 QUOTING THE WHOLE STRING ONCE NAMES ONE FAMILY THAT DOES NOT EXIST. `'Ronde Script, …, Cookie'` is a single name with
+ * commas in it, so the browser skips it and draws the generic fallback — the stack would never reach Cookie, and the
+ * fallback ADR-0154 decided would exist only in the catalogue. For a one-family `fam` the result is the same `'Inter'`.
+ */
+export function familyStack(fam) {
+    return familiesIn(fam).map((f) => `'${f}'`).join(',');
 }
+/**
+ * THE FACES THE ENGINE DRAWS WITH ITSELF, by key — the eleventh button's cycle over EVERY hand a tag can pick (ADR-0149,
+ * ADR-0150). With the mathematics face (`MATHEMATICS_FAMILY`) they are the only faces packaged and precached (ADR-0255 §1); every
+ * other face of the kit is the font library's. `tests/what-fonts-the-package-carries.node.test.js` holds `fonts.css` to this list.
+ */
+export const ENGINE_FACE_KEYS = Object.freeze([...new Set([
+        'andika', 'atkinson', 'lexend', ...Object.values(HAND_BY_COUNTRY).flat(), ...Object.values(HAND_BY_LANGUAGE).flat(),
+    ])]);
+/** The face the engine draws mathematics in (`--font-math` in `style.css`): packaged, never a typography choice (ADR-0012). */
+export const MATHEMATICS_FAMILY = 'Atkinson Hyperlegible Mono';
 /**
  * CAN THIS FACE BE USED NOW? — `off` stops being a sentence and becomes a CONDITION.
  *
- * ADR-0012 decided the ronde option stays DISABLED WHILE no font is present, and ADR-0108 §4 added what it says. The word
- * "while" is what this function builds: an `off` face becomes available again the instant the adult installs one of the
- * ones the message names.
+ * An engine face is always there: it is packaged and precached (ADR-0255 §1). Any other face is used WHILE one of its families
+ * is present — a library family its cartridge declared in `uses.fonts` (the root's detector answers for those), or, for an `off`
+ * face, one the adult installed from the ones its message names (ADR-0012's «enquanto»). The ronde's stack ends in Cookie, a
+ * library family, so it is available where the game declares Cookie (ADR-0154, ADR-0255).
  *
  * ⚠️ THE DETECTOR IS INJECTED, and `document.fonts` is never read here: this module is the catalogue, it runs in node in
  * the gates, and reading a browser global here would be a boot waiting to crash against an injected document.
- * 📌 And the DEFAULT is not installed, which is safe for a reason that does not hold for every default in this repository:
- * with no detector the option stays disabled WITH the message, and the message tells the adult exactly what to do. The
- * silence decides nothing against the child — it keeps a state that already existed and is actionable.
+ * 📌 And the DEFAULT is not present, which is safe: with no detector a library row stays disabled, never offered and then drawn
+ * in the system font, and an `off` row keeps the message that tells the adult exactly what to do.
  */
 export function faceAvailable(it, installed) {
-    if (!it.off)
+    if (!it.off && ENGINE_FACE_KEYS.includes(it.k))
         return true;
     return !!installed && faceFamilies(it).some((f) => installed(f));
 }
@@ -279,6 +311,8 @@ export const OFERECIVEIS = FONT_GROUPS.flatMap((g) => g.items).filter((it) => fo
  * module wrote into at import, which the code-health measure reads as module state. The last item with a key wins, as it did.
  */
 export const FONT_BY_KEY = Object.fromEntries(FONT_GROUPS.flatMap((g) => g.items.map((it) => [it.k, it])));
+/** The families `vendor/fonts.css` declares — the engine's faces and the mathematics face. A cartridge never declares these. */
+export const ENGINE_FAMILIES = new Set([...ENGINE_FACE_KEYS.map((k) => FONT_BY_KEY[k].fam), MATHEMATICS_FAMILY]);
 const FONT_KEY = 'incl_font_k';
 const FONT_KEY_LEGACY = 'incl_fonte'; // pre-Fase-2: 'alfabetizacao' | 'dislexia'
 /**