@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/platform/vision-loop.d.ts

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+export type LoopHealth = 'ok' | 'slow' | 'stalled';
+export interface VisionLoopDeps {
+    readonly requestFrame: (cb: (ms: number) => void) => number;
+    readonly cancelFrame: (handle: number) => void;
+    readonly now: () => number;
+    readonly every: (cb: () => void, ms: number) => number;
+    readonly stopEvery: (handle: number) => void;
+}
+export interface VisionLoopOptions {
+    readonly onFrame: (ms: number) => void;
+    readonly onError?: (error: unknown) => void;
+    readonly onHealth?: (health: LoopHealth, framesPerSecond: number) => void;
+    readonly floorFps?: number;
+    readonly stallMs?: number;
+    readonly watchMs?: number;
+}
+export interface VisionLoop {
+    start(): void;
+    stop(): void;
+    health(): LoopHealth;
+}
+export declare function createVisionLoop(deps: VisionLoopDeps, { onFrame, onError, onHealth, floorFps, stallMs, watchMs }: VisionLoopOptions): VisionLoop;

package/dist-pkg/platform/vision-loop.js

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/vision-loop — THE CAMERA'S FRAME LOOP, WHICH CANNOT STOP IN SILENCE (ADR-0213; issue #196).
+//
+// · The next frame is booked BEFORE anything that could throw. The lab's loop booked it at the end, one item threw on every frame, and the
+//   eye control stopped on its first frame with nothing on screen saying so — every measurement taken after that was of a stopped page.
+// · A frame that throws is handed to `onError` and the loop goes on.
+// · A watchdog on its OWN clock (a stopped loop cannot report itself) says whether frames are arriving: `stalled` when none came for
+//   `stallMs`, `slow` under `floorFps` in the last second, `ok` otherwise. A reading taken while it is not `ok` is not a reading, and the
+//   child must be told, not left gazing at a control that no longer listens. It reports on change only.
+export function createVisionLoop(deps, { onFrame, onError = () => { }, onHealth = () => { }, floorFps = 8, stallMs = 1000, watchMs = 500 }) {
+    let frame = null, watch = null, health = 'ok', startedAt = 0;
+    const times = [];
+    const tick = (ms) => {
+        frame = deps.requestFrame(tick);
+        times.push(deps.now());
+        try {
+            onFrame(ms);
+        }
+        catch (e) {
+            onError(e);
+        }
+    };
+    const check = () => {
+        const now = deps.now();
+        while (times.length && now - times[0] > 1000)
+            times.shift();
+        const last = times.at(-1) ?? startedAt;
+        if (health === 'stalled' && now - last < stallMs)
+            startedAt = now; // back from a stall: judge the rate on a full second of the new frames
+        const next = now - last >= stallMs ? 'stalled' : now - startedAt >= 1000 && times.length < floorFps ? 'slow' : 'ok';
+        if (next !== health) {
+            health = next;
+            onHealth(health, times.length);
+        }
+    };
+    return {
+        start() {
+            if (frame !== null)
+                return;
+            startedAt = deps.now();
+            health = 'ok';
+            times.length = 0;
+            frame = deps.requestFrame(tick);
+            watch = deps.every(check, watchMs);
+        },
+        stop() {
+            if (frame !== null)
+                deps.cancelFrame(frame);
+            if (watch !== null)
+                deps.stopEvery(watch);
+            frame = null;
+            watch = null;
+        },
+        health: () => health,
+    };
+}

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

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** The files the face reader needs, by catalogue id. */
+export declare const FACE_VISION_FILES: readonly ["visao:runtime", "visao:runtime:cola", "visao:runtime:wasm", "visao:modelo:rosto"];
+/** The files the hand reader needs (ADR-0210 hands map: the Gesture Recognizer gives the canned gestures and the landmarks). */
+export declare const HAND_VISION_FILES: readonly ["visao:runtime", "visao:runtime:cola", "visao:runtime:wasm", "visao:modelo:gestos"];
+/** The part of one detection the eye control reads. */
+export interface FaceDetection {
+    readonly faceBlendshapes?: ReadonlyArray<{
+        readonly categories: ReadonlyArray<{
+            readonly categoryName: string;
+            readonly score: number;
+        }>;
+    }>;
+    readonly facialTransformationMatrixes?: ReadonlyArray<{
+        readonly data: ArrayLike<number>;
+    }>;
+    readonly faceLandmarks?: ReadonlyArray<ReadonlyArray<{
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    }>>;
+}
+interface Landmarker {
+    detectForVideo(frame: unknown, ms: number): FaceDetection;
+    close(): void;
+}
+/** The part of one Gesture Recognizer result the hands map reads: each hand's categories, best first, and its landmarks. */
+export interface HandDetection {
+    readonly gestures?: ReadonlyArray<ReadonlyArray<{
+        readonly categoryName: string;
+        readonly score: number;
+    }>>;
+    readonly landmarks?: ReadonlyArray<ReadonlyArray<{
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    }>>;
+}
+interface Recognizer {
+    recognizeForVideo(frame: unknown, ms: number): HandDetection;
+    close(): void;
+}
+export type Connections = ReadonlyArray<{
+    readonly start: number;
+    readonly end: number;
+}>;
+/** The shape of the `tasks-vision` bundle this module uses. */
+export interface TasksVision {
+    readonly FilesetResolver: {
+        forVisionTasks(wasmBase: string): Promise<unknown>;
+    };
+    readonly FaceLandmarker: {
+        createFromOptions(fileset: unknown, options: object): Promise<Landmarker>;
+        readonly FACE_LANDMARKS_LEFT_EYE: Connections;
+        readonly FACE_LANDMARKS_RIGHT_EYE: Connections;
+        readonly FACE_LANDMARKS_LEFT_IRIS: Connections;
+        readonly FACE_LANDMARKS_RIGHT_IRIS: Connections;
+        readonly FACE_LANDMARKS_LEFT_EYEBROW: Connections;
+        readonly FACE_LANDMARKS_RIGHT_EYEBROW: Connections;
+        readonly FACE_LANDMARKS_LIPS: Connections;
+    };
+    readonly GestureRecognizer: {
+        createFromOptions(fileset: unknown, options: object): Promise<Recognizer>;
+        readonly HAND_CONNECTIONS: Connections;
+    };
+}
+/** The lines the eye control highlights (ADR-0213): the eyes with their irises, and the brows — never the camera's picture (ADR-0212). */
+export interface EyeLines {
+    readonly eyes: Connections;
+    readonly brows: Connections;
+}
+/** The face mode also draws the lips (ADR-0212 §3). */
+export interface FaceLines extends EyeLines {
+    readonly lips: Connections;
+}
+export interface VisionDeps {
+    /** The page's address, to make the delivery paths absolute. */
+    readonly base: string;
+    /**
+     * Whether a catalogue file (by its upstream address) is in the checked cache — `platform/heavy`'s `checkedCacheHas`, over
+     * the host's `caches`. REQUIRED (ADR-0232 D4): the root lends the cache; this module reaches none.
+     */
+    readonly hasFile: (upstreamUrl: string) => Promise<boolean>;
+    readonly importBundle?: (absoluteUrl: string) => Promise<TasksVision>;
+}
+export type Delegate = 'GPU' | 'CPU';
+export interface FaceTracker {
+    /** One frame; null while it has nothing to say (no face, or the CPU landmarker still being built after a GPU failure). */
+    detect(frame: unknown, ms: number): FaceDetection | null;
+    delegate(): Delegate;
+    /** The connection sets the bundle ships for the eyes, irises and brows, to draw over the game. */
+    readonly eyeLines: EyeLines;
+    /** The same lines and the lips, for the face mode. */
+    readonly faceLines: FaceLines;
+    close(): void;
+}
+export type FaceTrackerLoad = {
+    readonly ok: true;
+    readonly tracker: FaceTracker;
+} | {
+    readonly ok: false;
+    readonly missing: readonly string[];
+};
+export interface HandTracker {
+    /** The hand's bones, as the bundle ships them, to draw over the game (ADR-0215). */
+    readonly handLines: Connections;
+    /** One frame; null while it has nothing to say. */
+    detect(frame: unknown, ms: number): HandDetection | null;
+    delegate(): Delegate;
+    close(): void;
+}
+export type HandTrackerLoad = {
+    readonly ok: true;
+    readonly tracker: HandTracker;
+} | {
+    readonly ok: false;
+    readonly missing: readonly string[];
+};
+export declare function loadFaceTracker(deps: VisionDeps): Promise<FaceTrackerLoad>;
+/** The Gesture Recognizer, one hand, in video mode — as the lab's map rounds ran it. */
+export declare function loadHandTracker(deps: VisionDeps): Promise<HandTrackerLoad>;
+/** The camera, video only, at the size the readings were measured. */
+export declare function openCamera(media: {
+    getUserMedia(c: MediaStreamConstraints): Promise<MediaStream>;
+}): Promise<MediaStream>;
+/** Let the camera go: every track stops, so the device's light goes off. */
+export declare function closeCamera(stream: {
+    getTracks(): ReadonlyArray<{
+        stop(): void;
+    }>;
+} | null | undefined): void;
+export {};

