@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/platform/choose-by-voice.js

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/choose-by-voice — A CHILD ANSWERS BY SAYING ONE OF THE OPTIONS THE GAME SHOWS (ADR-0256).
+//
+// The game passes the options it is showing and gets back which one was said. The recogniser hears a grammar of exactly those
+// options plus `[unk]`, so it can only answer with one of them or with «none of these» — never with the nearest option to a word
+// that was not one. 📏 Why not the reading (Whisper): the lab measured it at 1 of 7 on words said alone, and an option is one or
+// two words; the command recogniser, closed, heard 7 of 7.
+//
+// 🔴 TWO OPTIONS IN ONE SENTENCE ARE NOT AN ANSWER (the quiz's own rule, which moved here with the matching): a child who says
+// «gato ou galinha» is thinking out loud, and picking one of them would answer FOR her — and mark it wrong. So the choice is
+// decided at the END of a sentence, never on its first word: one option chooses, two or more end the choice unanswered, none
+// goes on listening. 📏 It costs the end of the sentence — the lab measured 1.3 s after the word against 0.4 s on the partial.
+//
+// What this module decides, and nothing else: the grammar an option set becomes, which options a sentence names, when the
+// listening ends, and that one choice at a time holds the microphone. Opening the recogniser and the microphone is the root's
+// (`open`), which lends the delivery, the cache and the browser (ADR-0232 D4).
+import { spokenText, compareKey } from './speech-recognition.js';
+import { loadVoskRuntime } from './vosk-runtime.js';
+import { startVoiceListening } from './voice-listener.js';
+const MAX_MS = 10_000;
+/**
+ * THE `open` A CHOOSER IS GIVEN WHERE THE COMMAND RECOGNISER IS THE EAR: the language's model from the delivery, then the
+ * microphone with the grammar. A model that opened for a microphone that did not is let go before the refusal travels.
+ */
+export function openWithCommandRecogniser(d) {
+    return async (language, grammar, onHeard) => {
+        // a device with no microphone is refused before 31 MiB of model are opened for nothing
+        if (!d.getUserMedia)
+            throw new Error('this device cannot open a microphone');
+        const load = await (d.load ?? loadVoskRuntime)({ ...d, language });
+        if (!load.ok)
+            throw new Error(`${load.missing.join(', ')} not on this device`);
+        try {
+            const listening = await startVoiceListening({
+                model: load.model, grammar, getUserMedia: d.getUserMedia, createContext: d.createContext,
+                onPartial: (text) => onHeard(text, false), onFinal: (text) => onHeard(text, true),
+            });
+            return { stop: () => listening.stop(), ...(load.vocabulary ? { vocabulary: load.vocabulary } : {}) };
+        }
+        catch (e) {
+            load.model.terminate?.();
+            throw e;
+        }
+    };
+}
+/**
+ * The options a sentence names, in the order said, each once: read word by word, the LONGEST option that starts at each word —
+ * so «cavalo marinho» is one option and not also «cavalo» — accents and case aside, whole words only.
+ */
+export function optionsNamed(options, sentence) {
+    const keys = options.map((o) => compareKey(o).split(' ').filter(Boolean));
+    const said = compareKey(sentence).split(' ').filter(Boolean);
+    const named = [];
+    for (let i = 0; i < said.length;) {
+        let best = -1;
+        keys.forEach((k, o) => {
+            if (k.length && k.every((w, j) => said[i + j] === w) && (best < 0 || k.length > keys[best].length))
+                best = o;
+        });
+        if (best < 0) {
+            i += 1;
+            continue;
+        }
+        if (!named.includes(best))
+            named.push(best);
+        i += keys[best].length;
+    }
+    return named;
+}
+export function createVoiceChooser(d) {
+    const said = new Set();
+    const once = (kind, line) => { if (!said.has(kind)) {
+        said.add(kind);
+        d.report(line);
+    } };
+    let inFlight = null;
+    let askToStop = null;
+    /** An option with a word the model does not know can never be heard: said to the adult, once per option and language. */
+    const reportUnsayable = async (opened, options, language) => {
+        const known = await opened.vocabulary?.().catch(() => null);
+        if (!known)
+            return;
+        for (const option of options) {
+            const lacking = spokenText(option).split(' ').filter((w) => w && !known.has(w));
+            if (lacking.length) {
+                once(`unsayable:${language}:${option}`, `choosing by voice: the option "${option}" has ${lacking.length === 1 ? 'a word' : 'words'} `
+                    + `the ${language} speech model does not know (${lacking.map((w) => `"${w}"`).join(', ')}) — the child cannot choose it by saying `
+                    + 'it, only with the arrows; reword it with words the model knows (ADR-0256)');
+            }
+        }
+    };
+    const run = async (options, settings) => {
+        const language = settings.language ?? d.language();
+        const grammar = [...new Set(options.map((o) => spokenText(o)).filter(Boolean))];
+        let heard = '';
+        let settle = () => { };
+        const answer = new Promise((resolve) => { settle = resolve; });
+        const end = (chosen, ended) => settle({ chosen, heard, ended });
+        // asked to stop while the microphone is still opening counts too: it is let go as soon as it opens
+        askToStop = () => end(null, 'asked');
+        const onHeard = (text, final) => {
+            const clean = text.replace(/\[unk\]/g, ' ').replace(/\s+/g, ' ').trim();
+            // 🔴 THE END OF A SENTENCE IS WHAT WAS HEARD, even empty: a partial the recogniser took back («happy», then nothing) is not
+            // an answer to show the child — measured on 2026-09-27, the quiz said «I heard happy» for a word the model had withdrawn
+            if (final || clean)
+                heard = clean;
+            if (!final || !clean)
+                return;
+            const named = optionsNamed(options, clean);
+            if (named.length === 1)
+                end(named[0], 'chosen');
+            else if (named.length > 1)
+                end(null, 'unclear');
+        };
+        const borrowed = d.borrow?.(language, grammar, onHeard) ?? null;
+        if (!borrowed)
+            d.pause?.();
+        try {
+            let opened;
+            try {
+                opened = borrowed ?? await d.open(language, grammar, onHeard);
+            }
+            catch (e) {
+                const why = e instanceof Error ? e.message : String(e);
+                once(`open:${language}`, `choosing by voice: the recogniser did not open for ${language} (${why}) — the child cannot answer an `
+                    + `option by saying it; build the delivery with \`--commands ${language.split('-')[0]}\` and allow the microphone (ADR-0256)`);
+                throw e;
+            }
+            void reportUnsayable(opened, options, language);
+            // a game's listener that throws must not take the child's answer with it
+            try {
+                settings.onListening?.();
+            }
+            catch { /* the game's own line, not the choice */ }
+            const timer = d.after(() => end(null, 'timeout'), settings.maxMs ?? MAX_MS);
+            const result = await answer;
+            d.cancel(timer);
+            await opened.stop().catch(() => { });
+            return result;
+        }
+        finally {
+            askToStop = null;
+            if (!borrowed)
+                d.resume?.();
+        }
+    };
+    return {
+        choose(options, settings = {}) {
+            // one microphone, one choice: a second caller waits on the first
+            if (inFlight)
+                return inFlight;
+            inFlight = run(options, settings).finally(() => { inFlight = null; });
+            return inFlight;
+        },
+        stop() { askToStop?.(); },
+    };
+}

