@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -1,49 +1,45 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate, Translator } from '../core/i18n.js';
 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';
+import type { PanelShellCtx } from './panel-shell.js';
+import { type TtsPanel, type VoiceSettingsStore } from './voice-settings.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;
-    /**
-     * ESTA MONTAGEM TEM MOTOR NEURAL? (ADR-0094) OPCIONAL, e a ausência vale `true`: um falso de teste
-     * escrito antes deste campo não tem opinião sobre motores neurais, e fazê-lo esconder o Piper mudaria o
-     * que esse teste afirma sem que ninguém tenha escrito a mudança.
-     */
-    neuralDisponivel?: boolean;
-}
+import { type AudioCatDef, type AudioCatState } from './audio-choices.js';
 /**
- * Saída de áudio dedicada de um jogador: o id do dispositivo e o AudioContext/ganho que ele abriu.
+ * A player's dedicated audio output: the device id and the AudioContext/gain it opened.
  *
- * 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ó.
+ * The id is the entity's (a persisted player preference); the `_ac`/`_acOut` pair is `platform/audio-sonar`'s, which
+ * creates them. Hence the intersection instead of three keys in one view.
  */
 export type SinkPlayer = PlayerView<'audioSink'> & PlayerAudioOut;
+/**
+ * THE SETTINGS THIS PANEL READS AND WRITES — the page's settings store, built by the root (ADR-0232 D2c, issue #207): the
+ * voice section's (the spoken index and the speech rate) and the default blind-mode writer. A root passes `core/state`.
+ */
+export interface SettingsAudioSettings extends VoiceSettingsStore {
+    /** Write, persist, notify — used when the host injects no `setBlindMode`. */
+    setBlindModeValue(on: boolean): void;
+}
 export interface SettingsAudioCtx {
+    /**
+     * The root's translator (ADR-0232 D3): its `t`, and the page's language as a BCP-47 tag, which picks the system voices the
+     * list offers. A Pick and not a bare `t`, because the voice list reads the language.
+     */
+    translator: Pick<Translator, 't' | 'bcp47'>;
+    /** The page's settings store (see `SettingsAudioSettings`). REQUIRED (ADR-0232): no module reads it by import. */
+    settings: SettingsAudioSettings;
+    /**
+     * Subscribes to a setting's change and returns the release. REQUIRED, and it is the ROOT'S door (`stateOn` in
+     * `createGame`): a subscription made through it ends with the root's `dispose()` (ADR-0220), where one made on the
+     * page's bus by import went on redrawing the panel of an ended root.
+     */
+    on: (setting: 'blindMode', react: (on: boolean) => void) => () => void;
     /** DOM selector (querySelector), injected — never reaches `document` globally. */
     $: DomQuery;
     /** Screen-reader "polite" announcement (core/a11y-sr's srSay), injected. */
@@ -51,15 +47,38 @@ export interface SettingsAudioCtx {
     /** 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. */
+    /**
+     * Creates an element KEEPING its type — the outputs' `<select>` answers `.value`, the voice list needs `<option>`.
+     *
+     * 📌 Named like its neighbour, `ui/voice-settings`'s `newOption`.
+     */
+    newElement: <K extends keyof HTMLElementTagNameMap>(tag: K) => HTMLElementTagNameMap[K];
+    /** THIS device's speech synthesis. With no voices, `voices` returns an empty list — which is an answer. */
+    speech: {
+        voices: () => readonly SpeechSynthesisVoice[];
+        speakSample: (sample: string, chosen: SpeechSynthesisVoice | null) => void;
+        whenVoicesChange: (again: () => void) => void;
+    };
+    /** This device's audio outputs, and what it can do with them. */
+    audioOutputs: {
+        /** Can this browser LIST outputs? */
+        canList: () => boolean;
+        /** Can this browser ROUTE sound to a chosen output? (It needs an AudioContext.) */
+        canRoute: () => boolean;
+        /** The outputs already known, without asking permission — many come unnamed, which is the browser's design. */
+        list: () => Promise<readonly MediaDeviceInfo[]>;
+        /** Asks permission so the outputs have NAMES, and returns them. */
+        detect: () => Promise<readonly MediaDeviceInfo[]>;
+    };
+    /** Category catalog (platform/audio-mixer.ts's AUDIO_CATS) — pure data, injected. */
     audioCats: readonly AudioCatDef[];
-    /** Shared helper (game.js): toggles a button's .is-on/aria-pressed. Used by many other panels too — not ours. */
+    /** Shared helper (the host's): 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). */
+    /** Shared: current player count, read live from the host. */
     getNumPlayers: () => number;
-    /** Shared: the live players array (core/state.ts) — only `.audioSink`/`._ac`/`._acOut` are touched here. */
+    /** Shared: the live players array — 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. */
+    /** Master mute (platform/audio.ts's soundOn), read/write live. */
     getSoundOn: () => boolean;
     setSoundOn: (on: boolean) => void;
     /** Master volume 0..1 (platform/audio.ts's volume). */
@@ -71,100 +90,64 @@ export interface SettingsAudioCtx {
     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. */
+    /** Blind-mode state (NOT owned by this panel). The toggle's widget lives inside #audio; the state and its gameplay
+     *  side effects belong to the host. */
+    getBlindMode: () => boolean;
+    setBlindMode?: (on: boolean) => void;
+    /** Cane hit spacing. Same reasoning as blind mode. */
     getCaneBlockDiv: () => number;
     setCaneBlockDiv: (div: number) => void;
     /**
-     * Move a prosa das linhas para o rodapé (`ui/settings-panel` → `fillExplain`). Chamado a CADA render.
+     * Moves the rows' prose to the footer (`ui/settings-panel` → `fillExplain`). Called on EVERY render.
      *
-     * ⚠️ NÃO É OPCIONAL POR ELEGÂNCIA: `fillExplain` roda uma vez quando o overlay é frontalizado e move o
-     * `.opt-hint` de dentro de cada linha para o rodapé. Este painel RECONSTRÓI as linhas, e as linhas novas
-     * voltam com a prosa lá dentro — então a explicação aparece duas vezes, no rodapé e sob o rótulo, a
-     * partir do primeiro clique. O `CLAUDE.md` §4 regista exatamente isto, e a issue #109 já o consertou
-     * uma vez noutros painéis.
+     * ⚠️ Relabelling a row puts its `.opt-hint` back inside it — so without this call the explanation appears twice, in
+     * the footer and under the label, from the first click. `CLAUDE.md` §4 records exactly this (issue #109).
      *
-     * Opcional na assinatura porque um consumidor pode montar o painel sem a casca (um teste, o segundo
-     * consumidor): sem casca não há rodapé para duplicar.
+     * Optional in the signature because a consumer can mount the panel without the shell (a test): without the shell
+     * there is no footer to duplicate.
      */
     fillExplain?: (card: HTMLElement | null) => 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. */
+    /** Re-renders the whole #audio overlay content (master, categories, nav-sound, TTS panel, sinks, blind-mode and
+     *  cane-div sync) and re-wires whatever it (re)creates. Idempotent; the host calls it on 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. */
+    /** Refreshes the #opt-modocego button. Exported because the host's blind-mode setter calls it directly. */
+    reflectBlindMode: () => void;
+    /** Refreshes the #opt-tts button, the #tts-vol slider and the #tts-engine selection. */
     reflectTts: () => void;
+    /**
+     * Shows ONE mixer category as the mixer holds it now — its switch and its volume wherever this panel draws them, and the
+     * left-the-default marks — without redrawing anything else. The host calls it for every change the mixer tells
+     * (`Audio.onCatChange`, ADR-0247): a category written by a game, the bar or another panel.
+     */
+    reflectCategory: (cat: string) => 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])[];
 /**
- * Os motores que ESTA MONTAGEM pode de facto oferecer (ADR-0094).
+ * MOUNTS THIS PANEL'S INSIDE — the controls and containers it reaches.
  *
- * ⚠️ Desde que o motor neural passou a chegar por PORTA (`ctx.carregarVozNeural`), «o Piper existe» deixou
- * de ser verdade sobre a engine e passou a ser verdade sobre o JOGO. Oferecer uma opção que não pode
- * funcionar é pior que uma opção a menos: quem a escolhe fica à espera de um download que nunca começa, e
- * quem navega por escuta não tem como ver que não começou.
+ * 🔴 IT IS THE LARGEST INVISIBLE CONTRACT OF THE PANELS: this file looks for `#opt-modocego`, `#cane-div`,
+ * `#opt-menuindex`, `#opt-tts`, `#tts-vol` and more, and nothing in the type says so — which is why it builds them.
  *
- * Só o `piper` é filtrado. `kokoro`/`kitten`/`espeak` também não funcionam hoje — «ainda não entraram» —,
- * mas isso é anterior a este registro e escondê-los aqui mudaria comportamento que ninguém pediu para mudar.
+ * ⚠️ AND EACH ONE'S TAG MATTERS, which makes this the worst place to guess: the voice selects have to be `<select>` — the
+ * panel writes `.value` into them —, the volumes `<input type=range>`, and `#cane-div` is the cycle row `caneRow` builds
+ * (a host's own `<select>` is still read). On a `<button>`,
+ * writing `.value` gives no error at all: it creates a property nobody reads, and the child's choice vanishes silently.
+ *
+ * 📌 THE ORDER IS THE DECISION (ADR-0044 §2), from general to particular (see the composition below).
+ *
+ * ⚠️ `#opt-sound` IS NOT CREATED HERE, deliberately: it is this setting's mirror on the quick bar, outside the panel.
+ * `reflectMaster` reaches it with a guard (`if (sb)`), because a game may have no bar.
+ *
+ * Idempotent: calling it twice reuses what exists instead of duplicating it.
  */
-export declare function opcoesDeMotor(neuralDisponivel: boolean): readonly (readonly [string, string])[];
-export interface VoiceLike {
-    name: string;
-    lang: string;
-}
+export declare function mountAudioInside(t: Translate, ctx: PanelShellCtx, card: HTMLElement, list: HTMLElement): void;
 /**
- * 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.
+ * MOUNTS THE AUDIO PANEL'S INSIDE (ADR-0151 §2 item 4): the general sound — switch and volume — and then the shell's
+ * list with the four taste categories (music, ambience, interaction, earcons).
  *
- * 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.
+ * ⚠️ THE IDS ARE THE ONES `initSettingsAudio` ALREADY LISTENS TO (`#audio-master`, `#audio-master-vol`, `#audio-list`). And
+ * the same order rule: mount BEFORE `init`. Idempotent and relabellable, like its hearing sibling.
  */
-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 mountSoundInside(t: Translate, ctx: PanelShellCtx, card: HTMLElement, list: HTMLElement): void;
 export declare function initSettingsAudio(ctx: SettingsAudioCtx): SettingsAudioApi;