package/dist-pkg/platform/vision.js

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/vision — THE FACE LANDMARKER AND THE CAMERA, FROM THE GAME'S OWN ORIGIN (ADR-0213, ADR-0177; issue #196).
+//
+// · MediaPipe `tasks-vision` and the face model are the files the install already fetched and checked by sha256 (`platform/heavy`).
+//   They are asked for at `heavy/<host><path>` beside the page, so no third-party host is contacted, and a file that is not in the
+//   checked cache is never loaded: the reader says which ones are missing instead, so the child hears why the eyes do not work.
+// · The bundle is imported by an ABSOLUTE address: a relative one resolves against this module, not against the page.
+// · GPU first; a GPU that fails to create the landmarker, or fails on a frame, gives way to the CPU once. The frame that failed reads
+//   nothing while the CPU landmarker is being built.
+// · `tasks-vision` tries to send usage logs to `odml.pa.googleapis.com`; the page's CSP refuses it (measured in the lab) and that is
+//   kept on purpose — nothing about the child's camera leaves the device.
+// · The camera is video only, 640×480: the lab's readings were measured at that size, and a larger capture changed them.
+import { HEAVY_FILES, deliveryPath } from './heavy.js';
+/** The files the face reader needs, by catalogue id. */
+export const FACE_VISION_FILES = ['visao:runtime', 'visao:runtime:cola', 'visao:runtime:wasm', 'visao:modelo:rosto'];
+/** The files the hand reader needs (ADR-0210 hands map: the Gesture Recognizer gives the canned gestures and the landmarks). */
+export const HAND_VISION_FILES = ['visao:runtime', 'visao:runtime:cola', 'visao:runtime:wasm', 'visao:modelo:gestos'];
+const urlOf = (id) => HEAVY_FILES.find((x) => x.id === id).url; // the vision entries are in the catalogue, with addresses
+const OPTIONS = (modelAssetPath, delegate) => ({
+    baseOptions: { modelAssetPath, delegate }, runningMode: 'VIDEO', numFaces: 1,
+    outputFaceBlendshapes: true, outputFacialTransformationMatrixes: true,
+});
+/** Checks the files in the checked cache and opens the bundle; the missing ids when any file is not there. */
+async function open(deps, files) {
+    const { hasFile } = deps;
+    const importBundle = deps.importBundle ?? ((u) => import(/* @vite-ignore */ u));
+    const missing = [];
+    for (const id of files)
+        if (!(await hasFile(urlOf(id))))
+            missing.push(id);
+    if (missing.length)
+        return { missing };
+    const at = (id) => new URL(deliveryPath(urlOf(id)), deps.base).href;
+    const vision = await importBundle(at('visao:runtime'));
+    const glue = at('visao:runtime:cola');
+    return { vision, fileset: await vision.FilesetResolver.forVisionTasks(glue.slice(0, glue.lastIndexOf('/'))), at };
+}
+/**
+ * GPU first; a GPU that fails to create, or fails on a frame, gives way to the CPU once; the frame that failed reads nothing while the CPU
+ * one is built; a CPU that cannot be built makes the next frame throw. Shared by the face and the hands.
+ */
+async function withFallback(create, read) {
+    let delegate = 'GPU', closed = false, failure = null;
+    let current;
+    try {
+        current = await create('GPU');
+    }
+    catch {
+        delegate = 'CPU';
+        current = await create('CPU');
+    }
+    const toCpu = () => {
+        current?.close();
+        current = null;
+        delegate = 'CPU';
+        create('CPU').then((l) => { if (closed)
+            l.close();
+        else
+            current = l; }, (e) => { failure = e; });
+    };
+    return {
+        detect(frame, ms) {
+            if (failure)
+                throw failure; // the CPU could not be built either: the frame loop says so on screen
+            if (!current)
+                return null;
+            try {
+                return read(current, frame, ms);
+            }
+            catch (e) {
+                if (delegate === 'CPU')
+                    throw e;
+                toCpu();
+                return null;
+            }
+        },
+        delegate: () => delegate,
+        close() { closed = true; current?.close(); current = null; },
+    };
+}
+export async function loadFaceTracker(deps) {
+    const o = await open(deps, FACE_VISION_FILES);
+    if ('missing' in o)
+        return { ok: false, missing: o.missing };
+    const F = o.vision.FaceLandmarker;
+    const eyeLines = {
+        eyes: [...F.FACE_LANDMARKS_LEFT_EYE, ...F.FACE_LANDMARKS_RIGHT_EYE, ...F.FACE_LANDMARKS_LEFT_IRIS, ...F.FACE_LANDMARKS_RIGHT_IRIS],
+        brows: [...F.FACE_LANDMARKS_LEFT_EYEBROW, ...F.FACE_LANDMARKS_RIGHT_EYEBROW],
+    };
+    const shell = await withFallback((d) => F.createFromOptions(o.fileset, OPTIONS(o.at('visao:modelo:rosto'), d)), (l, frame, ms) => l.detectForVideo(frame, ms));
+    return {
+        ok: true,
+        tracker: {
+            ...shell,
+            eyeLines,
+            faceLines: { ...eyeLines, lips: F.FACE_LANDMARKS_LIPS },
+        },
+    };
+}
+/** The Gesture Recognizer, one hand, in video mode — as the lab's map rounds ran it. */
+export async function loadHandTracker(deps) {
+    const o = await open(deps, HAND_VISION_FILES);
+    if ('missing' in o)
+        return { ok: false, missing: o.missing };
+    const options = (d) => ({ baseOptions: { modelAssetPath: o.at('visao:modelo:gestos'), delegate: d }, runningMode: 'VIDEO', numHands: 1 });
+    const shell = await withFallback((d) => o.vision.GestureRecognizer.createFromOptions(o.fileset, options(d)), (g, frame, ms) => g.recognizeForVideo(frame, ms));
+    return { ok: true, tracker: { ...shell, handLines: o.vision.GestureRecognizer.HAND_CONNECTIONS } };
+}
+/** The camera, video only, at the size the readings were measured. */
+export function openCamera(media) {
+    return media.getUserMedia({ video: { width: 640, height: 480 }, audio: false });
+}
+/** Let the camera go: every track stops, so the device's light goes off. */
+export function closeCamera(stream) {
+    for (const t of stream?.getTracks() ?? [])
+        t.stop();
+}

