@the-inclusionist/engine 6.36.1

package/dist-pkg/ui/pause-icons.d.ts

@@ -0,0 +1,327 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { PlayerView } from '../core/entity.js';
+import type { NavKeys } from '../input/edges.js';
+import type { MotionSceneFlags, MotionSceneKey, MotionCharDef } from './settings-motion.js';
+import type { AudioCatState } from './settings-audio.js';
+/**
+ * A LEGENDA de um ícone da barra de acessibilidade — uma função, e não três cópias da mesma expressão.
+ *
+ * Ela é escrita em TRÊS momentos que parecem diferentes e são o mesmo: o cursor direcional pousa no ícone
+ * (`ui/menu-nav`), o dedo o aciona, e o mouse ou o foco passa por cima. Enquanto eram três linhas soltas, o
+ * índice do ADR-0044 teria de ser acrescentado em três lugares — e a chance de um ficar para trás é a mesma
+ * que este repositório já pagou dezesseis vezes com o `DomQuery`.
+ *
+ * O `aria-label` já conta o ESTADO ("Alto contraste, ativado"): é ele que o `reflectIconBtn` reescreve a cada
+ * mudança, e é por isso que a legenda o lê de volta em vez de recompor o texto por conta própria.
+ */
+export declare function legendaDoIcone(barra: ParentNode, el: HTMLElement): string;
+export interface PauseIcon {
+    /** `data-pi` key — the dispatch key of iconAct/iconLabel/reflectIconBtn. */
+    k: string;
+    /** The emoji glyph rendered inside the button. */
+    e: string;
+    /** i18n KEY of the base name; also the `aria-label` when the icon carries no state (or is `soon`). */
+    n: string;
+    /** Under construction: the button announces itself and does nothing else. */
+    soon?: boolean;
+}
+/** The accessibility shortcut bar at the top of every pause screen (and of the splash `#title-icons`).
+ *  Sound-bound icons (blind/TTS) require a private audio output; webcam/voice are still `soon`.
+ *  VERBATIM from game.js in order and behaviour; the names became i18n keys in the Fase-5 pass. */
+export declare const PAUSE_ICONS: readonly PauseIcon[];
+export declare function pauseIcon(k: string): PauseIcon | undefined;
+/** TEA cycle: 0 = normal · 1 = calmo (reduces) · 2 = silencioso (switches off). Never touches TTS/blind mode. */
+export declare const CALM_NAMES: readonly string[];
+/** The audio categories `applyCalm` governs. TTS/sonar/guarda/guia stay untouched — a calm player still needs them. */
+export declare const CALM_AUDIO_CATS: readonly string[];
+/** Colour-vision-deficiency cycle, in `player.viz` values. */
+export declare const CVD_SEQ: readonly string[];
+/** i18n keys of the CVD announcement names, indexed the same as CVD_SEQ.
+ *
+ * ⚠️ POSITION 0 IS `cvd.tricro` AND NOT `cvd.off`, AND THE TWO KEYS ARE NOT INTERCHANGEABLE.
+ * This list names the four CHOICES of the cycle, so position 0 is a way of seeing — trichromatic
+ * vision, the one that needs no correction — and it is said as one. `cvd.off` below is a FALLBACK
+ * for `s.viz` values that are not corrections at all, and 13 of the 16 viz modes are exactly that:
+ * the three simulations, the three contrast levels, the five low-vision modes and blind mode.
+ * Announcing "trichromatic vision" there would have the software assert what the child sees, while
+ * she is simulating not seeing it. The choice is named; the fallback is switched off. */
+export declare const CVD_NAMES: readonly string[];
+/** `player.viz` → i18n key of the label used by iconLabel (anything else falls back to the 'off' key). */
+export declare const CVD_LABELS: Readonly<Record<string, string>>;
+/** The slice of a player object the pause icons touch. `players` (core/state) is typed `unknown[]`. */
+/**
+ * A fatia que os ícones de pausa tocam — derivada de core/entity, e SEM assinatura de índice.
+ *
+ * Havia uma (`[prop: string]: unknown`), posta ali porque `applyCalm` escreve por nome calculado
+ * (`p[c.prop] = …`). Era andaime: `c.prop` tem tipo `MotionCharProp`, que é a união literal
+ * `'rmWalk' | 'rmBreath' | 'rmFlavor'`, e o TypeScript verifica acesso por chave literal sem precisar de
+ * assinatura nenhuma — bastava que os três campos tivessem nome, que é o que a derivação deu.
+ *
+ * E ela custava caro: uma assinatura de índice aceita QUALQUER propriedade, com valor `unknown`. Enquanto
+ * existiu, um erro de digitação em qualquer campo deste objeto compilava em silêncio. Quem a denunciou foi
+ * tipar `core/state.players` como `Player[]`: o compilador recusou converter um `Player` — que não tem
+ * assinatura de índice — para ela, e essa recusa é a informação.
+ */
+export type PausePlayer = PlayerView<'viz' | 'toggleMove' | 'audioSink' | 'rmWalk' | 'rmBreath' | 'rmFlavor'>;
+/** One `.pm-btn` descriptor — the shape of game.js's PM_BTNS (owned by ui/activities-menu). */
+export interface PauseMenuButton {
+    act: string;
+    /** Só é lido quando o botão tem rótulo dinâmico; ver a nota em `PauseBtnDef` (ui/activities-menu). */
+    lbl?: string;
+    /** Dynamic label (the ABC cycle) — rendered from `lbl`, not from i18n, and NOT given `data-i18n`. */
+    letra?: boolean;
+    /** Dynamic label (the literacy level) — rendered from quizLevel + qlName. Currently dormant: no PM_BTNS
+     *  entry sets it, but the branch is live code and is ported verbatim. */
+    nivel?: boolean;
+}
+/** Everything the label/visual of ONE icon depends on, gathered in one value. */
+export interface IconStateSnapshot {
+    modoCego: boolean;
+    ttsOn: boolean;
+    librasOn: boolean;
+    calmMode: number;
+    toggleMove: boolean;
+    /** `player.viz` — shared by the contrast and CVD icons (they overwrite each other; that is by design). */
+    viz: string;
+    /** False disables the blind/TTS icons: those need an audio output nobody else is listening to. */
+    privateOutput: boolean;
+}
+/** A player has private output when nobody else is on the same sink. Single screen ⇒ always private.
+ *  Pure form of game.js's hasPrivateOutput (see the report: it had no other caller left). */
+export declare function hasPrivateOutputIn(list: readonly PausePlayer[], count: number, i: number): boolean;
+/** TEA cycle step. */
+export declare function nextCalmMode(cur: number): number;
+/** Next high-contrast level. An unlisted `viz` (e.g. a CVD filter) is treated as index 0 ⇒ jumps to 'hc-direto'. */
+export declare function nextContrast(cur: string | undefined): string;
+/** Next CVD filter. NOTE the asymmetry with nextContrast: an unlisted `viz` maps to index 1 ('fix-protan'),
+ *  not 0 — verbatim from game.js (`idx = idx<0 ? 1 : (idx+1)%seq.length`). */
+export declare function nextCvd(cur: string | undefined): {
+    idx: number;
+    mode: string;
+};
+/** What `applyCalm` does to ONE audio category, given the TEA level. Extracted so the (destructive) volume
+ *  clamp at level 1 is visible and testable — see the report. */
+export declare function calmAudioPlan(calmMode: number, vol: number): {
+    on: boolean;
+    vol: number;
+};
+/** What `applyCalm` does to the scene/character reduced-motion flags. */
+export declare function calmMotionPlan(calmMode: number): {
+    sceneReduced: boolean;
+    charFrozen: boolean;
+};
+/** The `aria-label` of one icon — it MUST reflect the current state, on/off or level. This is the whole
+ *  point of the function: a toggle that looks pressed but does not say so is invisible to a screen reader. */
+export declare function computeIconLabel(k: string, s: IconStateSnapshot): string;
+/** The visual state of one icon button. `active` is what becomes `aria-pressed`. */
+export interface IconVisual {
+    /** `.pi-on` — the yellow "this is on" state. */
+    on: boolean;
+    /** `.pi-dis` — greyed out (blind/TTS without a private audio output). */
+    dis: boolean;
+    /** `.pi-calm` — TEA level 1 only (white); level 2 uses `.pi-on` instead. */
+    calm: boolean;
+    /** `.pi-cvd-protan` | `.pi-cvd-deuter` | `.pi-cvd-tritan`, or '' — the two-tone background IS the on-signal. */
+    cvd: string;
+    /** aria-pressed: on OR calm OR a CVD tint. */
+    active: boolean;
+}
+/** Pure form of reflectIconBtn's branching. A `soon` icon lands on all-false — it never claims to be on. */
+export declare function computeIconVisual(k: string, s: IconStateSnapshot): IconVisual;
+/** The CSS classes reflectIconBtn clears before applying a fresh visual — in the original order. */
+export declare const ICON_STATE_CLASSES: readonly string[];
+/** One `.pi-btn`. `soon` icons get `.pi-soon` and the "under construction" suffix baked into the aria-label.
+ *  The label is the RESTING one: reflectIconBtn overwrites it with the stateful label as soon as the bar is
+ *  reflected. `ic.n` is an i18n key, so it must be resolved here too — the markup is rendered once at build
+ *  time and would otherwise ship the raw key to a screen reader. */
+export declare function iconBtnMarkup(ic: PauseIcon): string;
+/** The whole icon bar. Used by the pause screen AND by the splash `#title-icons` (which built the same string
+ *  by hand in game.js — that duplication dies with this export). */
+export declare function iconsMarkup(): string;
+/** One `.pm-btn`. Dynamic labels (`letra`/`nivel`) are rendered eagerly and carry NO `data-i18n`, so
+ *  i18n.applyDom() cannot overwrite them. */
+/**
+ * ⚠️ O RÓTULO DINÂMICO ENTRA PRONTO (item 19), e a mudança conserta DUAS coisas de uma vez.
+ *
+ * A linha era `'📚 Nível ' + level + ' · ' + qlName[level]` — e ela tinha dois defeitos que só se enxergam
+ * juntos:
+ *
+ *   1. FRONTEIRA. `level` vinha de `core/state.quizLevel` e `qlName` de uma tabela do jogo. Um menu de pausa
+ *      da ENGINE montava o rótulo de uma atividade de alfabetização — conteúdo pedagógico, não mecânica.
+ *   2. IDIOMA. "Nível" é pt-BR CRU dentro de um módulo de engine. O gate do item 14 vigia o `main.js` e não
+ *      alcança `ui/`, então esta linha atravessou a i18n inteira sem ser vista. Num build em inglês, o menu
+ *      de pausa de uma criança dizia "📚 Nível 2 · …".
+ *
+ * Agora o jogo entrega a frase montada (`dynLabel`), e a engine só a coloca no botão. O jogo é quem sabe o
+ * que é um nível, quem sabe o nome dele e quem sabe em que idioma dizê-lo.
+ */
+export declare function pmBtnMarkup(b: PauseMenuButton, dynLabel: (b: PauseMenuButton) => string | null, tr: (key: string) => string): string;
+/**
+ * Qual das duas listas o cartão de pausa está mostrando.
+ *
+ * DUAS listas no markup, UMA visível — e a escondida carrega `hidden`, que a tira da árvore de acessibilidade
+ * inteira. É o que faz "um menu por tela" (ADR-0044 §5) valer para quem escuta e não só para quem vê, e é o
+ * que permite o anel dar a volta DENTRO da lista visível sem nunca atravessar para a outra.
+ */
+export type PauseSub = 'raiz' | 'opcoes';
+/**
+ * Os itens navegáveis de um cartão de pausa — os da lista VISÍVEL, e só eles.
+ *
+ * Uma constante porque TRÊS módulos a consultam (a navegação em `ui/menu-nav`, a seleção inicial em
+ * `ui/shell` e a troca de submenu aqui). Enquanto fosse `.pm-btn` escrito três vezes, bastaria um deles
+ * esquecer o `:not([hidden])` para o anel atravessar para a lista invisível — e a criança ouviria itens de um
+ * menu que não está na tela.
+ */
+export declare const PM_ITENS_VISIVEIS = ".pause-menu:not([hidden]) .pm-btn";
+/** O innerHTML de UMA `.pause-menu`: a lista, e só ela. */
+export declare function pauseMenuHtml(bs: readonly PauseMenuButton[], sub: PauseSub, dynLabel: (b: PauseMenuButton) => string | null, tr: (key: string) => string): string;
+/**
+ * Troca a lista visível de UM cartão de pausa, e põe o cursor no PRIMEIRO item da lista que entrou.
+ *
+ * Livre (e não um método do `init`) de propósito: `ui/menu-nav` precisa dela para o "não" voltar da lista de
+ * opções à raiz, e não tem acesso às tabelas de botões. Como as duas listas já existem no markup, a troca é
+ * só DOM — nada a re-renderizar, nada a injetar.
+ */
+export declare function mostrarSubmenuDaPausa(sp: HTMLElement, sub: PauseSub): HTMLElement | null;
+/**
+ * A BARRA RÁPIDA DE ACESSIBILIDADE — dez alternadores e a legenda que os explica (ADR-0044, item 7).
+ *
+ * Saiu do cartão de pausa e passou a viver no HUD. O motivo é de uso, não de arrumação: é DURANTE a partida
+ * que uma criança precisa mudar um ajuste que está a atrapalhando, e não depois de pausar. E o motivo
+ * secundário é estrutural — sem ela, o cartão deixa de ter duas zonas e vira uma LISTA, o que é o que
+ * finalmente autoriza o anel (a XAG 106 permite laço para menu linear e o proíbe para grade).
+ *
+ * A LEGENDA VIAJA JUNTO. Ela é a dica que substitui, para quem não vê, o `title` que só o mouse revela;
+ * deixá-la no cartão tornaria a barra do HUD muda.
+ */
+export declare function quickBarMarkup(): string;
+/**
+ * O QUE UMA INTENÇÃO SIGNIFICA DENTRO DO MODO `accessibility` (ADR-0044, item 7).
+ *
+ * O registro listou este modo entre as consequências NEGATIVAS da decisão, e disse por quê: "um modo em que
+ * se entra e não se sabe sair é a própria armadilha de que este registro trata — então a saída dele (START ou
+ * VOLTAR) é parte da decisão, e não um detalhe de implementação".
+ *
+ * Daí a forma desta função: SAIR vem primeiro, e vem por DUAS portas. Não é redundância. VOLTAR é a saída de
+ * tudo no jogo, e é o que quem já o conhece tenta primeiro; START é o botão que ABRE a pausa, e a pausa é de
+ * onde se entrou aqui — quem se perde tenta voltar por onde veio. Ter só uma das duas seria apostar que a
+ * criança adivinhe qual delas foi escolhida.
+ *
+ * E a precedência é decisão também: um controle registra mais de uma borda no mesmo quadro (dedos apertam
+ * junto), e nesse quadro `sair` não pode ficar atrás de `ativar`.
+ */
+export type AcaoNaBarra = 'sair' | 'ativar' | 'andar' | 'nada';
+export declare function acaoNaBarra(k: NavKeys, temStart: boolean): AcaoNaBarra;
+export interface ScreenPauseMarkupOpts {
+    /** Screen/player index (0-based); the dialog label and the "· Jogador N" suffix are 1-based. */
+    player: number;
+    /** Live player count — the suffix only appears in multiplayer. */
+    numPlayers: number;
+    /** A lista RAIZ: os sete itens do ADR-0044, `resume` primeiro e `quit` último. */
+    pmButtons: readonly PauseMenuButton[];
+    /** O submenu de opções: os sete painéis de ajuste, com o "Voltar" na frente. */
+    optionsButtons: readonly PauseMenuButton[];
+    /** Rótulo pronto de um botão DINÂMICO, ou `null` se aquele botão não tem um. Quem monta a frase é o jogo. */
+    dynLabel: (b: PauseMenuButton) => string | null;
+    t: (key: string) => string;
+}
+/** The full innerHTML of a `.screen-pause`. Pure — every input is a parameter. */
+export declare function screenPauseMarkup(o: ScreenPauseMarkupOpts): string;
+export interface PauseIconsCtx {
+    /** Quantos jogadores/telas. Estado de RODADA (ADR-0038): vem da instância que a raiz possui.
+     *  Era `numPlayers`, um `let` de `core/state` importado como binding vivo — e um `let` de módulo
+     *  é compartilhado por qualquer segundo jogo que a mesma página carregue (D13 do `demos`). */
+    getNumPlayers: () => number;
+    /** Os jogadores. Estado de RODADA, pelo mesmo motivo. `readonly unknown[]` porque cada consumidor
+     *  estreita para a SUA fatia — o tipo real é do jogo, não da engine (ADR-0033). */
+    getPlayers: () => readonly unknown[];
+    /** aria-live "polite" — every successful toggle announces its NEW state. */
+    srSay: (text: string) => void;
+    /** aria-live "assertive" — the two refusals (`soon` icon, shared audio output). */
+    srAlert: (text: string) => void;
+    /**
+     * As BARRAS RÁPIDAS por tela (`.screen-a11y`), na ordem dos jogadores.
+     *
+     * Existe pelo mesmo motivo de `getPauseScreens`: `buildGameHud` REATRIBUI a array a cada remontagem, então
+     * o que se injeta é o getter e não a array. E existe separada da pausa porque, desde o item 7, a barra não
+     * mora mais dentro dela — o daltonismo é POR JOGADOR, e refletir os ícones exige achar a barra daquela tela.
+     */
+    getA11yBars: () => readonly HTMLElement[];
+    /** PM_OPTIONS_BTNS — o submenu de opções. Mesma dona, mesmo motivo: ninguém tem duas cópias de uma lista. */
+    optionsButtons: readonly PauseMenuButton[];
+    /** PM_BTNS — the `.pm-btn` list. Owned by ui/activities-menu; injected, never copied. */
+    pmButtons: readonly PauseMenuButton[];
+    /** QL_NAME — literacy-level names, for the (dormant) `nivel` button. Same owner as pmButtons. */
+    /**
+     * O RÓTULO de um botão dinâmico, pronto — ou `null` quando aquele botão não tem um (item 19).
+     *
+     * Era `quizLevel` (importado de `core/state`) mais `qlName` (tabela do jogo), e este módulo montava a
+     * frase. Um menu de pausa da ENGINE não sabe o que é nível de alfabetização, nem em que idioma dizê-lo.
+     * Função e não valor, porque o rótulo muda em execução — de nível E de idioma.
+     */
+    dynLabel: (b: PauseMenuButton) => string | null;
+    /** The `.pm-btn` action table. LAZY: `pauseActs` is a `const` declared far below the init site in game.js. */
+    getPauseActs: () => Record<string, (() => void) | undefined>;
+    /** Records which player opened the menu. `pauseActor` itself stays in game.js — the gamepad, the keyboard
+     *  router, openHelp() and openOptions() all read it there. */
+    setPauseActor: (i: number) => void;
+    /** The live `vpPause` array (game.js rebuilds it on every buildGameHud). Getter, not the array. */
+    getPauseScreens: () => readonly Element[];
+    getModoCego: () => boolean;
+    setModoCego: (on: boolean) => void;
+    /**
+     * O mixer por categoria. NULO até `initAudioMixer()` — `platform/audio` o declara
+     * `Record<string, CatState> | null` porque o import dele é PURO (não lê localStorage), e quem inicializa
+     * é o boot do consumidor. Este ctx pedia não-nulo, o que era uma promessa que a fonte não faz.
+     */
+    getAudioCat: () => Record<string, AudioCatState> | null;
+    /** Re-applies a category's gain node after `on`/`vol` changed. */
+    setCatGain: (k: string) => void;
+    /** Repaints the TTS row of the auditory panel. See BUG #1 in the report: in game.js this call is behind a
+     *  `typeof reflectTTS==='function'` guard on a symbol that no longer exists, so it never fires. The guard is
+     *  ported verbatim as `reflectTtsPanelEnabled` below rather than silently fixed. */
+    reflectTtsPanel: () => void;
+    /** Verbatim port of game.js's dead guard: `typeof reflectTTS === 'function'`. Pass `false` to preserve
+     *  today's behaviour (the panel is NOT refreshed), `true` to restore the intended call. */
+    reflectTtsPanelEnabled: boolean;
+    isLibrasOn: () => boolean;
+    toggleLibras: () => void;
+    rm: MotionSceneFlags;
+    rmKeys: readonly MotionSceneKey[];
+    rmChar: readonly MotionCharDef[];
+    saveRM: () => void;
+    setToggleMove: (i: number, on: boolean) => void;
+    setPlayerViz: (i: number, mode: string) => void;
+}
+export interface PauseIconsApi {
+    /** Builds one `.screen-pause` (hidden), wired for click + hover/focus caption. Caller appends it. */
+    buildScreenPause: (i: number) => HTMLElement;
+    /** Monta a BARRA RÁPIDA (`.screen-a11y`) da tela `i`, já fiada. Chamada por ui/hud.ts, uma por tela. */
+    buildQuickBar: (i: number) => HTMLElement;
+    /** ENTRA no modo `accessibility` da tela `i` — é o que o item `acessibilidade` da pausa faz. */
+    entrarNaBarra: (i: number) => void;
+    /** SAI do modo e devolve o direcional ao personagem. */
+    sairDaBarra: (i: number) => void;
+    /** A tela `i` está com o direcional na BARRA em vez de no personagem? Perguntado a cada quadro. */
+    naBarraDe: (i: number) => boolean;
+    /** Um passo dentro do modo. `temStart` é a borda do botão de pausa — a segunda saída (ADR-0044, item 7). */
+    navBar: (i: number, k: NavKeys, temStart?: boolean) => void;
+    /** Runs the icon `k` for screen `i`. Does NOT reflect — callers reflect after, as game.js always did. */
+    iconAct: (k: string, i: number) => void;
+    /** The state-reflecting `aria-label` of icon `k` for screen `i`. */
+    iconLabel: (k: string, i: number) => string;
+    /** Applies classes + aria-pressed + aria-label to ONE `.pi-btn`. */
+    reflectIconBtn: (b: HTMLElement, i: number) => void;
+    /** Reflects every `.pi-btn` inside `root` in screen `i`'s scope. `#title-icons` uses i=0 (splash = J1). */
+    reflectIconsIn: (root: ParentNode | null, i: number) => void;
+    /** Reflects every pause screen (each in its own player's scope). */
+    reflectPauseIcons: () => void;
+    /** Applies the current TEA level to scene motion, character motion and the five audio categories. */
+    applyCalm: () => void;
+    getCalmMode: () => number;
+    /** Sets the TEA level WITHOUT applying it (applyCalm is the apply step) — for tests and future restore. */
+    setCalmMode: (n: number) => void;
+    /** Snapshot of everything the label/visual of screen `i` depends on. Exposed for tests and debugging. */
+    iconState: (i: number) => IconStateSnapshot;
+}
+export declare function initPauseIcons(ctx: PauseIconsCtx): PauseIconsApi;