@the-inclusionist/engine 6.36.1

package/dist-pkg/ui/reach-notice.js

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * AS FRASES DO AVISO, na ordem em que são lidas. Vazio = não há nada a dizer, e é o caso comum.
+ *
+ * ⚠️ A ÚLTIMA LINHA TEM DUAS FORMAS, e a diferença entre elas é a diferença entre ajudar e mentir:
+ *
+ *   · há transporte que serviria se ligado → «ligue um controle», que é acionável.
+ *   · não há nenhum → dizer «ligue um controle» seria mandar a criança procurar uma coisa que não resolve.
+ *     Nesse caso o problema é do JOGO, que pede mais posições do que qualquer transporte deste aparelho
+ *     oferece, e a frase honesta é outra.
+ */
+export function linhasDoAviso(a, t) {
+    if (a.ok)
+        return [];
+    const nome = (id) => t('reach.nome.' + id);
+    const linhas = [t('reach.titulo', { pedidas: a.pedidas })];
+    for (const c of a.curtos) {
+        linhas.push(t('reach.curto', { transporte: nome(c.id), lugares: c.slots }));
+    }
+    linhas.push(a.serviriamSeLigados.length
+        ? t('reach.ligue', { saida: a.serviriamSeLigados.map(nome).join(t('reach.ou')) })
+        : t('reach.semSaida'));
+    return linhas;
+}
+/** O id do cartão. Estável porque o teste e a folha de estilo o procuram. */
+export const REACH_NOTICE_ID = 'reach-notice';
+/**
+ * Mostra o aviso, se houver o que dizer. Devolve `true` quando mostrou.
+ *
+ * ⚠️ MONTA POR NÓS E NÃO POR `innerHTML`. As frases passam por `t()` e um dicionário é conteúdo que muda sem
+ * passar por revisão de código — é exatamente a fronteira que a issue #106 mapeia. `textContent` fecha a
+ * questão sem precisar de escapar nada.
+ */
+export function mostrarAvisoDeAlcance(ctx, a) {
+    const linhas = linhasDoAviso(a, ctx.t);
+    if (linhas.length === 0)
+        return false;
+    const dentro = ctx.procurar('#game-region');
+    if (!dentro)
+        return false; // sem a marcação do hospedeiro não há onde mostrar; o `problems` já o denuncia
+    const fora = ctx.criar('div');
+    fora.id = REACH_NOTICE_ID;
+    fora.className = 'overlay';
+    const cartao = ctx.criar('div');
+    cartao.className = 'overlay__card';
+    cartao.setAttribute('role', 'dialog');
+    cartao.setAttribute('aria-modal', 'true');
+    cartao.setAttribute('tabindex', '-1');
+    for (const [i, texto] of linhas.entries()) {
+        const p = ctx.criar('p');
+        p.textContent = texto;
+        if (i === 0)
+            p.className = 'reach-notice__titulo';
+        cartao.appendChild(p);
+    }
+    // ⚠️ O BOTÃO É O QUE FAZ DISTO UM AVISO E NÃO UMA PORTA FECHADA. Ver o cabeçalho: a detecção de teclado
+    // erra, e o erro só é aceitável enquanto a criança puder seguir em frente.
+    const seguir = ctx.criar('button');
+    seguir.setAttribute('type', 'button');
+    seguir.className = 'mode-btn';
+    seguir.textContent = ctx.t('reach.continuar');
+    seguir.addEventListener('click', () => fora.remove());
+    cartao.appendChild(seguir);
+    fora.appendChild(cartao);
+    dentro.appendChild(fora);
+    // O foco vai para o cartão, não para o botão: a criança tem de OUVIR o motivo antes de encontrar a saída.
+    // (Se fosse para o botão, o leitor de tela leria «Jogar assim mesmo» e o resto ficaria para quem procurasse.)
+    cartao.focus();
+    ctx.srAlert(linhas.join(' '));
+    return true;
+}

package/dist-pkg/ui/settings-audio.d.ts