package/dist-pkg/platform/voice-listener.d.ts

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { AudioContextLike, StreamLike } from './microphone.js';
+import type { VoskModel } from './vosk-runtime.js';
+/** How much sound is handed over at a time. The lab's number; smaller starves the recogniser, larger delays a command. */
+export declare const VOICE_BLOCK = 4096;
+export interface VoiceListenerDeps {
+    readonly model: VoskModel;
+    /** Every phrase the recogniser may answer with: the language's words, plus what the open menu is showing (ADR-0194). */
+    readonly grammar: readonly string[];
+    /**
+     * The host's `navigator.mediaDevices.getUserMedia`, lent by the root (ADR-0232 D4). REQUIRED, and `undefined` is a device
+     * with no microphone: REFUSED and said, never hidden.
+     */
+    readonly getUserMedia: ((constraints: {
+        audio: object | boolean;
+    }) => Promise<StreamLike>) | undefined;
+    /** A new audio context from the host's `AudioContext`, lent by the root. REQUIRED. */
+    readonly createContext: () => AudioContextLike;
+    /** What the recogniser has heard so far in this utterance. */
+    readonly onPartial: (text: string) => void;
+    /**
+     * The utterance ended, with the recogniser's last word on it: a name the partials held back because another item's name
+     * continued it («voltar» while «voltar ao jogo» could follow) is decided HERE (ADR-0194 §3), and whoever counts what was
+     * already answered for starts a new sentence. `''` when the recogniser heard nothing it knows.
+     */
+    readonly onFinal?: (text: string) => void;
+}
+export interface VoiceListener {
+    /** The words the recogniser may answer with, from now on. A new grammar is a new recogniser; the microphone stays open. */
+    setGrammar(grammar: readonly string[]): void;
+    /** Gives the microphone back and closes everything. Safe to call twice. */
+    stop(): Promise<void>;
+}
+/**
+ * Opens the microphone and feeds the recogniser until `stop()`.
+ *
+ * ⚠️ THE MICROPHONE IS ASKED FOR WITH ECHO CANCELLATION AND NOISE SUPPRESSION, which is what a classroom needs: twenty children
+ * in one room is the case, not the exception. Mono, because the recogniser hears one channel.
+ */
+export declare function startVoiceListening(d: VoiceListenerDeps): Promise<VoiceListener>;