package/dist-pkg/platform/flash-sampler.d.ts

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** What a measurement found. `passes` and `worstSecond` exist only when the canvas was actually read. */
+export interface FlashMeasurement {
+    readonly measured: boolean;
+    readonly reason?: string;
+    readonly passes?: boolean;
+    readonly worstSecond?: number;
+}
+export interface FlashSamplerCtx {
+    /** The world's canvas, read at the moment of the call — a `mount()` may have replaced the world. */
+    readonly canvas: () => HTMLCanvasElement | null;
+    /** A scratch canvas of our own: the world's is never resized, only copied from. */
+    readonly scratch: () => HTMLCanvasElement;
+    /** `requestAnimationFrame`, absent in a host that cannot animate — then there is nothing to sample over time. */
+    readonly frame?: (cb: (t: number) => void) => void;
+    /** Where a failure goes, so `problems` carries it for whoever reads the page's diagnosis. */
+    readonly report: (line: string) => void;
+}
+export declare function sampleFlashes(ctx: FlashSamplerCtx, ms: number): Promise<FlashMeasurement>;

package/dist-pkg/platform/flash-sampler.js

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/flash-sampler — READING THE WORLD'S CANVAS TO ANSWER WCAG 2.3.1 (study item B2; ADR-0027; issue #203).
+//
+// The pure half of this has lived in `core/flash-threshold` since it was written: given the luminance of a grid over time, it
+// says whether the general flash threshold is crossed. THIS is the half that has to touch a browser — copy the world's canvas
+// into a small one, read its pixels frame by frame, and turn them into the grid the pure half expects. It lived inside
+// `boot/create-game`, and it left for the reason ADR-0221 gives: 📏 that file reached 2185 lines and 330 decision nodes, and
+// the debt is paid by SUBJECT.
+//
+// ⚠️ IT ONLY RUNS WHEN IT IS CALLED, and that is a decision and not an omission: sampling a canvas every frame would cost a
+// school's machine the very thing the engine exists to protect. `Engine.measureFlashes(ms)` is how an adult asks.
+//
+// 📌 THE THREE REFUSALS ARE AS MUCH THE ANSWER AS THE MEASUREMENT, and each names what a developer must do: a world that is not
+// a canvas cannot be read at all; a host without `getImageData` or `requestAnimationFrame` cannot sample; and a canvas that
+// reads transparent in every frame is the WebGL case, where the buffer is thrown away unless `preserveDrawingBuffer` asked it
+// not to be. A silent `false` would have sent somebody looking for a flash that was never measured.
+import { analyseFlashes, COLUMNS, ROWS } from '../core/flash-threshold.js';
+/** Ten samples per cell of the pure half's grid — enough for an average, small enough to read every frame. */
+const SAMPLE_COLS = COLUMNS * 10;
+const SAMPLE_ROWS = ROWS * 10;
+/** sRGB → linear light, which is what a luminance average may be taken over (WCAG's own definition). */
+const linear = (v) => { const c = v / 255; return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; };
+export function sampleFlashes(ctx, ms) {
+    const canvas = ctx.canvas();
+    if (!canvas)
+        return Promise.resolve({ measured: false, reason: 'the world is not a canvas and contains none to read' });
+    const copy = ctx.scratch();
+    copy.width = SAMPLE_COLS;
+    copy.height = SAMPLE_ROWS;
+    const c2d = copy.getContext('2d', { willReadFrequently: true });
+    const frame = ctx.frame;
+    if (!c2d || typeof frame !== 'function')
+        return Promise.resolve({ measured: false, reason: 'this host cannot sample canvases' });
+    return new Promise((resolve) => {
+        const frames = [];
+        let start = -1;
+        let anyPixel = false;
+        const step = (now) => {
+            if (start < 0)
+                start = now;
+            let px;
+            try {
+                c2d.clearRect(0, 0, SAMPLE_COLS, SAMPLE_ROWS);
+                c2d.drawImage(canvas, 0, 0, SAMPLE_COLS, SAMPLE_ROWS);
+                px = c2d.getImageData(0, 0, SAMPLE_COLS, SAMPLE_ROWS).data;
+            }
+            catch {
+                resolve({ measured: false, reason: 'the page may not read the world\'s canvas (an image from another origin drew on it)' });
+                return;
+            }
+            const grid = new Float32Array(COLUMNS * ROWS);
+            for (let y = 0; y < SAMPLE_ROWS; y++) {
+                for (let x = 0; x < SAMPLE_COLS; x++) {
+                    const i = (y * SAMPLE_COLS + x) * 4;
+                    if (px[i + 3])
+                        anyPixel = true;
+                    const l = 0.2126 * linear(px[i]) + 0.7152 * linear(px[i + 1]) + 0.0722 * linear(px[i + 2]);
+                    grid[Math.floor(y / 10) * COLUMNS + Math.floor(x / 10)] += l / 100;
+                }
+            }
+            frames.push({ t: now - start, luminances: grid });
+            if (now - start < ms) {
+                frame(step);
+                return;
+            }
+            if (!anyPixel) {
+                resolve({ measured: false, reason: 'the world\'s canvas read transparent in every frame (WebGL canvases need preserveDrawingBuffer)' });
+                return;
+            }
+            const { passes: passed, worstSecond: worst } = analyseFlashes(frames);
+            if (!passed) {
+                ctx.report(`the world's canvas flashed ${worst} times in one second within a 10-degree field `
+                    + '(WCAG 2.3.1 allows 3): it can trigger a seizure in a child with photosensitive epilepsy — slow or dim it');
+            }
+            resolve({ measured: true, passes: passed, worstSecond: worst });
+        };
+        frame(step);
+    });
+}