@@ -0,0 +1,139 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { PlayerView } from '../core/entity.js';
+import type { PlayerAudioOut } from '../platform/audio-sonar.js';
+import type { DomQuery } from '../core/dom-query.js';
+export type { DomQuery } from '../core/dom-query.js';
+/** Minimal platform/storage.ts shape this module needs (get/set only — no direct localStorage access). */
+export interface AudioStore {
+    get(key: string, fallback?: string | null): string | null;
+    set(key: string, value: string | number | boolean): boolean;
+}
+export interface AudioCatDef {
+    k: string;
+    lbl: string;
+}
+export interface AudioCatState {
+    on: boolean;
+    vol: number;
+}
+export interface TtsPanelEngine {
+    id: string;
+    speak: (text: string) => void;
+}
+/** Minimal shape of the injected `tts` (platform/tts.ts's createTts() instance) this panel drives. */
+export interface TtsPanel {
+    getEngineSel: () => string;
+    setEngineSel: (v: string) => void;
+    getEngine: () => TtsPanelEngine | null;
+    getVoiceObj: () => SpeechSynthesisVoice | null;
+    setVoiceObj: (v: SpeechSynthesisVoice | null) => void;
+    loadTTS: () => void;
+    narrate: (text: string) => void;
+}
+/**
+ * Saída de áudio dedicada de um jogador: o id do dispositivo e o AudioContext/ganho que ele abriu.
+ *
+ * O id é da entidade (é preferência do jogador, persistida); o par `_ac`/`_acOut` é do
+ * `platform/audio-sonar`, que os cria. Daí a intersecção em vez de três chaves numa vista só.
+ */
+export type SinkPlayer = PlayerView<'audioSink'> & PlayerAudioOut;
+export interface SettingsAudioCtx {
+    /** DOM selector (querySelector), injected — never reaches `document` globally. */
+    $: DomQuery;
+    /** Screen-reader "polite" announcement (core/a11y-sr's srSay), injected. */
+    srSay: (msg: string) => void;
+    /** Persistence (platform/storage.ts) — only the TTS engine/voice choice and the per-player audio sink live
+     *  here; the mixer categories persist through `setCatGain` (platform/audio.ts already saves them). */
+    store: AudioStore;
+    /** Category catalog (platform/audio-mixer.ts's AUDIO_CATS) — pure data, injected like game.js's own import. */
+    audioCats: readonly AudioCatDef[];
+    /** Shared helper (game.js): toggles a button's .is-on/aria-pressed. Used by many other panels too — not ours. */
+    toggleBtn: (b: HTMLElement, on: boolean) => void;
+    /** Shared: current player count (core/state.ts's numPlayers, read live via game.js). */
+    getNumPlayers: () => number;
+    /** Shared: the live players array (core/state.ts) — only `.audioSink`/`._ac`/`._acOut` are touched here. */
+    getPlayers: () => SinkPlayer[];
+    /** Master mute (platform/audio.ts's soundOn), read/write live via game.js's re-export. */
+    getSoundOn: () => boolean;
+    setSoundOn: (on: boolean) => void;
+    /** Master volume 0..1 (platform/audio.ts's volume). */
+    getVolume: () => number;
+    setVolume: (v: number) => void;
+    /** The live per-category mixer state (platform/audio.ts's audioCat) — mutated in place, never reassigned. */
+    getAudioCat: () => Record<string, AudioCatState> | null;
+    /** Re-applies a category's gain to the audio graph AND persists it (platform/audio.ts's setCatGain). */
+    setCatGain: (cat: string) => void;
+    /** Narration engine/voice panel API (platform/tts.ts's createTts() instance). */
+    tts: TtsPanel;
+    /** Core collision state (NOT owned by this panel — core/collision.ts reads it via isModoCego). The toggle's
+     *  widget lives inside #audio; the state and its gameplay side effects (setupExtras) stay in game.js. */
+    getModoCego: () => boolean;
+    setModoCego: (on: boolean) => void;
+    /** Core collision state (cane hit spacing). Same reasoning as modo cego. */
+    getCaneBlockDiv: () => number;
+    setCaneBlockDiv: (div: number) => void;
+}
+export interface SettingsAudioApi {
+    /** Re-renders the whole #audio overlay content (master, categories, nav-sound, TTS panel, sinks, modo-cego and
+     *  cane-div sync) and re-wires whatever it (re)creates. Idempotent; game.js's openAudio() calls it every open. */
+    renderAudio: () => void;
+    /** Refreshes the #opt-modocego button. Exported because game.js's setModoCego() calls it directly. */
+    reflectModoCego: () => void;
+    /** Refreshes the #opt-tts button + #tts-engine selection. Exported because the pause-menu icon bar's
+     *  iconAct('tts', …) toggles audioCat.tts.on itself and then calls this. */
+    reflectTts: () => void;
+}
+/** Categorias de NAVEGAÇÃO SONORA (bengala/sonar/guarda/guia) — volume geral separado do som do jogo. */
+export declare const NAV_CATS: readonly ["sonar", "guard", "guide"];
+/** Categorias GERAIS do jogo (TTS fica na seção Voz, fora desta lista). */
+export declare const GEN_CATS: readonly ["music", "ambient", "interact", "earcons", "other"];
+/** 0..1 -> 0..100 rounded (slider display value). */
+export declare function volPercent(v: number): number;
+/** One category row's markup (volume slider + on/off switch). Pure — resolves label/state from the given data,
+ *  never from a global. Returns '' for an unknown/missing category (defensive; never hit with real catalogs). */
+export declare function catRowHTML(k: string, cats: readonly AudioCatDef[], state: Readonly<Record<string, AudioCatState>>): string;
+/** Full innerHTML for a category list (#audio-list or #navsound-list). Pure string building — no DOM. */
+export declare function catsListHTML(keys: readonly string[], cats: readonly AudioCatDef[], state: Readonly<Record<string, AudioCatState>>): string;
+/** #navsound-master's value: the loudest of the nav categories, as a 0..100 slider value. */
+export declare function navMasterVolume(state: Readonly<Record<string, AudioCatState>>, navCats?: readonly string[]): number;
+/** Cane-hit spacing select -> validated int (garbage/empty -> 1, "a batida por bloco"). */
+export declare function parseCaneDiv(raw: string): number;
+/** srSay text for a cane-hit spacing choice. The two halves are ONE sentence per case, not a shared prefix
+ *  plus a tail: a language that renders this as "One tap per block (cane)" needs to move the word "cane". */
+export declare function caneDivMessage(div: number): string;
+/** #tts-engine's option catalog: (value, i18n KEY of the label). The engine NAMES are proper nouns and stay
+ *  put; what translates is the parenthetical that explains each one. Keys, not text — see input/devices. */
+export declare const TTS_ENGINE_OPTIONS: readonly (readonly [string, string])[];
+export interface VoiceLike {
+    name: string;
+    lang: string;
+}
+/**
+ * As vozes do sistema no idioma pedido; sem nenhuma, a lista inteira.
+ *
+ * Chamava-se `pickPtVoices` e filtrava `/^pt/i` fixo, de modo que o jogo em inglês oferecia à pessoa uma
+ * lista de vozes PORTUGUESAS para ler texto em inglês. O nome dizia a verdade sobre o que fazia e mentia
+ * sobre o que devia fazer.
+ *
+ * A comparação é pelo PREFIXO de idioma, não pela etiqueta inteira: quem joga em pt-BR também deve poder
+ * escolher uma voz pt-PT se for a única instalada, e o navegador de uma escola raramente tem a variante
+ * exata. O recuo para a lista inteira fica: uma lista vazia seria pior que uma lista no idioma errado, que
+ * ao menos a pessoa pode ouvir e rejeitar.
+ */
+export declare function pickVoicesFor<T extends VoiceLike>(voices: readonly T[], lang: string): readonly T[];
+/** "<name> (<lang>)" option label. */
+export declare function voiceLabel(v: VoiceLike): string;
+/** Whether the browser can list/switch audio outputs at all (gates the #audio-sinks hint copy). */
+export declare function sinksSupported(hasEnumerateDevices: boolean, hasAudioContextCtor: boolean): boolean;
+export interface SinkDeviceLike {
+    deviceId: string;
+    label?: string;
+}
+/** A device's option label, falling back to a 1-based "Saída N" when the browser withholds the real label
+ *  (no getUserMedia permission granted yet). */
+export declare function sinkOptionLabel(d: SinkDeviceLike, index: number): string;
+/** A player's current sink select value ('' = default/shared). */
+export declare function sinkSelectValue(p: {
+    audioSink?: string | null;
+} | undefined): string;
+export declare function initSettingsAudio(ctx: SettingsAudioCtx): SettingsAudioApi;