package/dist-pkg/platform/voice-listener.js

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/voice-listener — THE MICROPHONE THAT HEARS COMMANDS, AND LETS GO (ADR-0189, ADR-0193; issue #184).
+//
+// The reading opens a microphone for one sentence and closes it (`platform/microphone`); this one stays open while the child
+// plays by voice, because a command may come at any moment. Everything else is the same promise: the sound is handed to a
+// recogniser ON THIS MACHINE, nothing is kept, and letting go is part of the job — a page that is still listening after the
+// child turned voice off is the promise broken, however good the reason.
+//
+// 📌 THE GRAMMAR CARRIES `[unk]`, and it is what lets the recogniser answer «that was not one of these». Without it a closed
+// grammar pushes whatever it hears to the NEAREST word — the lab measured «configurações de inclusão» coming back as «quatro»,
+// which in a game is a button the child never pressed.
+//
+// ⚠️ `ScriptProcessorNode`, deprecated, for the reason already written in `platform/microphone`: the AudioWorklet replacement
+// needs its code served as a module and the engine's policy has no `blob:` in `script-src` (ADR-0214). It is also what
+// `acceptWaveform` takes directly. Written here so the next person does not «fix» it without that decision.
+/** How much sound is handed over at a time. The lab's number; smaller starves the recogniser, larger delays a command. */
+export const VOICE_BLOCK = 4096;
+const withUnknown = (grammar) => JSON.stringify([...grammar, '[unk]']);
+/**
+ * Opens the microphone and feeds the recogniser until `stop()`.
+ *
+ * ⚠️ THE MICROPHONE IS ASKED FOR WITH ECHO CANCELLATION AND NOISE SUPPRESSION, which is what a classroom needs: twenty children
+ * in one room is the case, not the exception. Mono, because the recogniser hears one channel.
+ */
+export async function startVoiceListening(d) {
+    const { getUserMedia } = d;
+    if (!getUserMedia)
+        throw new Error('voice-listener: this device cannot open a microphone');
+    const context = d.createContext();
+    let recognizer = new d.model.KaldiRecognizer(context.sampleRate, withUnknown(d.grammar));
+    const listen = (r) => {
+        r.on('partialresult', (heard) => { const t = heard.result.partial; if (t)
+            d.onPartial(t); });
+        r.on('result', (heard) => { d.onFinal?.(heard.result.text ?? ''); });
+    };
+    listen(recognizer);
+    const stream = await getUserMedia({ audio: { echoCancellation: true, noiseSuppression: true, channelCount: 1 } });
+    const node = context.createScriptProcessor(VOICE_BLOCK, 1, 1);
+    let stopped = false;
+    node.onaudioprocess = (e) => {
+        if (stopped)
+            return;
+        // ⚠️ A recogniser that throws on one block must not take the microphone down with it: the next block is a new chance, and
+        // a child mid-sentence would otherwise lose the rest of it.
+        try {
+            recognizer.acceptWaveform(e.inputBuffer);
+        }
+        catch { /* this block is lost, the next is not */ }
+    };
+    context.createMediaStreamSource(stream).connect(node);
+    // 📌 The graph has to REACH the destination or nothing is pulled through it — and it must be silent, or the classroom hears
+    // itself. That is what the muted gain is for; it is not decoration.
+    node.connect(context.destination);
+    return {
+        setGrammar(grammar) {
+            if (stopped)
+                return;
+            const previous = recognizer;
+            recognizer = new d.model.KaldiRecognizer(context.sampleRate, withUnknown(grammar));
+            listen(recognizer);
+            try {
+                previous.remove();
+            }
+            catch { /* an old recogniser that is already gone is not a failure */ }
+        },
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            node.onaudioprocess = null;
+            try {
+                node.disconnect();
+            }
+            catch { /* a node already detached is not a failure */ }
+            for (const t of stream.getTracks())
+                t.stop();
+            try {
+                recognizer.remove();
+            }
+            catch { /* idem */ }
+            try {
+                d.model.terminate?.();
+            }
+            catch { /* idem */ }
+            await context.close();
+        },
+    };
+}

