@the-inclusionist/engine 6.36.1

package/dist-pkg/ui/shell.js

@@ -0,0 +1,430 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/shell.ts — A CASCA: em que TELA o jogo está, e o que a tela liga e desliga ao trocar.
+//
+// Este módulo responde a UMA pergunta: "estamos no título, jogando ou pausados — e o que isso significa para o
+// documento?". Ele é o irmão de cima de tudo o que já saiu: game/session.ts decide o que é uma RODADA,
+// render/draw.ts decide o que é um QUADRO, e aqui se decide o que é uma TELA. Nada aqui sabe de física, de
+// moeda ou de pixel; tudo aqui sabe de `hidden`, de foco, de mudo e do menu de pausa.
+//
+// O QUE VEIO, E DE ONDE (bloco "E14: shell — título/splash + pausa" do game.js)
+//  · `setPhase(p)`        — a reação de UI à troca de fase. O VALOR continua em core/state.ts (setPhaseValue);
+//                           o que mora aqui é só a consequência visível.
+//  · `pauseActs`          — a tabela de ações dos `.pm-btn` do menu de pausa (por tela).
+//  · `pauseSelect()`      — põe o 1º item (Continuar) selecionado em cada tela de pausa.
+//  · `printMode()`        — esconde as pausas para ver a tela limpa; qualquer botão volta.
+//  · `togglePause()`      — jogando ⇄ pausado.
+//  · `updateTitleLegend()`— a legenda de dispositivo do splash (2 linhas de "chips": movimento/pausa e os 4
+//                           botões de ação, com o que está CONFIGURADO para o Jogador 1).
+//
+// POR QUE `setPhase` NÃO VIROU UMA MÁQUINA DE ESTADOS COM TABELA DE TRANSIÇÃO — E O QUE VIROU NO LUGAR
+// O pedido do projeto era transformar a sequência de `if`s numa máquina de estados de verdade. Olhei e a
+// resposta honesta é: metade sim, metade não, e a metade que vale não é a que o nome sugere.
+//   · NÃO vale a tabela de transição. São TRÊS estados e as nove transições são todas legais — de qualquer
+//     fase para qualquer fase, sem guarda, sem evento nomeado, sem hook de entrada/saída além do corpo que já
+//     está aqui. Uma `Map<[from,to], handler>` sobre isso não impede nenhum estado ilegal (não existe nenhum),
+//     não descreve nada que o código já não diga, e troca um bloco linear que se lê de cima a baixo por uma
+//     indireção que obriga a saltar. Seria cerimônia sobre três estados. Não fiz.
+//   · VALE, e muito, separar a DECISÃO do EFEITO. Os `if`s do original não são transições: são nove perguntas
+//     diferentes feitas à MESMA fase (`p!=='playing'`, `p!=='title'`, `p!=='paused'`, `p==='paused'`…),
+//     espalhadas no meio de nove escritas no DOM. Isso é uma PROJEÇÃO pura da fase disfarçada de sequência
+//     imperativa. Extraí a projeção — `phaseView(p)` devolve o registro completo do que a fase manda fazer, e
+//     `applyPhaseView` é a única parte que toca o documento. O ganho é concreto e não é estético: a decisão
+//     passa a ser testável no project `node`, sem DOM, sem PIXI e sem áudio, e um erro de sinal num `!==`
+//     (o tipo de erro que aqui deixa a11y quebrada em silêncio: overlay do título visível durante o jogo,
+//     áudio não silenciado na pausa) vira uma asserção em vez de um sintoma que só aparece jogando.
+//     É o mesmo movimento que ui/title.ts já fez com `computeTitleMenuView`, e por isso é o precedente da casa.
+//   · O único pedaço com MEMÓRIA (e portanto o único candidato legítimo a "estado") é a restauração dos
+//     controles de toque, que depende do `dataset.wasOn` gravado na pausa anterior. Esse virou
+//     `touchControlsPlan(...)`, uma função pura de (fase, wasOn, escondido, nº de telas) → (escondido', wasOn').
+//     Ver, logo abaixo, o defeito que essa separação tornou visível.
+//
+// O QUE FICOU DE FORA, E POR QUÊ
+//  · `fpsTick` — a fronteira listava, mas ele não é casca: é instrumentação de HUD (escreve `#hud-fps` e
+//    `#hud-fpsmin`), tem três contadores próprios de módulo e é chamado do laço a cada quadro, não na troca de
+//    tela. Trazê-lo para cá acoplaria o "em que tela estamos" ao "quantos quadros por segundo" sem nenhum
+//    parentesco. O precedente da casa já é esse: ui/layout.ts diz, no cabeçalho, "fpsTick/configureRender
+//    seguem no game.js (outro concern)". Não forcei; segue no game.js, e o lar natural dele, quando chegar a
+//    vez, é ui/hud.ts.
+//  · `padKind()` — NÃO extraí porque JÁ ESTÁ EXTRAÍDO: `input/touch.ts` exporta `padKind()` desde a Onda A,
+//    com o corpo idêntico ao do game.js, e o cabeçalho de lá registra que a cópia é órfã. A que sobrou no
+//    game.js é código morto duplicado (nenhum chamador — ver o relatório). O certo é apagá-la, não mudá-la
+//    de lugar mais uma vez.
+//  · `updateTitleLegend()` — a fronteira deixava em aberto se ela é de shell ou de menu-nav. É de SHELL, e a
+//    razão é simples: ela não navega nada. Não lê foco, não trata tecla, não anda entre itens; ela pinta o
+//    rodapé de UMA tela específica (o título) com a configuração de entrada vigente, e quem a chama é o
+//    próprio `setPhase('title')`. Se morasse em ui/menu-nav, a casca precisaria importar o módulo de
+//    navegação só para desenhar uma legenda, e a dependência apontaria para o lado errado (a casca chamando o
+//    teclado). Ficando aqui, ui/menu-nav não precisa saber que existe uma tela de título.
+//  · O `.pm-btn`/`.pi-btn` (markup e delegação de clique) é de ui/pause-icons.ts, que já os constrói e já
+//    consome esta tabela por `getPauseActs()`. Aqui está só a TABELA, não o botão.
+//  · Abrir/fechar os nove diálogos de configuração é de ui/settings-panel.ts + ui/settings-*.ts. `pauseActs`
+//    apenas os CHAMA, por injeção.
+//
+// INJEÇÃO E ORDEM DE BOOT (a armadilha desta etapa)
+//   · `phase` e `numPlayers` NÃO entram por getter, e isso é de propósito: eles deixaram de ser `let` do
+//     game.js na Fase 2 e hoje são bindings vivos de core/state.ts. Importá-los direto é exatamente o que
+//     game/session.ts e input/touch.ts já fazem — um getter aqui seria uma indireção sobre uma indireção.
+//     Quem AINDA é `let` do game.js entra por getter: `vpPause` (reatribuído por `buildGameHud`) e
+//     `pauseActor` (reatribuído por seis lugares, incluindo o ctx do gamepad).
+//   · TODA entrada de `pauseActs` é um callback, e não um valor, porque `initShell` precisa poder ser chamado
+//     no lugar do bloco E14 (linha ~1373 do game.js) enquanto quase tudo o que a tabela chama — `openTypo`,
+//     `openAudio`, `openMovement`, `openVisual`, `openHelp`, `quitGame`, `fitsN`, `joinPlayer` — são
+//     `function` içadas OU `const` declarados depois (`motor`, `motion`, `empathy`, `hud`, `selVizPlayer`).
+//     Com callbacks, a resolução acontece na CHAMADA (sempre pós-boot) e não na montagem do ctx.
+//   · `setPhase` é chamado de fora por game/session.ts, input/gamepad.ts, game/attract.ts e
+//     ui/activities-menu.ts, todos com o ctx montado ANTES do ponto de extração. Por isso o game.js deve
+//     manter um envelope `function setPhase(p){ shell.setPhase(p); }` — declaração de função, içada — em vez
+//     de trocar as quatro fiações. É o mesmo padrão já usado lá para `hideTouchControls`, `showTouchControls`,
+//     `restartGame`, `fitsN`, `joinPlayer` e `quitGame`.
+//   · O original protegia duas chamadas com `typeof pauseSelect==='function'` / `typeof reflectPauseIcons===
+//     'function'`. Eram guardas de TDZ do tempo do monólito; aqui `pauseSelect` é função local (sempre
+//     definida) e `reflectPauseIcons` é injetada (sempre função). Verifiquei que `reflectPauseIcons` é `const`
+//     declarado no game.js MUITO antes de a primeira pausa acontecer, então as guardas nunca foram falsas em
+//     execução real — removê-las não muda comportamento, só tira ruído. Registrado aqui porque é a única
+//     linha que não é cópia literal.
+//
+// SEM I/O NO IMPORT: o corpo do módulo só declara dados e funções puras. Todo efeito passa por `initShell`.
+// GUARDAS: cada consulta ao DOM passa por guarda de nulo, como manda a casa — é o que permite rodar no project
+// `node` com um `$` falso que devolve `null`.
+//
+// Ver docs/5-Refactoring/plano-modularizacao-mapa.md (C3).
+import { t } from '../core/i18n.js';
+import { PAD_DESIGNS, PAD_GLYPH_SPOKEN } from '../input/devices.js'; // módulo-folha de DADOS (zero deps) — importado, não injetado
+// UMA constante, e não um seletor repetido: com o submenu de opções (ADR-0044, item 5) o cartão de pausa passou
+// a ter DUAS listas, e quem varrer `.pm-btn` cru enxerga também a que está escondida.
+import { PM_ITENS_VISIVEIS } from './pause-icons.js';
+// `FatosDaCena` mora em `core/scenes`, ao lado da pilha que os produz — é tipo de ENGINE, e precisa ser
+// alcançável também por `game/`, que não pode importar de `ui/`. Ver o cabeçalho de lá.
+/** Verbatim das nove perguntas que o `setPhase` do game.js fazia à fase, agora feitas de uma vez só. */
+export function phaseView(f) {
+    return {
+        titleOverlayHidden: !f.telaDeTitulo,
+        pauseOverlayHidden: true,
+        screenPauseHidden: !f.menuDePausa,
+        masterMuted: !f.mundoRodando,
+        hideTouchControls: !f.mundoRodando,
+        pausePressed: f.menuDePausa,
+        focus: f.mundoRodando ? 'game-region' : f.menuDePausa ? 'pause-menu' : 'title-button',
+    };
+}
+/**
+ * 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 function touchControlsPlan(f, st, screens) {
+    if (f.menuDePausa) {
+        if (!st.hidden)
+            return { hidden: true, wasOn: true }; // guarda que estava ligado e esconde
+        return st; // já escondido: nada muda (nem `wasOn`)
+    }
+    if (f.mundoRodando) {
+        return { hidden: st.wasOn && screens <= 1 ? false : st.hidden, wasOn: false };
+    }
+    return { hidden: true, wasOn: false }; // título (ou qualquer cena que não seja jogo nem pausa): some e esquece
+}
+// ---------------------------------------------------------------------------------------------------------
+// LEGENDA DO TÍTULO — a parte pura (montar as duas linhas de chips a partir dos glifos escolhidos)
+// ---------------------------------------------------------------------------------------------------------
+/** Um "chip" da legenda: o glifo (com cor de fundo opcional) seguido da palavra que ele significa. */
+export function chip(txt, col, word) {
+    return `<span class="lg"><span class="lg-ico"${col ? ` style="background:${col}"` : ''}>${txt}</span>${word ? ' ' + word : ''}</span>`;
+}
+/**
+ * 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 function glifoFalado(g) {
+    const k = PAD_GLYPH_SPOKEN[g];
+    return k ? t(k) : g;
+}
+/**
+ * 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 function pauseLegendHtml(sim, nao) {
+    const mudo = (g, palavra) => `<span class="lg" aria-hidden="true"><span class="lg-ico" style="background:${g[1]}">${g[0]}</span> ${palavra}</span>`;
+    const falada = t('menu.legendSpoken', { sim: glifoFalado(sim[0]), nao: glifoFalado(nao[0]) });
+    return mudo(sim, t('menu.yes')) + mudo(nao, t('menu.no')) + `<span class="sr-only">${falada}</span>`;
+}
+/**
+ * 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 function legendRow1(dirTxt, pauseTxt) {
+    return chip(dirTxt, null, t('legend.move')) + chip(pauseTxt, null, t('legend.pause'));
+}
+/**
+ * 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 function legendRow2(g, rotulo) {
+    const ORDEM = ['action2', 'action3', 'action1', 'action4'];
+    return ORDEM.map((a) => {
+        const palavra = rotulo(a);
+        return palavra ? chip(g[a][0], g[a][1], palavra) : '';
+    }).join('');
+}
+/** O innerHTML final de `#title-legend`: duas `.lg-row`. */
+export function legendHtml(l1, l2) {
+    return `<span class="lg-row">${l1}</span><span class="lg-row">${l2}</span>`;
+}
+/**
+ * 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 function padActionGlyphs(layout, custom) {
+    const set = PAD_DESIGNS[layout] || PAD_DESIGNS.generic;
+    // O `typeof b === 'object'` não é cerimônia: o `PadMap` admite `boolean` além de `PadBinding` — é o
+    // sentinela `_skip: true` do assistente de mapeamento. As quatro chaves lidas aqui nunca são ele, então
+    // em execução nada muda; o que muda é que a leitura passa a PERGUNTAR em vez de supor.
+    const bOf = (k, def) => {
+        const b = custom && custom[k];
+        return b && typeof b === 'object' && typeof b.b === 'number' ? String(b.b) : def;
+    };
+    const gy = (k) => set[k] || [k, '#3a4a6a'];
+    return { action2: gy(bOf('action2', '0')), action3: gy(bOf('action3', '1')), action1: gy(bOf('action1', '2')), action4: gy(bOf('action4', '3')) };
+}
+/** Glifos do joystick VIRTUAL (toque): sempre o design 'generic' (0/1/2/3), sem mapa custom. */
+export function touchActionGlyphs() {
+    return padActionGlyphs('generic', null);
+}
+/**
+ * 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 function pickLegendPad(pads, p1pad) {
+    let gp = null;
+    for (const g of pads) {
+        if (!g)
+            continue;
+        if (p1pad >= 0) {
+            if (g.index === p1pad) {
+                gp = g;
+                break;
+            }
+        }
+        else if (!gp)
+            gp = g;
+    }
+    return gp;
+}
+export function initShell(ctx) {
+    /* ===================== a legenda do título ===================== */
+    /** Linha 1+2 quando não há toque nem gamepad: as teclas REALMENTE configuradas do Jogador 1. */
+    function keyboardLegend() {
+        const m = ctx.kbFor(0);
+        const K = (a) => ctx.keyName((m[a] || [])[0] || '?');
+        const l1 = legendRow1(`${K('up')} ${K('left')} ${K('down')} ${K('right')}`, 'Enter');
+        const l2 = legendRow2({ action2: [K('action2'), null], action3: [K('action3'), null], action1: [K('action1'), null], action4: [K('action4'), null] }, ctx.rotuloCurto);
+        return [l1, l2];
+    }
+    function updateTitleLegend() {
+        const el = ctx.$('#title-legend');
+        if (!el)
+            return; // 2 LINHAS, com o que está CONFIGURADO p/ o jogador da tela
+        let l1, l2;
+        if (ctx.isTouchMode()) { // joystick VIRTUAL: 0/1/2/3 + START
+            l1 = legendRow1('✜', 'START');
+            l2 = legendRow2(touchActionGlyphs(), ctx.rotuloCurto);
+        }
+        else {
+            const p0 = ctx.getPlayers()[0];
+            const p1pad = p0 && typeof p0.pad === 'number' && p0.pad >= 0 ? p0.pad : -1;
+            const gp = pickLegendPad(ctx.getGamepads(), p1pad);
+            if (gp) { // joystick FÍSICO: design do modelo + mapa custom do wizard
+                const layout = gp.mapping === 'standard' ? ctx.padLayoutFromId(gp.id) : 'generic';
+                const custom = gp.mapping !== 'standard' ? ctx.padMapFor(gp.id) : null;
+                l1 = legendRow1('✜', 'START');
+                l2 = legendRow2(padActionGlyphs(layout, custom), ctx.rotuloCurto);
+            }
+            else {
+                [l1, l2] = keyboardLegend(); // TECLADO: teclas configuradas (remap respeitado)
+            }
+        }
+        el.innerHTML = legendHtml(l1, l2);
+        const w = ctx.$('#title-wait');
+        if (w)
+            w.hidden = ctx.getNumPlayers() <= 1; // MP: aviso "Aguarde o Jogador 1"
+    }
+    /* ===================== seleção e Print ===================== */
+    function pauseSelect() {
+        ctx.getPauseScreens().forEach((sp) => {
+            const items = [...sp.querySelectorAll(PM_ITENS_VISIVEIS)];
+            items.forEach((b) => b.classList.remove('pm-sel'));
+            if (items[0])
+                items[0].classList.add('pm-sel'); // 1º item (Continuar) selecionado em cada tela
+        });
+    }
+    function printMode() {
+        ctx.getPauseScreens().forEach((sp) => { sp.hidden = true; }); // vê a tela limpa; qualquer botão volta
+        const back = (e) => {
+            if (e && e.preventDefault) {
+                try {
+                    e.preventDefault();
+                }
+                catch { /* noop */ }
+            }
+            ctx.win.removeEventListener('keydown', back, true);
+            ctx.win.removeEventListener('pointerdown', back, true);
+            if (ctx.fatosDaCena().menuDePausa) {
+                ctx.getPauseScreens().forEach((sp) => { sp.hidden = false; });
+                pauseSelect();
+            }
+        };
+        // 80ms de atraso: o próprio evento que ACIONOU o Print não pode ser o que o desfaz.
+        ctx.win.setTimeout(() => {
+            ctx.win.addEventListener('keydown', back, true);
+            ctx.win.addEventListener('pointerdown', back, true);
+        }, 80);
+        ctx.srSay(t('sr.print.on'));
+    }
+    /* ===================== a troca de fase ===================== */
+    /** A metade IMPURA: pega a projeção pronta e a carimba no documento. */
+    function applyPhaseView(v) {
+        const t = ctx.$('#title-overlay'), pa = ctx.$('#pause-overlay');
+        if (t)
+            t.hidden = v.titleOverlayHidden;
+        if (pa)
+            pa.hidden = v.pauseOverlayHidden; // pausa GLOBAL aposentada (Etapa 2): agora é uma por tela
+        ctx.getPauseScreens().forEach((sp) => { sp.hidden = v.screenPauseHidden; });
+    }
+    /** O estado do `#touch-controls` ANTES de qualquer coisa desta troca de fase mexer nele. */
+    function readTouchControls() {
+        const tc = ctx.$('#touch-controls');
+        return tc ? { hidden: tc.hidden, wasOn: tc.dataset.wasOn === '1' } : null;
+    }
+    /** A metade IMPURA do plano de toque: recebe o estado lido ANTES do hide e grava o plano de volta. */
+    function applyTouchControls(f, before) {
+        const tc = ctx.$('#touch-controls');
+        if (!tc || !before)
+            return;
+        const after = touchControlsPlan(f, before, ctx.getNumPlayers());
+        // Só escreve o que MUDOU — é o que torna o applier equivalente linha a linha ao original (que, no ramo
+        // 'paused' já-escondido, não toca em nada; e cujos `delete` nos outros ramos são no-op quando não havia flag).
+        if (after.hidden !== before.hidden)
+            tc.hidden = after.hidden;
+        if (after.wasOn !== before.wasOn) {
+            if (after.wasOn)
+                tc.dataset.wasOn = '1';
+            else
+                delete tc.dataset.wasOn;
+        }
+    }
+    function applyFocus(f) {
+        if (f === 'game-region') {
+            const gr = ctx.$('#game-region');
+            if (gr)
+                gr.focus();
+            return;
+        }
+        if (f === 'pause-menu') {
+            pauseSelect();
+            ctx.reflectPauseIcons();
+            return;
+        }
+        updateTitleLegend();
+        const b = ctx.$('#tm-main button');
+        if (b)
+            b.focus();
+    }
+    /**
+     * Projeta a cena do topo no documento. Chamada pela raiz DEPOIS de ela mexer na pilha — a casca não empilha
+     * nem desempilha, e é essa separação que faz o `Phase` sumir daqui: quem troca de cena sabe os nomes, quem
+     * projeta só precisa dos três fatos.
+     */
+    function aplicarCena() {
+        const f = ctx.fatosDaCena();
+        const v = phaseView(f);
+        // LER ANTES DE ESCONDER. Era aqui o defeito: `hideTouchControls()` roda logo abaixo e já põe `tc.hidden`
+        // em true, então o plano — que rodava depois — via o pad como se ele já estivesse desligado, nunca gravava
+        // o `wasOn`, e o ramo que o traz de volta ao retomar era inalcançável. No celular: pausar sumia com o
+        // direcional e retomar não o devolvia.
+        const antesDoHide = readTouchControls();
+        if (v.hideTouchControls)
+            ctx.hideTouchControls(); // menu ativo (título/pausa) = sem controle virtual
+        // GAG: na pausa, silencia TODO o som do jogo (loops de ambiente/chuva inclusive) — volta ao retomar.
+        ctx.setMasterMuted(v.masterMuted);
+        applyPhaseView(v);
+        applyTouchControls(f, antesDoHide); // o estado é o de ANTES do hide — ver o comentário acima
+        // ORDEM verbatim: o aria-pressed vem DEPOIS do bloco de toque.
+        //
+        // No TÍTULO o atributo SAI, em vez de virar `false`. Ali o botão significa "iniciar", e `aria-pressed`
+        // num botão que não alterna nada faz o leitor de tela anunciar um estado que não existe — pior que não
+        // anunciar nada. `titleOverlayHidden` é verdadeiro fora do título.
+        const pb = ctx.$('#touch-start');
+        if (pb) {
+            if (v.titleOverlayHidden)
+                pb.setAttribute('aria-pressed', String(v.pausePressed));
+            else
+                pb.removeAttribute('aria-pressed');
+        }
+        applyFocus(v.focus);
+    }
+    /* ===================== a tabela do menu de pausa ===================== */
+    // Ações do menu de pausa (compartilhadas pelos menus por tela). Ao abrir um submenu de a11y, escopa ao
+    // jogador que agiu (pauseActor) — o diálogo abre na aba dele.
+    const pauseActs = {
+        resume: () => ctx.retomarJogo(),
+        // O botão ABC era um CICLO de duas posições; virou a porta do menu de CAA (ADR-0028), onde a caixa da
+        // letra é uma escolha entre outras. Ele não sumiu — quem usava o atalho continua a um clique da escolha,
+        // em vez de ter de descobrir onde ela foi parar. A ação `letra` sumiu junto com o ciclo: um nome por coisa.
+        caa: () => ctx.openCaa(),
+        nivel: () => ctx.setQuizLevel(ctx.getQuizLevel() % 5 + 1, true), // L3: cicla 1..5
+        tipo: () => ctx.openTypo(),
+        // R-splash 2: só AUMENTA (nunca diminui); a tela nova ESPERA um botão do jogador entrar
+        addplayer: () => {
+            const n = ctx.getNumPlayers();
+            if (n >= 4) {
+                ctx.srAlert(t('sr.screens.maxPlayers'));
+                return;
+            }
+            if (!ctx.fitsN(n + 1)) {
+                ctx.srAlert(t('sr.screens.wontFitOneMore'));
+                return;
+            }
+            if (!ctx.joinPlayer(null))
+                return;
+            const p = ctx.getPlayers()[ctx.getNumPlayers() - 1];
+            p.waiting = true;
+            ctx.showWaitingBadge(p.i);
+            ctx.retomarJogo();
+            ctx.srAlert(t('sr.player.pressToJoin', { n: p.i + 1 }));
+        },
+        audio: () => ctx.openAudio(),
+        motora: () => { ctx.setMotorPlayer(ctx.getPauseActor()); ctx.openMovement(); },
+        anim: () => { ctx.setMotionPlayer(ctx.getPauseActor()); ctx.openMotion(); },
+        visual: () => { ctx.setSelVizPlayer(ctx.getPauseActor()); ctx.openVisual(); },
+        empatia: () => { ctx.setSelVizPlayer(ctx.getPauseActor()); ctx.openEmpathy(); },
+        print: () => printMode(),
+        quit: () => ctx.quitGame(),
+        ajuda: () => ctx.openHelp(),
+    };
+    return { aplicarCena, pauseSelect, printMode, updateTitleLegend, pauseActs };
+}

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

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { DomQuery } from '../core/dom-query.js';
+/** Minimal DOM-selector shape (matches ui/dom.ts's `$`). */
+export type { DomQuery } from '../core/dom-query.js';
+export type TitleMenuId = 'tm-main' | 'tm-alf' | 'tm-mat' | 'tm-tab' | 'tm-fr' | 'tm-cen';
+/**
+ * The 6 submenus of the title screen, in the order game.js has always hidden/shown them.
+ *
+ * The ORDERED array is the source and the Set is derived from it, not the other way round. A Set carries no
+ * order in its type, so ui/activities-menu - which has to scan the submenus in order to find the visible one -
+ * had declared its own array of the same six ids, kept in step by discipline alone. One list now.
+ */
+export declare const TITLE_MENU_IDS_ORDERED: readonly TitleMenuId[];
+export declare const TITLE_MENU_IDS: ReadonlySet<TitleMenuId>;
+export declare function isTitleMenuId(v: string): v is TitleMenuId;
+export interface TitleCtx {
+    /** DOM selector (querySelector), injected — this module never reaches `document` globally. */
+    $: DomQuery;
+}
+export interface TitleApi {
+    /** Shows `which` and hides the other 5 submenus; toggles legend/title-block; focuses the first button. */
+    show: (which: TitleMenuId) => void;
+}
+export interface TitleMenuView {
+    /** The submenu that becomes visible. */
+    active: TitleMenuId;
+    /** hidden.get(id) === true means that submenu's `hidden` attribute should be set. */
+    hidden: ReadonlyMap<TitleMenuId, boolean>;
+    /** #title-legend is hidden everywhere except tm-main (submenus show their own description footer instead). */
+    legendHidden: boolean;
+    /** .title-block (the game's title art) shows only on tm-main; submenus render their own `.tm-title` heading. */
+    titleBlockDisplay: '' | 'none';
+}
+/** Pure view-model for showTitleMenu(which). Verbatim port of the old function's branching. */
+export declare function computeTitleMenuView(which: TitleMenuId): TitleMenuView;
+export declare function initTitle(ctx: TitleCtx): TitleApi;