package/dist-pkg/platform/font-library.d.ts

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { HeavyFile } from './heavy-catalogue.js';
+/** One face of a family: one file, and what its `@font-face` rule says of it. */
+export interface LibraryFace {
+    readonly file: string;
+    /** A weight (`400`) or a variable range (`100 900`), as `font-weight` takes it. */
+    readonly weight: string;
+    readonly style: string;
+    /** A key of `FontLibrary.ranges`; absent = the file covers the whole family (an author's original, ADR-0254). */
+    readonly range?: string;
+    readonly bytes: number;
+    readonly sha256: string;
+    /** The author's original this file was compressed from, for a family with a Reserved Font Name (ADR-0254). */
+    readonly from?: string;
+}
+/** A family of the library: its folder in the mirror, the licence its fonts state, and its faces. */
+export interface LibraryFamily {
+    readonly folder: string;
+    readonly licence: string;
+    readonly faces: readonly LibraryFace[];
+}
+/** The catalogue: the mirror's address, the unicode-ranges the faces share, and the families by name. */
+export interface FontLibrary {
+    readonly mirror: string;
+    readonly ranges: Readonly<Record<string, string>>;
+    readonly families: Readonly<Record<string, LibraryFamily>>;
+}
+/** The heavy-file id of a face: `font:<folder>:<file>`. */
+export declare const libraryFaceId: (family: LibraryFamily, face: LibraryFace) => string;
+/**
+ * Each FILE of these families as a heavy file: its address, its bytes and the sha256 its body must have to be kept. Once each —
+ * a variable file may be declared at two weights, and is kept once.
+ */
+export declare function libraryFiles(library: FontLibrary, families: readonly string[]): HeavyFile[];
+/**
+ * The `@font-face` rules of these families, each `src` at `href(address)` — the delivery's `heavy/` path, resolved against the
+ * page, where the service worker answers from the checked cache. A face with no range covers the whole family (ADR-0254).
+ */
+export declare function libraryFaceRules(library: FontLibrary, families: readonly string[], href: (url: string) => string): string;
+/**
+ * THE FAMILIES A CARTRIDGE DECLARED (`uses.fonts`), less the engine's own — they are packaged, and declaring one asks for
+ * nothing. `problem` names a declaration that is not a list of family names, which the engine cannot read.
+ */
+export declare function declaredFamilies(value: unknown, engineFamilies: ReadonlySet<string>): {
+    readonly asked: string[];
+    readonly problem: string | null;
+};
+/** The line of `problems` for a declared family the library does not hold (ADR-0169: the subject, the cost, the fix). */
+export declare function unknownFamilyLine(family: string): string;
+/** What the root lends the library's start: where the rules go, how a delivery path becomes an address, and where lines go. */
+export interface LibraryFontsPorts {
+    /** The families declared, the engine's own left out (`declaredFamilies`). */
+    readonly asked: readonly string[];
+    /** Writes the rules into the document (a `<style>` of the root's). */
+    readonly declare: (css: string) => void;
+    /** An upstream address → the address the page asks for it at (`heavy/` under the page). */
+    readonly href: (url: string) => string;
+    /** A line of `problems`. */
+    readonly report: (line: string) => void;
+    /** The catalogue; `loadFontLibrary` unless a case hands its own. */
+    readonly load?: () => Promise<FontLibrary>;
+}
+/** What the start answers: the files to keep in the checked cache, and the listener that turns their refusals into lines. */
+export interface LibraryFontsStarted {
+    readonly files: readonly HeavyFile[];
+    readonly onReport: (r: {
+        readonly id: string;
+        readonly outcome: string;
+        readonly error?: string;
+    }) => void;
+}
+/**
+ * DECLARES THE ASKED FAMILIES' FACES, and answers the files to keep. A family the library does not hold is said in `problems`;
+ * a file the delivery did not carry, or whose sha256 differs, is said once per family when its report arrives. Never throws: a
+ * catalogue that does not load is one line, and the game plays in its stack's next face.
+ */
+export declare function startLibraryFonts(p: LibraryFontsPorts): Promise<LibraryFontsStarted>;

