@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -1,11 +1,78 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** Estado do modo pessoa surda. Escolha da PESSOA, persistida — não inferência sobre um widget de terceiro. */
-export declare let librasOpen: boolean;
-export declare function setOnLibrasChange(fn: () => void): void;
-export declare function vlibrasSay(text: string): void;
-/** O modo pessoa surda está ligado? Lê o NOSSO estado — nunca mais a geometria do widget. */
-export declare function vlibrasOpen(): boolean;
-/** Liga/desliga o modo pessoa surda. Um toggle de verdade: o estado é nosso, então ele sempre alterna. */
-export declare function toggleLibras(): void;
-/** Mantido para o laço do jogo, que o chama a cada quadro. Já não decide nada — o estado é nosso. */
-export declare function vlTick(): void;
+import type { Translate } from '../core/i18n.js';
+import type { Store } from '../platform/storage.js';
+/**
+ * What a sign request comes back with: signed — and, when part of the text was left out, what and why (`unsigned`) — or why
+ * not. The reason and the part left out go into `problems`.
+ */
+export type SignResult = {
+    readonly signed: true;
+    readonly unsigned?: string;
+} | {
+    readonly signed: false;
+    readonly reason: string;
+};
+/** A player of Libras: whatever signs, or a test's double. */
+export interface Interpreter {
+    /** Signs exactly this text, in front of the screen; resolves with whether it could. */
+    readonly sign: (text: string) => Promise<SignResult>;
+    /** Takes the interpreter off the screen: deaf mode was turned off. */
+    readonly hide: () => void;
+    /** Releases the player: its root is gone. */
+    readonly dispose: () => void;
+}
+/**
+ * Why a delivery that carries no Libras player cannot sign, and the fix — the ONE reason both `NO_INTERPRETER` and the free
+ * player give for it, so `problems` says the same thing whichever of them answered.
+ */
+export declare const LIBRAS_NOT_INSTALLED = "a Libras player is not installed in this delivery \u2014 build it with `inclusionist-heavy <folder> --libras`";
+/** The interpreter of a delivery that carries no Libras player (ADR-0234): it signs nothing and says why, and how to fix it. */
+export declare const NO_INTERPRETER: Interpreter;
+/** Where the person's choice is kept: the page's store, built by the root (ADR-0232, issue #207). */
+export type DeafModeStore = Pick<Store, 'getBool' | 'setBool'>;
+/** What a deaf mode is built over. Every port is the root's. */
+export interface DeafModePorts {
+    /** The page's store: the choice is read once, at build, and written at each toggle. */
+    readonly store: DeafModeStore;
+    /** The child's captions setting, read live: with deaf mode off it alone decides whether a sound is captioned. */
+    readonly captionsSetting: () => boolean;
+    /** The root's translator: what the child is told comes out in the page's language. */
+    readonly t: Translate;
+    /** Who signs. */
+    readonly interpreter: Interpreter;
+    /**
+     * The narration: what the sonar's text does with deaf mode off. `seat`, the player who pressed, when the sonar knows it: then
+     * the reading takes turns with the other players' (ADR-0234, errata 2026-09-26).
+     */
+    readonly speak: (text: string, seat?: number) => void;
+    /** The caption host, which writes while deaf mode is on (`Engine.captionSound`). */
+    readonly caption: (text: string) => void;
+    /** The announcer: what the child is told about the interpreter. */
+    readonly tell: (text: string) => void;
+    /** A line of `problems`; each distinct line is reported once. */
+    readonly report: (line: string) => void;
+}
+/** One root's deaf mode. */
+export interface DeafMode {
+    /** Is deaf mode on? The person's choice — never a player's state. */
+    readonly isOn: () => boolean;
+    /** Turns deaf mode on or off. It always flips: the state is ours. Off, the interpreter leaves the screen. */
+    readonly toggle: () => void;
+    /** Does a sound get its caption now? Deaf mode on, or the captions setting on — every sound is captioned in deaf mode. */
+    readonly captionsOn: () => boolean;
+    /**
+     * What the sonar found: captioned and handed to the interpreter with deaf mode on, spoken with it off — by `seat`'s turn, when
+     * the player who pressed is known (`speak`).
+     */
+    readonly sonar: (text: string, seat?: number) => void;
+    /** Runs `fn` when the mode turns on or off (a host's reflow); returns its release. */
+    readonly onChange: (fn: () => void) => () => void;
+    /** Releases the interpreter; an answer still on its way is dropped. */
+    readonly dispose: () => void;
+}
+/** The line `problems` gets when the interpreter cannot sign: the subject, the child's cost and the fix (ADR-0169). */
+export declare function signingUnavailableLine(reason: string): string;
+/** The line `problems` gets when the interpreter signed a text but left part of it out: what, the child's cost, the fix. */
+export declare function signedInPartLine(unsigned: string): string;
+/** Builds a deaf mode. The stored choice is read here, at build, never at import (ADR-0232). */
+export declare function createDeafMode({ store, captionsSetting, t, interpreter, speak, caption, tell, report }: DeafModePorts): DeafMode;