package/dist-pkg/ui/title.js

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/title — title-screen submenu NAVIGATION (Estágio 4): extracted from game.js's showTitleMenu(). Shows one
+// submenu (`tm-main`/`tm-alf`/`tm-mat`/`tm-tab`/`tm-fr`/`tm-cen`) and hides the rest, toggles the footer legend
+// (only on `tm-main`) and the game-title block (only on `tm-main` — submenus show their own `.tm-title` instead),
+// then focuses the first button of the now-visible submenu. DI via initTitle(ctx): only `$` (DOM selector,
+// ui/dom.ts shape) is needed — the transition carries no message of its own (callers picked the srSay text
+// per-transition in game.js; duplicating an announcement here would double-speak). Everything else that used to
+// live under "menu inicial" in game.js — building the submenu markup (buildTitleMenus), the footer legend
+// (updateTitleLegend), arrow-key focus traversal (navTitle/titleButtons) and the click/keydown wiring — belongs to
+// other Estágio-4 slices and stays in game.js for now.
+/**
+ * The 6 submenus of the title screen, in the order game.js has always hidden/shown them.
+ *
+ * The ORDERED array is the source and the Set is derived from it, not the other way round. A Set carries no
+ * order in its type, so ui/activities-menu - which has to scan the submenus in order to find the visible one -
+ * had declared its own array of the same six ids, kept in step by discipline alone. One list now.
+ */
+export const TITLE_MENU_IDS_ORDERED = [
+    'tm-main', 'tm-alf', 'tm-mat', 'tm-tab', 'tm-fr', 'tm-cen',
+];
+export const TITLE_MENU_IDS = new Set(TITLE_MENU_IDS_ORDERED);
+export function isTitleMenuId(v) {
+    return TITLE_MENU_IDS.has(v);
+}
+/** Pure view-model for showTitleMenu(which). Verbatim port of the old function's branching. */
+export function computeTitleMenuView(which) {
+    const hidden = new Map();
+    for (const id of TITLE_MENU_IDS)
+        hidden.set(id, id !== which);
+    return {
+        active: which,
+        hidden,
+        legendHidden: which !== 'tm-main',
+        titleBlockDisplay: which === 'tm-main' ? '' : 'none',
+    };
+}
+// ---------------------------------------------------------------------------------------------
+// DOM-facing (thin) — requires `document`/injected ctx
+// ---------------------------------------------------------------------------------------------
+export function initTitle(ctx) {
+    function show(which) {
+        const view = computeTitleMenuView(which);
+        for (const [id, hide] of view.hidden) {
+            const el = ctx.$('#' + id);
+            if (el)
+                el.hidden = hide;
+        }
+        const lg = ctx.$('#title-legend');
+        if (lg)
+            lg.hidden = view.legendHidden;
+        const tb = ctx.$('#title-overlay .title-block');
+        if (tb)
+            tb.style.display = view.titleBlockDisplay;
+        const activeEl = ctx.$('#' + which);
+        const b = activeEl && activeEl.querySelector('button');
+        if (b)
+            b.focus();
+    }
+    return { show };
+}

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

@@ -0,0 +1,11 @@
+// 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;

package/dist-pkg/ui/vlibras.js

@@ -0,0 +1,87 @@
+// 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);
+}
+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();
+        }
+        catch (e) { /* noop */ }
+    }
+    else if (!librasOpen) {
+        try {
+            window.dispatchEvent(new CustomEvent('vp-widget-close'));
+        }
+        catch (e) { /* noop */ }
+    }
+    _onLibrasChange();
+    if (librasOpen)
+        vlibrasSay(t('sr.libras.on'));
+}
+/** 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/webcam.d.ts

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+export declare let eyeMode: boolean;
+export declare function setEyeMode(on: boolean): void;
+export declare function onGaze(data: unknown): void;
+export declare function startEyeControl(): void;
+export declare function stopEyeControl(): void;
+export declare function loadWebGazer(cb?: () => void): void;