package/dist-pkg/platform/font-library.js

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Loads the catalogue — its own chunk, fetched from the page's origin the first time a cartridge declares a family. */
+async function loadFontLibrary() {
+    return (await import('./font-library.json')).default;
+}
+/** The address a face is kept under in the checked cache — the mirror's, as every heavy file's upstream address is. */
+function libraryFaceUrl(library, family, face) {
+    return `${library.mirror}/${family.folder}/${face.file}`;
+}
+/** The heavy-file id of a face: `font:<folder>:<file>`. */
+export const libraryFaceId = (family, face) => `font:${family.folder}:${face.file}`;
+/**
+ * Each FILE of these families as a heavy file: its address, its bytes and the sha256 its body must have to be kept. Once each —
+ * a variable file may be declared at two weights, and is kept once.
+ */
+export function libraryFiles(library, families) {
+    const files = families.flatMap((name) => {
+        const family = library.families[name];
+        return family ? family.faces.map((face) => ({
+            id: libraryFaceId(family, face), url: libraryFaceUrl(library, family, face), bytes: face.bytes, sha256: face.sha256,
+        })) : [];
+    });
+    return files.filter((f, i) => files.findIndex((g) => g.id === f.id) === i);
+}
+/**
+ * The `@font-face` rules of these families, each `src` at `href(address)` — the delivery's `heavy/` path, resolved against the
+ * page, where the service worker answers from the checked cache. A face with no range covers the whole family (ADR-0254).
+ */
+export function libraryFaceRules(library, families, href) {
+    return families.flatMap((name) => {
+        const family = library.families[name];
+        if (!family)
+            return [];
+        return family.faces.map((face) => {
+            const range = face.range ? `unicode-range:${library.ranges[face.range]};` : '';
+            return `@font-face{font-family:'${name}';font-style:${face.style};font-weight:${face.weight};font-display:swap;`
+                + `src:url('${href(libraryFaceUrl(library, family, face))}') format('woff2');${range}}`;
+        });
+    }).join('\n');
+}
+/**
+ * THE FAMILIES A CARTRIDGE DECLARED (`uses.fonts`), less the engine's own — they are packaged, and declaring one asks for
+ * nothing. `problem` names a declaration that is not a list of family names, which the engine cannot read.
+ */
+export function declaredFamilies(value, engineFamilies) {
+    if (value === undefined || value === null)
+        return { asked: [], problem: null };
+    if (!Array.isArray(value) || value.some((f) => typeof f !== 'string' || !f.trim())) {
+        return { asked: [], problem: `fonts: \`uses.fonts\` is ${JSON.stringify(value)}, not a list of family names — no library face was `
+                + 'loaded, so the text the game draws in them falls back to the next face of its stack; declare `uses: { fonts: [\'Lato\'] }`' };
+    }
+    return { asked: [...new Set(value.map((f) => f.trim()))].filter((f) => !engineFamilies.has(f)), problem: null };
+}
+/** The line of `problems` for a declared family the library does not hold (ADR-0169: the subject, the cost, the fix). */
+export function unknownFamilyLine(family) {
+    return `font «${family}»: the game declares it in \`uses.fonts\`, and the engine's font library has no such family — the text `
+        + 'the game draws in it falls back to the next face of its stack; declare a family the library holds '
+        + '(`platform/font-library.json`), or leave it out';
+}
+/** The line of `problems` for a declared family the delivery did not carry, or whose file was refused. */
+function undeliveredLine(family, error) {
+    return `font «${family}»: the game declares it in \`uses.fonts\`, and it was not kept (${error}) — the text the game draws in it `
+        + 'falls back to the next face of its stack, and on a day without a network the face is not there at all; build the delivery '
+        + `with \`inclusionist-heavy <folder> --fonts "${family}"\``;
+}
+/**
+ * DECLARES THE ASKED FAMILIES' FACES, and answers the files to keep. A family the library does not hold is said in `problems`;
+ * a file the delivery did not carry, or whose sha256 differs, is said once per family when its report arrives. Never throws: a
+ * catalogue that does not load is one line, and the game plays in its stack's next face.
+ */
+export async function startLibraryFonts(p) {
+    try {
+        const library = await (p.load ?? loadFontLibrary)();
+        const held = p.asked.filter((f) => library.families[f]);
+        for (const f of p.asked)
+            if (!library.families[f])
+                p.report(unknownFamilyLine(f));
+        if (held.length)
+            p.declare(libraryFaceRules(library, held, p.href));
+        const familyOf = new Map(held.flatMap((f) => library.families[f].faces.map((face) => [libraryFaceId(library.families[f], face), f])));
+        const said = new Set();
+        return {
+            files: libraryFiles(library, held),
+            onReport: (r) => {
+                const family = familyOf.get(r.id);
+                if (!family || r.outcome !== 'falhou' || said.has(family))
+                    return;
+                said.add(family);
+                p.report(undeliveredLine(family, r.error ?? 'refused'));
+            },
+        };
+    }
+    catch (e) {
+        for (const f of p.asked)
+            p.report(undeliveredLine(f, `the font catalogue did not load: ${e instanceof Error ? e.message : String(e)}`));
+        return { files: [], onReport: () => { } };
+    }
+}