package/dist-pkg/platform/voice-plan.d.ts

@@ -1,109 +1,26 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** Uma voz do catálogo. `voice` é o identificador no fornecedor; `engine` é o motor que a lê. */
-export interface VozNeural {
+/** A voice a child may pick. `voice` is its identifier in its engine; `engine` is the engine that reads it. */
+export interface NeuralVoice {
     readonly locale: string;
     readonly engine: string;
     readonly voice: string;
 }
 /**
- * AS QUATRO QUE A ENGINE GARANTE (ADR-0110), decididas pelo Dev em 2026-09-08.
- *
- * ⚠️ TODAS `vits-piper` E NENHUMA `ncnn`, que o ADR-0065 §5 já proibia: `ncnn` é outro MOTOR DE INFERÊNCIA —
- * modelos `.param`/`.bin` e não `.onnx` — e este projeto corre sherpa-onnx. Dois dos links que chegaram em
- * 2026-09-08 apontavam para os espelhos `ncnn`, e é por isso que a proibição tem gate e não só um comentário.
- * ⚠️ E NENHUMA `int8`, pela razão MEDIDA do mesmo §5: no backend WASM o int8 corre ~3× MAIS LENTO que o fp32
- * (RTF 5,6 contra 2,5, do log do próprio Dev) e produz saída incorrecta ou muda. Quantizar não encurta a
- * espera aqui — alonga-a.
+ * The voices a child may pick for a language (ADR-0185): matched on the LANGUAGE of the tag, not the region — a Mexican
+ * voice reads Spanish from Spain, and a Brazilian game tagged `pt` is still Portuguese. A voice reading another language
+ * is not offered: Portuguese text through English phonemes is noise.
  */
-export declare const VOZES_NEURAIS: readonly VozNeural[];
+export declare function voicesForLocale(tag: string, catalogue: readonly NeuralVoice[]): readonly NeuralVoice[];
 /**
- * DE ONDE VÊM OS MODELOS (ADR-0114), num sítio só.
- *
- * 📏 MEDIDO EM 2026-09-08, e não escolhido: o `piper.ttstool.com` — que o Dev nomeou ao perguntar — serve o
- * próprio runtime da própria origem e busca os modelos aqui. As quatro vozes deste catálogo respondem 200
- * neste endereço, com `Access-Control-Allow-Origin: *`, logo um PWA pode buscá-las de outra origem.
- *
- * ⚠️ UM SÍTIO SÓ É A METADE QUE O REGISTO PEDE. Um endereço repetido no ponto de uso é como o CDN do
- * WebGazer chegou ao `ui/webcam` — escrito à mão, sem política, e sem ninguém a poder mudá-lo de uma vez.
- *
- * ========================= 🔴 MUDOU DE ESPELHO EM 2026-09-09, E A REGRA É «BUSCAR DE ONDE O LEITOR LÊ» ====
- * Era `rhasspy/piper-voices`, medido a 08/09 como o espelho que o `piper.ttstool.com` usa. Depois de o
- * `platform/pesados` passar a descer os modelos no primeiro carregamento, mediu-se o outro lado — o
- * `@mintplex-labs/piper-tts-web@1.0.4` INSTALADO, lido do bundle e não do README — e ele busca em
- * `diffusionstudio/piper-voices`, com uma guarda que recusa qualquer URL fora de `huggingface.co`.
- *
- * 🎯 ENDEREÇOS DIFERENTES SIGNIFICAM CACHE DIFERENTE: a Cache Storage é indexada pela URL do pedido, logo os
- * 241 MB que desciam no primeiro dia NÃO ERAM LIDOS POR NINGUÉM, e a biblioteca descarregava tudo outra vez
- * no dia em que a voz fosse pedida. Até 482 MB num link de escola para uma voz.
- *
- * 📏 E OS DOIS ESPELHOS SERVEM OS MESMOS BYTES — 63 201 294 para o `pt_BR-faber-medium`, caminhos idênticos,
- * `Access-Control-Allow-Origin: *` nos dois. Medido nos dois no mesmo minuto, o que torna esta troca uma
- * correcção de facto e não uma preferência entre fornecedores.
- *
- * ⚠️ A CLÁUSULA DO ADR-0114 NÃO SE MEXE: o host continua nomeado num ponto só. O que mudou foi QUAL, e a
- * regra que decide isso passa a estar escrita para não voltar a divergir — **busca-se de onde o LEITOR lê**.
- * No dia em que a engine for dona do runtime (ADR-0124 cláusula 2), o leitor passa a ser ela e é ela que
- * escolhe; até lá, o único leitor é a porta do cartucho.
+ * A language's name, written in another language: `languageName('en-GB', 'pt-BR')` is «inglês» — the primary language, because a
+ * voice of the same language would have read the part (ADR-0243 §3). Where the platform cannot name it, the tag's language code.
  */
-export declare const HOST_DOS_MODELOS = "https://huggingface.co/diffusionstudio/piper-voices/resolve/main/";
+export declare function languageName(tag: string, inLanguage: string): string;
+/** Does a voice tagged `locale` speak the language of `tag`? By the primary language, as `voicesForLocale` matches. */
+export declare function speaksLanguageOf(locale: string, tag: string): boolean;
 /**
- * O CAMINHO DO MODELO, DERIVADO DO IDENTIFICADOR — e não uma segunda tabela.
- *
- * `pt_BR-faber-medium` diz tudo o que o caminho precisa: `pt/pt_BR/faber/medium/pt_BR-faber-medium.onnx`.
- * 🎯 DERIVAR EM VEZ DE TABELAR é a decisão inteira desta função: uma tabela de caminhos ao lado da tabela
- * de vozes seria o mesmo facto escrito duas vezes, e este repositório já pagou isso três vezes — o
- * `DomQuery`, os rótulos de movimento reduzido, as chaves de armazenamento. Duas listas divergem, e
- * divergem uma entrada de cada vez.
- *
- * ⚠️ Devolve `null` para um identificador que não tenha a forma esperada, em vez de montar um caminho
- * torto: uma URL inventada dá 404 na escola, e um `null` dá para reportar antes de sair de casa.
+ * THE VOICE OF A LANGUAGE (ADR-0243 §2): the child's chosen voice when it speaks that language; else the first voice `VOICE_ORDER`
+ * reaches — the exact tag before the region, a browser voice before a neural one. `chosen` comes in order of precedence.
+ * 🔴 No voice of another language is ever returned: `null` means the list has none for it, and the part is not spoken (§3).
  */
-export declare function caminhoDoModelo(v: VozNeural): string | null;
-/** O endereço completo do modelo. `null` quando o identificador não se deixa ler. */
-export declare function urlDoModelo(v: VozNeural): string | null;
-/**
- * A CONFIGURAÇÃO da voz, que o motor lê junto com o modelo.
- *
- * 📌 `.onnx.json` e não um segundo caminho: é o mesmo ficheiro com outro sufixo, medido a responder 200 no
- * mesmo sítio. Escrevê-lo como derivação mantém a regra de que o identificador é a única fonte.
- */
-export declare function urlDaConfig(v: VozNeural): string | null;
-/** Em que pé está cada voz. `falhou` é um estado e não uma excepção — ver `vozEmUso`. */
-export type EstadoDaVoz = 'ausente' | 'a-buscar' | 'pronta' | 'falhou';
-/** O que se sabe de cada voz, por identificador. Uma voz ausente do mapa é `ausente`. */
-export type EstadosDasVozes = Readonly<Record<string, EstadoDaVoz | undefined>>;
-export declare const estadoDe: (estados: EstadosDasVozes, v: VozNeural) => EstadoDaVoz;
-/**
- * A ORDEM POR QUE SE BUSCAM: primeiro as do idioma corrente, depois as outras, cada grupo na ordem do
- * catálogo. Só entram as que ainda não estão prontas nem em curso.
- *
- * ⚠️ O IDIOMA CORRENTE PRIMEIRO É A REGRA INTEIRA, e ela é sobre uma criança e não sobre eficiência: as
- * outras são para «conforme interesse do jogador», mas a dela é a que ela precisa AGORA. Buscar em ordem de
- * catálogo faria uma criança brasileira esperar por duas vozes inglesas na rede de uma escola.
- *
- * 📌 `falhou` VOLTA À FILA. Uma escola perde a rede a meio da manhã e recupera-a; uma voz marcada como
- * falhada para sempre seria uma criança sem voz até alguém recarregar a página. Quem chama decide QUANDO
- * tentar de novo — este módulo só diz que ainda há o que buscar.
- */
-export declare function ordemDeBusca(estados: EstadosDasVozes, localeCorrente: string, catalogo?: readonly VozNeural[]): VozNeural[];
-/** O que a criança ouve agora. `recuo` é a voz do sistema — eSpeak ou Web Speech. */
-export type VozEmUso = {
-    readonly tipo: 'neural';
-    readonly voice: string;
-} | {
-    readonly tipo: 'recuo';
-    readonly porque: 'a-buscar' | 'sem-voz-para-o-idioma' | 'falhou' | 'ausente';
-};
-/**
- * QUEM ESTÁ A FALAR, E POR QUE — e esta função é o gate 3 do ADR-0110 em forma de código.
- *
- * ⚠️ O DEFEITO QUE ELA IMPEDE TEM NOME NESTE REPOSITÓRIO: «um recuo que se apresenta como a coisa real é a
- * família do `reflectTTS`». Uma engine que dissesse «voz neural» enquanto o modelo ainda desce faria um adulto
- * concluir que a qualidade que ouve É a qualidade final — e desistir de esperar por uma coisa que já vinha a
- * caminho. Dizer `recuo` e dizer PORQUÊ custa uma linha e é a diferença entre informar e enganar.
- *
- * 📌 A PRIMEIRA VOZ PRONTA DO IDIOMA, e nada mais: onde há duas prontas, esta função NÃO escolhe entre elas —
- * devolve a primeira do catálogo porque tem de devolver alguma, e qual delas a criança prefere é a pergunta
- * que o ADR-0110 deixou em aberto. Ver o cabeçalho.
- */
-export declare function vozEmUso(estados: EstadosDasVozes, localeCorrente: string, catalogo?: readonly VozNeural[]): VozEmUso;
+export declare function voiceOfLanguage(tag: string, voices: readonly NeuralVoice[], chosen?: readonly (string | null | undefined)[]): NeuralVoice | null;