@the-inclusionist/engine 6.36.1

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

@@ -0,0 +1,239 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { DomQuery } from '../core/dom-query.js';
+import type { PadMap } from '../input/gamepad.js';
+import type { FatosDaCena } from '../core/scenes.js';
+/** ui/dom.ts `$` — injetado para o teste node poder passar um DOM falso. */
+export type { DomQuery } from '../core/dom-query.js';
+/** O subconjunto de `Window` que `printMode` usa (add/remove de ouvinte em CAPTURA + o adiamento de 80ms). */
+export interface ShellWindow {
+    addEventListener(type: string, fn: (e: Event) => void, capture: boolean): void;
+    removeEventListener(type: string, fn: (e: Event) => void, capture: boolean): void;
+    setTimeout(fn: () => void, ms: number): unknown;
+}
+/** Uma tela de pausa (`.screen-pause`) — só o que a casca toca. */
+export interface PauseScreen {
+    hidden: boolean;
+    querySelectorAll<T extends Element = Element>(sel: string): ArrayLike<T> & Iterable<T>;
+}
+/** Um gamepad, do jeito mínimo que a legenda do título lê. */
+interface PadLike {
+    index: number;
+    id: string;
+    mapping: string;
+}
+/** Para onde o foco vai ao ENTRAR na fase. `null` = ninguém foca nada (não existe hoje; é o default seguro). */
+export type PhaseFocus = 'game-region' | 'pause-menu' | 'title-button';
+/**
+ * O que a fase `p` manda o documento fazer. É a sequência de `if`s do `setPhase` original lida como o que ela
+ * sempre foi: uma projeção da fase. Nenhum campo depende de histórico — o único que dependeria
+ * (`#touch-controls`) mora em `touchControlsPlan`, separado de propósito.
+ */
+export type { FatosDaCena } from '../core/scenes.js';
+export interface PhaseView {
+    /** `#title-overlay`.hidden — o splash só aparece no título. */
+    titleOverlayHidden: boolean;
+    /** `#pause-overlay`.hidden — SEMPRE true. A pausa global foi aposentada na Etapa 2 (agora é uma por tela);
+     *  o elemento continua no index.html e o original o escondia incondicionalmente. Verbatim. */
+    pauseOverlayHidden: true;
+    /** `.screen-pause`.hidden de CADA tela — os menus por tela só aparecem na pausa. */
+    screenPauseHidden: boolean;
+    /** `setMasterMuted(...)` — GAG: fora de 'playing' TODO o som cala (loops de ambiente/chuva inclusive). */
+    masterMuted: boolean;
+    /** `hideTouchControls()` — menu ativo (título/pausa) = sem controle virtual. */
+    hideTouchControls: boolean;
+    /**
+     * `aria-pressed` do botão de pausa — ele diz ao leitor de tela SE está pausado.
+     *
+     * O alvo era `#btn-pause`, e esse id NUNCA existiu no documento: o botão saiu da barra e a fiação ficou
+     * "guardada p/ compat". A linha que escrevia o atributo era morta, e o teste do navegador não pegava porque
+     * o FIXTURE inventava o elemento — um caso que provava que o código escreve num botão que só o teste tem.
+     *
+     * O alvo agora é `#touch-start`, que é o botão que existe, o que o Dev clica e o ÚNICO caminho de pausa num
+     * tablet (não há teclado no Positivo da issue #8).
+     */
+    pausePressed: boolean;
+    /** Quem recebe o foco ao entrar nesta fase. */
+    focus: PhaseFocus;
+}
+/** Verbatim das nove perguntas que o `setPhase` do game.js fazia à fase, agora feitas de uma vez só. */
+export declare function phaseView(f: FatosDaCena): PhaseView;
+/** O estado de `#touch-controls` que interessa: escondido? e havia controle ligado antes da pausa? */
+export interface TouchControlsState {
+    /** `tc.hidden`. */
+    hidden: boolean;
+    /** `tc.dataset.wasOn === '1'`. Ausente/qualquer outro valor = false, como no original. */
+    wasOn: boolean;
+}
+/**
+ * O ÚNICO pedaço de `setPhase` com memória: esconder os controles de toque ao pausar (guardando que estavam
+ * ligados) e devolvê-los ao retomar. Pura, e por isso pinável sem navegador.
+ *
+ * O estado que chega aqui é o de ANTES de `hideTouchControls()` — quem chama lê primeiro e esconde depois.
+ * Já foi o contrário, e o efeito era que `wasOn` nunca era gravado (o plano via o pad como se já estivesse
+ * desligado): pausar no celular sumia com o direcional virtual e retomar não o devolvia.
+ */
+export declare function touchControlsPlan(f: FatosDaCena, st: TouchControlsState, screens: number): TouchControlsState;
+/** Um "chip" da legenda: o glifo (com cor de fundo opcional) seguido da palavra que ele significa. */
+export declare function chip(txt: string, col: string | null, word?: string): string;
+/**
+ * O nome FALADO de um glifo de controle. Glifo que já se lê passa intocado.
+ *
+ * Ver `PAD_GLYPH_SPOKEN` em `input/devices`: a tabela guarda CHAVES e não texto, porque ela é uma `const` de
+ * módulo avaliada uma vez no import — texto já resolvido congelaria o idioma no boot. Quem resolve é aqui, a
+ * cada chamada, com o idioma vigente naquele instante.
+ */
+export declare function glifoFalado(g: string): string;
+/**
+ * A LEGENDA DA PAUSA — duas camadas no mesmo lugar (ADR-0044, item 4).
+ *
+ * Ela dizia qual botão confirma e qual volta, e carregava `aria-hidden="true"` — ou seja, era invisível
+ * justamente para quem não pode ver o glifo. A XAG 106 manda narrar exatamente isto ("A to Select").
+ *
+ * Mas só tirar o atributo devolveria o ruído que provavelmente o motivou: um leitor de tela lê `✕` como
+ * "sinal de multiplicação". Então os CHIPS ficam visíveis e mudos, e ao lado nasce UMA frase só para leitor
+ * de tela, com os glifos já traduzidos em palavra. Duas leituras da mesma informação, cada uma no sentido
+ * que a alcança.
+ *
+ * Recebe os pares `[glifo, cor]` que `simNaoGlyphs` escolhe a partir do desenho do controle — a inversão
+ * PlayStation/Nintendo (onde "sim" é o botão 1) já vem decidida de lá.
+ */
+export declare function pauseLegendHtml(sim: readonly [string, string], nao: readonly [string, string]): string;
+/** Os quatro botões de ação, na ordem fixa da legenda: pular · especial · correr · trocar. */
+export interface ActionGlyphs {
+    action2: readonly [string, string | null];
+    action3: readonly [string, string | null];
+    action1: readonly [string, string | null];
+    action4: readonly [string, string | null];
+}
+/**
+ * Linha 1 da legenda: direcional + START/Enter. Igual para toque e gamepad; o teclado sobrescreve os rótulos.
+ *
+ * As palavras vêm de `legend.*` e são resolvidas AQUI, a cada chamada — não numa tabela de módulo, que
+ * congelaria o idioma no boot. Registro CURTO de propósito: esta fileira fica embaixo de um glifo e não tem
+ * largura para o "Correr / interagir" que a lista de mapeamento usa (ver a nota em pt.ts).
+ */
+export declare function legendRow1(dirTxt: string, pauseTxt: string): string;
+/**
+ * Linha 2 da legenda: os botões de ação, na ordem dos glifos.
+ *
+ * ⚠️ AS PALAVRAS DEIXARAM DE ESTAR AQUI. Esta função dizia `t('legend.jump')`, `t('legend.run')` — o
+ * vocabulário da plataforma dentro de um módulo de engine, e a engine a afirmar que todo jogo tem pular,
+ * especial, correr e trocar, nessa ordem. Agora `rotulo` é perguntado ao jogo (a versão CURTA, ver
+ * `ActionWord.short`), e uma posição que o jogo não nomeia não vira ficha nenhuma.
+ */
+export declare function legendRow2(g: ActionGlyphs, rotulo: (acao: string) => string | null): string;
+/** O innerHTML final de `#title-legend`: duas `.lg-row`. */
+export declare function legendHtml(l1: string, l2: string): string;
+/**
+ * Glifos de um pad FÍSICO. `layout` sai de `padLayoutFromId` (só quando `mapping === 'standard'`; fora do
+ * padrão é sempre 'generic'), e `custom` é o mapa do assistente (só consultado FORA do padrão). Verbatim:
+ * um botão sem entrada no mapa custom cai no índice default ('0'..'3'), e um índice que o design não conhece
+ * vira o par `[índice, '#3a4a6a']` — o cinza de fallback.
+ */
+export declare function padActionGlyphs(layout: string, custom: PadMap | null): ActionGlyphs;
+/** Glifos do joystick VIRTUAL (toque): sempre o design 'generic' (0/1/2/3), sem mapa custom. */
+export declare function touchActionGlyphs(): ActionGlyphs;
+/**
+ * Escolhe QUAL gamepad a legenda descreve: o do Jogador 1, se ele tiver um associado (`players[0].pad`);
+ * senão o primeiro conectado. Verbatim do laço do game.js — inclusive o detalhe de que, com `p1pad >= 0` e
+ * nenhum pad daquele índice presente, o resultado é `null` (a legenda cai no teclado) em vez de pegar outro.
+ */
+export declare function pickLegendPad(pads: readonly (PadLike | null)[], p1pad: number): PadLike | null;
+export interface ShellCtx {
+    /** Os três fatos da cena do TOPO, perguntados a cada uso — a raiz é quem tem a pilha e quem nomeia as
+     *  cenas. Getter, e não valor: a casca projeta o estado ATUAL, não o do momento em que foi ligada. */
+    fatosDaCena: () => FatosDaCena;
+    /** VOLTAR AO JOGO. É o que o "Continuar" do menu de pausa faz, e o que a entrada de um jogador novo faz.
+     *  Era `setPhase('playing')` daqui mesmo — mas empilhar é da raiz, e "retomar" é o que a casca quer dizer. */
+    retomarJogo: () => void;
+    /** 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[];
+    /** ui/dom.ts `$`. Injetado: o módulo nunca alcança `document`. */
+    $: DomQuery;
+    /** `window` — só para os dois ouvintes em CAPTURA do modo Print e o adiamento de 80ms. */
+    win: ShellWindow;
+    /** platform/audio.ts `setMasterMuted` — o nó mestre que cala TUDO na pausa/título (GAG). */
+    setMasterMuted: (muted: boolean) => void;
+    /** core/a11y-sr `srSay` (educado) e `srAlert` (assertivo). */
+    srSay: (msg: string) => void;
+    srAlert: (msg: string) => void;
+    /** `let vpPause` — `buildGameHud` REATRIBUI a array a cada troca de nº de telas. */
+    getPauseScreens: () => PauseScreen[];
+    /** `let pauseActor` — quem abriu o menu; os submenus de a11y escopam no jogador dele. */
+    getPauseActor: () => number;
+    /** input/touch.ts via o envelope içado do game.js: some com o direcional virtual. */
+    hideTouchControls: () => void;
+    /** ui/pause-icons.ts: reflete os `.pi-btn` de todas as telas (estado de a11y). */
+    reflectPauseIcons: () => void;
+    /** Adaptador da Gamepad API — mesmo padrão de input/gamepad.ts (é o que a torna testável sem navegador). */
+    getGamepads: () => readonly (PadLike | null)[];
+    /** `document.body.classList.contains('touch-mode')` — injetado para não alcançar `document`. */
+    isTouchMode: () => boolean;
+    /** input/touch.ts `padLayoutFromId` — id do controle → design de botões. */
+    padLayoutFromId: (id: string) => string;
+    /** input/gamepad.ts `padMapFor` — mapa do assistente para aquele modelo (só usado FORA do padrão). */
+    /** O mapa do controle. `PadMap` vem de `input/gamepad`, que é dono dele — a versão escrita aqui,
+     *  `Record<string, { b?: number }>`, era uma aproximação: perdia o `boolean` que o mapa admite. */
+    padMapFor: (id: string) => PadMap | null;
+    /** input/keyboard-runtime.ts `kbFor(i)` — as teclas CONFIGURADAS do jogador `i` (remap respeitado). */
+    kbFor: (i: number) => Record<string, string[]>;
+    /** ui/settings-controls.ts `keyName` — `KeyboardEvent.code` → rótulo humano. */
+    keyName: (code: string) => string;
+    /**
+     * A palavra CURTA desta posição, na língua do jogo. `null` = o jogo não a usa.
+     *
+     * ⚠️ Curta e não a longa: a legenda põe a palavra debaixo de um glifo, numa fileira de quatro, e não tem
+     * largura para o «Correr / interagir» que a lista de remapeamento usa. A distinção já estava no dicionário
+     * (`legend.*` contra `act.*`) e agora atravessa a fronteira COM as palavras — ver `ActionWord.short`.
+     */
+    rotuloCurto: (acao: string) => string | null;
+    /** `setQuizLevel(n, announce)` — o ciclo 1..5 do nível de alfabetização. */
+    setQuizLevel: (n: number, announce: boolean) => void;
+    /** `quizLevel` de core/state.ts — lido para calcular o próximo do ciclo. */
+    getQuizLevel: () => number;
+    openTypo: () => void;
+    openAudio: () => void;
+    openMovement: () => void;
+    openVisual: () => void;
+    openHelp: () => void;
+    quitGame: () => void;
+    /** game/session.ts: cabe mais uma tela nesta janela? */
+    fitsN: (n: number) => boolean;
+    /** game/session.ts: cria/ativa o jogador seguinte; `null` = sem pad associado ainda. */
+    joinPlayer: (padIdx: number | null) => boolean;
+    /** ui/hud.ts: crachá "aperte um botão para entrar" na tela do jogador novo. */
+    showWaitingBadge: (i: number) => void;
+    /** ui/settings-motor.ts: escopa o painel Movimento no jogador que abriu. */
+    setMotorPlayer: (i: number) => void;
+    /** ui/settings-motion.ts `setSelectedPlayer`: idem para o painel Animação. */
+    setMotionPlayer: (i: number) => void;
+    /** ui/settings-motion.ts `motion.open`. */
+    openMotion: () => void;
+    /** Abre o menu de Comunicação Aumentada e Alternativa (ui/settings-caa). */
+    openCaa: () => void;
+    /** ui/settings-empathy.ts `empathy.open`. */
+    openEmpathy: () => void;
+    /** `let selVizPlayer` do game.js — escopa Visual e Empatia no jogador que abriu. */
+    setSelVizPlayer: (i: number) => void;
+}
+/** A tabela de ações dos `.pm-btn`. Chave = `data-act` do botão (PM_BTNS, de ui/activities-menu.ts). */
+export type PauseActs = Record<string, () => void>;
+export interface ShellApi {
+    /** Projeta no documento a cena que está no topo da pilha AGORA. A raiz chama depois de empilhar/desempilhar.
+     *  (Era `setPhase(p)`: a casca gravava o valor E projetava. Empilhar é da raiz — ela é quem nomeia as cenas.) */
+    aplicarCena: () => void;
+    /** Põe o 1º `.pm-btn` (Continuar) selecionado em CADA tela de pausa. */
+    pauseSelect: () => void;
+    /** Modo Print: esconde as pausas para ver a tela limpa; qualquer tecla/clique as traz de volta. */
+    printMode: () => void;
+    /** Repinta `#title-legend` com o dispositivo e o mapeamento vigentes do Jogador 1. */
+    updateTitleLegend: () => void;
+    /** A tabela de ações do menu de pausa — consumida por ui/pause-icons.ts (`getPauseActs`). */
+    pauseActs: PauseActs;
+}
+export declare function initShell(ctx: ShellCtx): ShellApi;