package/dist-pkg/ui/vlibras.js

@@ -1,87 +1,136 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/vlibras.ts — MODO PESSOA SURDA (intérprete de Libras) — Estágio 4, Tier 1.
-//
-// DOIS DEFEITOS CONSERTADOS AQUI, e eles têm a mesma raiz.
-//
-// `librasOpen` era deduzido da GEOMETRIA do botão de acesso do VLibras: altura zero ou sem `offsetParent`
-// significava "o painel está aberto". Isso funcionava enquanto o widget renderizava dentro do nosso
-// `<div vw>`. Ele parou — hoje ele anexa `#vlibras-access-wrapper` direto no `<body>` —, e o que sobrou no
-// nosso markup é um div VAZIO, de 747×0. Altura zero. Então o detector respondia "aberto" para sempre:
-//
-//   1. o layout reservava 380px à direita para um intérprete inexistente e empurrava o jogo para fora da
-//      tela (medido: canvas em `left: -136`);
-//   2. o toggle não desligava, porque mandava um evento de fechar a um widget que não estava ali.
-//
-// (É a mesma raiz da falha do gate axe-core, consertada em 0657578: o VLibras mudou de lugar e três coisas
-// que o localizavam pelo nosso markup pararam juntas, em silêncio.)
-//
-// O ESTADO AGORA É NOSSO. `librasOpen` é uma escolha da pessoa, persistida, e não a leitura de um retângulo
-// de terceiro. Um modo de acessibilidade cujo estado é inferido da geometria de outra biblioteca é um modo
-// que desliga sozinho quando essa biblioteca muda — e quem paga é quem depende dele.
-//
-// O QUE AINDA NÃO É: o Dev decidiu que o intérprete deve aparecer NA FRENTE da tela quando um áudio toca e
-// sumir depois, sem clicar em nada e sem depender de clicar em textos. O widget do VLibras não faz isso (é um
-// painel encaixado, que traduz o texto do elemento clicado), então essa é a razão de o pilar 2 do ADR-0010
-// prever um motor próprio em zdog. Este arquivo para de empurrar a tela e passa a ter um toggle honesto; o
-// intérprete sob demanda é trabalho à parte.
-import { t } from '../core/i18n.js';
-import * as store from '../platform/storage.js';
-/** Estado do modo pessoa surda. Escolha da PESSOA, persistida — não inferência sobre um widget de terceiro. */
-export let librasOpen = store.getBool('incl_libras', false);
-let _vlOpen = false, _vlNode = null, _vlBusyUntil = 0, _vlNext = null;
-let _onLibrasChange = () => { };
-// Registra o reflow (layout) a rodar quando o painel abre/fecha. Chamado no boot do game.js.
-export function setOnLibrasChange(fn) { _onLibrasChange = fn; }
-// Fala em Libras: manda o texto ao intérprete (só quando o painel está aberto). Fila de 1 — fala nova substitui a pendente.
-export function vlibrasSay(text) {
-    if (!_vlOpen || !text)
-        return;
-    const now = Date.now();
-    if (now < _vlBusyUntil) {
-        _vlNext = text;
-        return;
-    }
-    _vlBusyUntil = now + 4000;
-    if (!_vlNode) {
-        _vlNode = document.createElement('span');
-        _vlNode.setAttribute('aria-hidden', 'true');
-        _vlNode.style.cssText = 'position:fixed;left:0;top:0;width:1px;height:1px;overflow:hidden;opacity:.01;z-index:1;pointer-events:auto';
-        document.body.appendChild(_vlNode);
-    }
-    _vlNode.textContent = text;
-    try {
-        _vlNode.click();
-    }
-    catch (e) { /* noop */ }
-    setTimeout(() => { const nx = _vlNext; _vlNext = null; _vlBusyUntil = 0; if (nx)
-        vlibrasSay(nx); }, 4100);
+/**
+ * Why a delivery that carries no Libras player cannot sign, and the fix — the ONE reason both `NO_INTERPRETER` and the free
+ * player give for it, so `problems` says the same thing whichever of them answered.
+ */
+export const LIBRAS_NOT_INSTALLED = 'a Libras player is not installed in this delivery — build it with `inclusionist-heavy <folder> --libras`';
+/** The interpreter of a delivery that carries no Libras player (ADR-0234): it signs nothing and says why, and how to fix it. */
+export const NO_INTERPRETER = {
+    sign: () => Promise.resolve({ signed: false, reason: LIBRAS_NOT_INSTALLED }),
+    hide: () => { },
+    dispose: () => { },
+};
+/** The line `problems` gets when the interpreter cannot sign: the subject, the child's cost and the fix (ADR-0169). */
+export function signingUnavailableLine(reason) {
+    return `deaf mode's sign-language interpreter could not sign: ${reason}. A deaf child keeps the captions and the written `
+        + 'text, but nothing is signed when she presses the sonar — give deaf mode a Libras player that can sign here (ADR-0234)';
 }
-const vwBtn = () => document.querySelector('[vw-access-button]');
-/** O modo pessoa surda está ligado? Lê o NOSSO estado — nunca mais a geometria do widget. */
-export function vlibrasOpen() { return librasOpen; }
-/** Liga/desliga o modo pessoa surda. Um toggle de verdade: o estado é nosso, então ele sempre alterna. */
-export function toggleLibras() {
-    librasOpen = !librasOpen;
-    _vlOpen = librasOpen;
-    store.setBool('incl_libras', librasOpen);
-    // Tentativa BEST-EFFORT de acordar o widget do VLibras, se ele estiver carregado. Falhar aqui não pode
-    // impedir o modo de ligar: o estado é a escolha da pessoa, o widget é só um tradutor possível para ela.
-    const b = vwBtn();
-    if (librasOpen && b) {
-        try {
-            b.click();
+/** The line `problems` gets when the interpreter signed a text but left part of it out: what, the child's cost, the fix. */
+export function signedInPartLine(unsigned) {
+    return `deaf mode's sign-language interpreter signed only part of what the sonar found: ${unsigned}. A deaf child reads `
+        + 'those words in the captions and is not signed them — give the player the signs or the letters it lacks (ADR-0234)';
+}
+/** Builds a deaf mode. The stored choice is read here, at build, never at import (ADR-0232). */
+export function createDeafMode({ store, captionsSetting, t, interpreter, speak, caption, tell, report }) {
+    let on = store.getBool('incl_libras', false);
+    let disposed = false;
+    /** Whether the child has been told, since the mode last came on, that signing is unavailable — told once, not per press. */
+    let told = false;
+    /** The lines already in `problems`: a child pressing the sonar twenty times is one diagnosis, not twenty. */
+    const reported = new Set();
+    const changeListeners = new Set();
+    /**
+     * The answer to one request, heard only while the mode that asked is still on and the root still alive. The first «no»
+     * is told through the announcer AND written after the sonar's text: she is deaf, and the announcer alone is heard.
+     */
+    const reportOnce = (line) => { if (!reported.has(line)) {
+        reported.add(line);
+        report(line);
+    } };
+    /** Signed, perhaps in part: what was left out is a diagnosis, not a notice — the child saw the rest signed. */
+    const signedPart = (unsigned) => { if (unsigned)
+        reportOnce(signedInPartLine(unsigned)); };
+    const heard = (text, result) => {
+        if (disposed || !on)
+            return;
+        if (result.signed) {
+            signedPart(result.unsigned);
+            return;
         }
-        catch (e) { /* noop */ }
-    }
-    else if (!librasOpen) {
+        reportOnce(signingUnavailableLine(result.reason));
+        if (told)
+            return;
+        told = true;
+        const notice = t('sr.deaf.noSigning');
+        tell(notice);
+        caption(`${text} ${notice}`);
+    };
+    /** One request signed: captioned when its turn comes, so the caption and the hands say the same thing; ends when it is heard. */
+    const signOne = (text) => {
+        caption(text);
+        let answer;
         try {
-            window.dispatchEvent(new CustomEvent('vp-widget-close'));
+            answer = interpreter.sign(text);
+        }
+        catch (failure) {
+            answer = Promise.reject(failure);
+        }
+        return answer.then((result) => { heard(text, result); }, (failure) => {
+            heard(text, { signed: false, reason: failure instanceof Error ? failure.message : String(failure) });
+        });
+    };
+    /** The players' requests waiting behind the one being signed, at most one per player, in the order they asked. */
+    const waiting = [];
+    /** Whose request is being signed, when it is a player's; `null` when none is, or when the one being signed named no player. */
+    let seatSigning = null;
+    /** Bumped by every request that takes the line, so one that ends after being overtaken does not sign the next in line. */
+    let line = 0;
+    /** Ends the line: nothing waits and nobody is being signed (the mode went off, or the root went away). */
+    const endLine = () => { line++; waiting.length = 0; seatSigning = null; };
+    const signInTurn = async (seat, text) => {
+        const mine = ++line;
+        for (let next = { seat, text }; next; next = waiting.shift()) {
+            seatSigning = next.seat;
+            await signOne(next.text);
+            if (mine !== line)
+                return; // overtaken: the line is the newer request's now
+        }
+        seatSigning = null;
+    };
+    const toggle = () => {
+        on = !on;
+        store.setBool('incl_libras', on);
+        if (on)
+            told = false;
+        else {
+            endLine();
+            interpreter.hide();
+        }
+        for (const fn of [...changeListeners])
+            fn();
+    };
+    /**
+     * THE INTERPRETER TAKES TURNS, as the narration does (ADR-0234, errata 2026-09-26 — the Dev: «Sim»): a request from ANOTHER
+     * player waits until the one being signed ends — replacing that player's own waiting one, in its place — and a player's newer
+     * request replaces that player's own, at once, the others waiting behind it. A request that names no player takes the line.
+     */
+    const sonar = (text, seat) => {
+        if (!on) {
+            speak(text, seat);
+            return;
+        }
+        if (seat !== undefined && seatSigning !== null && seat !== seatSigning) {
+            const own = waiting.find((w) => w.seat === seat);
+            if (own)
+                own.text = text;
+            else
+                waiting.push({ seat, text });
+            return;
         }
-        catch (e) { /* noop */ }
-    }
-    _onLibrasChange();
-    if (librasOpen)
-        vlibrasSay(t('sr.libras.on'));
+        if (seat === undefined || seatSigning === null)
+            waiting.length = 0;
+        void signInTurn(seat ?? null, text);
+    };
+    return {
+        isOn: () => on,
+        toggle,
+        captionsOn: () => on || captionsSetting(),
+        sonar,
+        onChange: (fn) => { changeListeners.add(fn); return () => { changeListeners.delete(fn); }; },
+        dispose: () => {
+            disposed = true;
+            endLine();
+            interpreter.dispose();
+        },
+    };
 }
-/** Mantido para o laço do jogo, que o chama a cada quadro. Já não decide nada — o estado é nosso. */
-export function vlTick() { _vlOpen = librasOpen; }

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

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+import type { VirtualController } from '../input/virtual-controller.js';
+import { type VoskDeps, type VoskLoad } from '../platform/vosk-runtime.js';
+import { type VoiceListener, type VoiceListenerDeps } from '../platform/voice-listener.js';
+import type { SwitchableControl } from './switchable-control.js';
+/** How long a spoken position stays pressed. The same pulse the scan uses: long enough for a game to see a press and a release. */
+export declare const VOICE_PULSE_MS = 400;
+export interface VoiceControlDeps {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    readonly base: string;
+    /** The child's language (`core/i18n.bcp47`): it chooses the model AND the words. */
+    readonly language: () => string;
+    readonly controller: VirtualController;
+    /** The names the open menu is showing right now, if any (ADR-0194) — `ui/menu-nav.itemNames`. */
+    readonly menuWords: () => readonly string[];
+    /**
+     * Puts the open menu's cursor on the item with this name, WITHOUT activating it — `ui/menu-nav.pointAt`. REQUIRED: it is
+     * what makes a name heard reach its item. `false` when that item is no longer there; then nothing is confirmed.
+     */
+    readonly pointAt: (name: string) => boolean;
+    /**
+     * ONE BUTTON ONLY is on (ADR-0218 §4): whatever the child says is her switch, one press the controller takes as «take the one
+     * shown» — so a name heard is not a place and nothing is pointed at. REQUIRED: without it a name is a cursor move AND a take.
+     */
+    readonly oneButtonOnly: () => boolean;
+    readonly say: (text: string) => void;
+    readonly alert: (text: string) => void;
+    readonly report: (line: string) => void;
+    /** Puts the 👄 back to off when nothing could start. */
+    readonly turnOff: () => void;
+    readonly after: (fn: () => void, ms: number) => void;
+    readonly hasFile: VoskDeps['hasFile'];
+    readonly loadBundle: VoskDeps['loadBundle'];
+    /** The host's `fetch`, handed on to read the loaded model's vocabulary (ADR-0194 §4). Without it an unsayable name goes unreported. */
+    readonly fetch?: VoskDeps['fetch'];
+    readonly getUserMedia: VoiceListenerDeps['getUserMedia'];
+    readonly createContext: VoiceListenerDeps['createContext'];
+    readonly loadRuntime?: (deps: VoskDeps) => Promise<VoskLoad>;
+    readonly listen?: (deps: VoiceListenerDeps) => Promise<VoiceListener>;
+}
+/**
+ * 🎯 THE VOICE IS IN THE FAMILY AND NOT IN THE CAMERA'S CYCLE (ADR-0221 step 7f): it answers the 👄 and not the 📷, and has
+ * one more method. Declaring the family is what makes the compiler see it turns on and off like the other three.
+ */
+export interface VoiceControl extends SwitchableControl {
+    /** The open menu changed: the words it shows join the grammar, or leave it. */
+    refreshGrammar(): void;
+    /**
+     * THE CHILD'S LANGUAGE CHANGED (ADR-0225): the model, the vocabulary and the grammar are chosen again.
+     *
+     * 📌 A listening recogniser is restarted, which costs the model being opened once more; one that is off has nothing to do,
+     * because the next start already reads the new language.
+     */
+    languageChanged(): Promise<void>;
+    /**
+     * LENDS THIS EAR TO A CHOICE AMONG THE GAME'S OPTIONS (ADR-0256): while it is listening in `language`, the grammar becomes
+     * `grammar` and every text heard goes to `onHeard` instead of being obeyed; `stop()` gives the menu's grammar back. `null` when
+     * it is not listening, or listens in another language — then the choice opens an ear of its own.
+     * 📏 Without it every choice paused this recogniser and opened another: two workers and two microphones per press, 40 MiB of
+     * model unpacked each time, measured on 2026-09-27 — and the Dev's machine froze.
+     */
+    borrow(language: string, grammar: readonly string[], onHeard: (text: string, final: boolean) => void): {
+        stop(): Promise<void>;
+    } | null;
+}
+export declare function createVoiceControl(d: VoiceControlDeps): VoiceControl;