@the-inclusionist/engine 6.36.1

package/dist-pkg/ui/layout.js

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/layout.ts — ESCALA do jogo (Estágio 4, Tier 1). Trava o #game-region num múltiplo inteiro de PIXELS REAIS
+// de 320×180 (por jogador) e reescala as vars de UI escopadas ao canvas. Deps: ui/dom ($), core/screens,
+// render/crt (crtScanVars). A contagem de jogadores entra por `initLayout`. fpsTick/configureRender seguem no main.js.
+//
+// JÁ NÃO RESERVA ESPAÇO PARA O INTÉRPRETE. Reservava 380px à direita quando o painel do VLibras "abria", e o
+// jogo deslocava para a esquerda — decisão revista pelo Dev: o intérprete deve aparecer NA FRENTE da tela
+// enquanto um áudio toca, e sumir. E a reserva estava sendo aplicada O TEMPO TODO, porque o detector de
+// "aberto" lia um div vazio (ver o cabeçalho de ui/vlibras): o canvas vivia em `left: -136`, fora da tela,
+// com ou sem modo pessoa surda. O acoplamento vlibras↔layout desaparece junto.
+import { $ } from './dom.js';
+import { screenBaseSize } from '../core/screens.js';
+import { crtScanVars } from '../render/crt.js';
+// A CONTAGEM DE JOGADORES entra por injeção desde 2026-08-26. 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`, ADR-0038). O que entra aqui é o GETTER da rodada que a raiz
+// possui; o `let` que sobra guarda a função, não o número.
+let _numJogadores = () => 1;
+/** Liga a contagem de jogadores. Chamado uma vez pela raiz, antes do primeiro `layout()`. */
+export function initLayout(deps) { _numJogadores = deps.numJogadores; }
+export function layout() {
+    const wrap = $('#stage-wrap');
+    if (!wrap)
+        return;
+    wrap.style.paddingRight = '0px';
+    const availW = wrap.clientWidth || 320;
+    const availH = wrap.clientHeight || 180;
+    // E11: a grade de telas define a base (1=320×180, 2=640×180, 3-4=640×360)
+    const n = _numJogadores();
+    // (`screenGrid(n)` SAIU em 2026-08-26: `cols`/`rows` eram desestruturados e nunca lidos — a escala sai de
+    //  `screenBaseSize`, logo abaixo. Era uma chamada paga a cada `layout()` por nada. `noUnusedLocals` achou.)
+    const { w: baseW, h: baseH } = screenBaseSize(n);
+    // Piso k=2: CADA viewport tem no mínimo 640×360. Assim 2×2 = 1280×720 cabe num Chromebook do governo (1366×768).
+    const MIN_K = 2;
+    // ADR-001 (CORRIGIDO 2026-07-04): ESCALA travada em PIXELS REAIS INTEIROS. Cada pixel de arte = kDev pixels
+    // FÍSICOS (inteiro) → scanlines SEMPRE regulares e arte uniforme em QUALQUER dpr. Tolera ≤5px lógicos de corte
+    // por lado (o −10): base·kDev − avail·dpr ≤ 10·kDev ⇒ kDev ≤ avail·dpr/(base−10). (José escolheu inteiro-REAL.)
+    const dpr = window.devicePixelRatio || 1;
+    const kDev = Math.max(Math.round(MIN_K * dpr), Math.floor(Math.min(availW * dpr / (baseW - 10), availH * dpr / (baseH - 10))));
+    const k = kDev / dpr; // fator LÓGICO/CSS (kDev = fator em pixels REAIS, inteiro)
+    // ESCALA das vars de UI é ESCOPADA ao #game-region: só a UI DENTRO do canvas (menus/HUD/pausa/quiz) escala com o
+    // k. Fora do canvas (barra de topo, painel de debug) herda o :root → texto SEMPRE 16px, toque 44px (José).
+    const gr = $('#game-region');
+    if (gr) {
+        gr.style.width = (baseW * k) + 'px';
+        gr.style.height = (baseH * k) + 'px';
+        gr.style.setProperty('--hud-fs', Math.max(9, Math.round(180 * k * 0.052)) + 'px');
+        gr.style.setProperty('--ui-fs', (8 * k) + 'px'); // base LÓGICA 8px × k (16px em k=2)
+        gr.style.setProperty('--tap', (22 * k) + 'px'); // toque 22px × k (44px em k=2, piso WCAG)
+    }
+    crtScanVars(); // scanlines re-alinham quando a escala k muda
+    if (/[?&]debug=true/.test(location.search))
+        console.info(`[escala] kDev=${kDev}× px REAIS (canvas físico ${baseW * kDev}×${baseH * kDev} = múltiplo INTEIRO de ${baseW}×${baseH}); CSS ${Math.round(baseW * k)}×${Math.round(baseH * k)} (k=${k.toFixed(3)}, dpr=${dpr})`);
+}

package/dist-pkg/ui/loop-crash.d.ts

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+export interface AvisoDeQuedaCtx {
+    /** `querySelector` do documento deste jogo. Injetado: a engine recebe o dela, `main.ts` passa o `$` global. */
+    procurar: (sel: string) => HTMLElement | null;
+    /** A narração falada, quando o jogo tiver uma. Ausente = o aviso escrito basta. */
+    narrar?: (texto: string) => void;
+}
+/**
+ * Monta o `aoFalhar` para entrar em `startLoop(ticker, quadro, maxDt, { aoFalhar })`.
+ *
+ * A ORDEM DOS CANAIS É DELIBERADA e vale escrever: o console PRIMEIRO, porque quem depura não pode perder o
+ * erro se o DOM estiver quebrado — e um DOM quebrado é um dos motivos plausíveis para o quadro ter lançado.
+ * Depois o leitor de tela, que é quem não tem outra pista nenhuma. O visível por último, porque quem o vê já
+ * viu a tela parar.
+ *
+ * Cada canal é isolado do seguinte: se a narração lançar, o aviso escrito já saiu. Um aviso que falha pela
+ * metade tem de entregar a outra metade — é a mesma regra que o `startLoop` aplica a este próprio callback.
+ */
+export declare function criarAvisoDeQueda(ctx: AvisoDeQuedaCtx): (erro: unknown) => void;

package/dist-pkg/ui/loop-crash.js

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/loop-crash.ts — O ANÚNCIO DE QUE O LAÇO PAROU. A outra metade do ADR-0054.
+//
+// `core/loop.startLoop` já PARA quando um quadro lança, e já chama `aoFalhar`. O que faltava era alguém que
+// passasse um `aoFalhar` — e a `confirmation` do ADR-0054 diz isso por escrito: *"a raiz de composição ainda
+// não liga o `aoFalhar`, então hoje o laço para em silêncio... enquanto isto não existir este registro é só
+// metade verdadeiro."*
+//
+// ⚠️ E A METADE QUE FALTAVA É A QUE IMPORTA. Tela congelada é sintoma VISUAL. No modo cego, um jogo parado e
+// um jogo pensando produzem a mesma coisa: silêncio. A criança fica a esperar por um jogo que já morreu, sem
+// nada que lhe diga para recarregar — e o único aviso que existia era um erro no console, que ela não lê.
+//
+// ⚠️ POR QUE UM MÓDULO E NÃO UMA LINHA DENTRO DE `createGame`. Porque o jogo de plataforma NÃO PASSA POR
+// `createGame` — `main.ts` monta a engine à mão, e é ele quem chama `startLoop`. Uma solução que vivesse só
+// na raiz de composição da engine deixaria de fora exatamente o jogo que existe. As duas raízes importam
+// daqui.
+//
+// ⚠️ E NÃO USA `srAlert` DE `core/a11y-sr`, o que é uma escolha e não um esquecimento:
+//
+//   · `srAlert` limpa, espera um `requestAnimationFrame` e só então escreve. Essa dança existe para forçar o
+//     leitor a REANUNCIAR texto repetido; uma queda é anunciada uma vez e nunca se repete, então não compra
+//     nada aqui — e faz o aviso depender de um quadro futuro, no instante em que os quadros pararam.
+//   · `srAlert` busca no documento GLOBAL. Quem recebe o documento por injeção (a engine, um teste, um
+//     segundo jogo na mesma página) perderia o aviso. O anúncio de que tudo parou é o último lugar que
+//     deveria depender de uma busca global.
+import { t } from '../core/i18n.js';
+/**
+ * Monta o `aoFalhar` para entrar em `startLoop(ticker, quadro, maxDt, { aoFalhar })`.
+ *
+ * A ORDEM DOS CANAIS É DELIBERADA e vale escrever: o console PRIMEIRO, porque quem depura não pode perder o
+ * erro se o DOM estiver quebrado — e um DOM quebrado é um dos motivos plausíveis para o quadro ter lançado.
+ * Depois o leitor de tela, que é quem não tem outra pista nenhuma. O visível por último, porque quem o vê já
+ * viu a tela parar.
+ *
+ * Cada canal é isolado do seguinte: se a narração lançar, o aviso escrito já saiu. Um aviso que falha pela
+ * metade tem de entregar a outra metade — é a mesma regra que o `startLoop` aplica a este próprio callback.
+ */
+export function criarAvisoDeQueda(ctx) {
+    return (erro) => {
+        try {
+            console.error('[inclusionist] the frame threw; the loop stopped.', erro);
+        }
+        catch { /* noop */ }
+        const msg = t('sr.laco.parou');
+        // O leitor de tela: assertivo, porque interromper é justamente o ponto.
+        const alerta = ctx.procurar('#sr-alert');
+        if (alerta)
+            alerta.textContent = msg;
+        try {
+            ctx.narrar?.(msg);
+        }
+        catch { /* noop: a narração falhou; o aviso escrito já saiu */ }
+        // O VISÍVEL. O texto entra no ATRIBUTO e a folha de estilo o mostra com `content: attr(...)` — é o que
+        // mantém a frase LOCALIZADA. Um aviso cravado no CSS estaria em inglês para uma criança brasileira, que
+        // é o defeito que o pilar 3 existe para impedir.
+        const regiao = ctx.procurar('#game-region');
+        if (regiao)
+            regiao.setAttribute('data-incl-parou', msg);
+    };
+}

package/dist-pkg/ui/map-hub.d.ts

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { DomQuery } from '../core/dom-query.js';
+/** Assinatura mínima do seletor de DOM (a mesma de `ui/dom.ts`). */
+export type { DomQuery } from '../core/dom-query.js';
+/** Qual painel a linha abre. `null` = ainda não existe subsistema para abrir. */
+export type MapHubAction = 'options' | 'padwiz' | null;
+/** Uma linha do painel. */
+export interface MapHubRow {
+    /** Rótulo com o emoji na frente — o emoji é o que `soonMessage` corta para falar. */
+    lbl: string;
+    /** Nº de telas exigido; `undefined` = vale em qualquer modo. */
+    mode?: number;
+    /** Em construção: aparece cinza, com "Em breve" no botão. */
+    soon?: boolean;
+    /** O painel que o botão abre, por nome. */
+    act?: MapHubAction;
+}
+/**
+ * A TABELA — congelada. A ordem é a da tela: os quatro modos de teclado, o gamepad, e as três promessas.
+ * As três últimas são o roadmap deste jogo (webcam e fala), e é por causa delas que o módulo não é engine.
+ */
+export declare const MAP_HUB_ROWS: readonly MapHubRow[];
+/** O estado visual de uma linha, para o número de telas atual. */
+export interface MapHubRowState {
+    /** A linha exige um modo diferente do atual. */
+    off: boolean;
+    /** A linha está cinza (em construção OU modo errado) — é o que vira `row-off` + `disabled`. */
+    dis: boolean;
+}
+/** O estado de cada linha em `np` telas. Fonte única do markup e das duas mensagens de `srAlert`. */
+export declare function mapHubStates(np: number, rows?: readonly MapHubRow[]): MapHubRowState[];
+/** O HTML do painel inteiro — cabeçalho + uma `.ctrl-row` por linha. */
+export declare function mapHubMarkup(np: number, rows?: readonly MapHubRow[]): string;
+/** O rótulo sem o emoji da frente — "👁 Mapear olhos e boca" → "Mapear olhos e boca". */
+export declare function soonName(lbl: string): string;
+/** O aviso falado de uma linha em construção. */
+export declare function soonMessage(lbl: string): string;
+/** O aviso falado de uma linha cujo modo não é o número de telas atual. */
+export declare function wrongModeMessage(mode: number): string;
+export interface MapHubCtx {
+    /** Seletor de DOM injetado (`ui/dom.ts:$`) — o módulo nunca alcança `document` sozinho. */
+    $: DomQuery;
+    /** Anúncio assertivo ao leitor de tela (`core/a11y-sr.ts:srAlert`). */
+    srAlert: (msg: string) => void;
+    /** Nº de telas vivo (`core/state.ts:numPlayers`) — GETTER, porque é reatribuído. */
+    getNumPlayers: () => number;
+    /** Abre o painel de remapeamento de teclado (`openOptions` do main.js). */
+    openOptions: () => void;
+    /** Abre o assistente de gamepad (`input/gamepad.ts:openPadWiz`). */
+    openPadWiz: () => void;
+}
+export interface MapHubApi {
+    /** Redesenha `#map-hub` e reamarra os botões. Chamado por `openMovement`, a cada abertura do menu. */
+    render(): void;
+}
+export declare function initMapHub(ctx: MapHubCtx): MapHubApi;

package/dist-pkg/ui/map-hub.js

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/map-hub — O PAINEL "MAPEAR CONTROLES", dentro do menu de Movimento.
+//
+// Este módulo é o antigo `renderMapHub()` do main.js (mais o seu ajudante `mapSoon`, que não tinha outro
+// chamador). Ele desenha a lista de formas de comandar o jogo — teclado (uma linha por modo de 1 a 4 telas),
+// gamepad, e três entradas ainda por construir (olhos e boca, setores de olhar, palavras faladas) — e amarra
+// o botão de cada linha ao painel que ela abre.
+//
+// ======================= É DESTE JOGO, E NÃO ENGINE =======================
+// Um segundo jogo da coleção NÃO reusaria este arquivo, e a razão não é o assunto (mapear controles é
+// universal) — é o CONTEÚDO. Este painel enumera exatamente os subsistemas de entrada que *The Inclusionist*
+// tem hoje e os que ele PROMETE ter: a redação "em construção — chega junto com os subsistemas de webcam e
+// fala" é uma declaração de roadmap deste jogo, não uma capacidade do engine. Ele também depende do `#map-hub`
+// deste `index.html`, das classes `ctrl-row`/`mode-btn`/`row-off` desta folha de estilo, e de dois painéis
+// concretos (`openOptions`, `openPadWiz`). O que É engine já está extraído e mora noutro lugar:
+// `input/keyboard.ts` (o esquema), `input/gamepad.ts` (o assistente de mapeamento), `core/screens.ts` (a
+// grade). Aqui sobra a VITRINE — e vitrine é do jogo. Daí `ui/`, ao lado de `ui/settings-motor.ts`, que é o
+// resto do mesmo menu de Movimento.
+//
+// ======================= DECIDIR ≠ EXECUTAR =======================
+// Três coisas eram uma só, e as duas primeiras são puras:
+//   · `MAP_HUB_ROWS` — a TABELA. Rótulo, modo exigido (ou nenhum) e a ação nomeada (`'options'`, `'padwiz'`
+//     ou nada, para as três em construção). A ação virou um NOME e não uma função: é o que permite a tabela
+//     ser um dado congelado, testável, e o `init` decidir qual painel cada nome abre.
+//   · `mapHubStates(np)` / `mapHubMarkup(np)` — o estado de cada linha (desabilitada por estar em construção,
+//     ou por o modo dela não ser o número de telas atual) e o HTML que sai disso. A regra que importa e que
+//     ninguém via no meio da interpolação: "⌨ Mapear teclado para modo 3 jogadores" só habilita quando o jogo
+//     ESTÁ em 3 telas — trocar o mapa de um modo em que você não está mostraria teclas que não valem.
+//   · `initMapHub(ctx).render()` — a metade impura: `innerHTML`, `querySelectorAll`, `addEventListener`.
+//
+// ======================= O AVISO É A PARTE DE ACESSIBILIDADE =======================
+// Um botão `disabled` é invisível para quem navega por teclado com leitor de tela: o foco simplesmente pula.
+// Por isso as duas mensagens de `srAlert` existem, e por isso elas são exportadas como funções puras
+// (`soonMessage`, `wrongModeMessage`): quem clica na linha cinza — por toque, ou porque o leitor lê a linha
+// inteira e não só o botão — recebe o MOTIVO em palavras, não silêncio.
+// Já foi assim: os botões nasciam com o atributo `disabled`, o `click` deles não disparava, e as duas
+// mensagens eram inalcançáveis — medido no navegador: das oito linhas, seis ficavam fora da ordem de foco e
+// clicar nelas não dizia nada. Agora é `aria-disabled`, que anuncia o estado sem esconder o botão.
+//
+// ======================= O QUE FICOU DE FORA, E POR QUÊ =======================
+//  · Abrir/fechar o overlay `#movement` (`openMovement`/`closeMovement`, `frontOverlay`, o foco no primeiro
+//    botão) FICA no main.js: é a casca compartilhada por TODOS os painéis de configuração, não deste.
+//  · `openOptions` e `gamepadApi.openPadWiz()` entram por injeção. O primeiro é do main.js (edita o controle
+//    do jogador que abriu a pausa), o segundo é de `input/gamepad.ts`.
+//  · O número de telas entra por GETTER (`getNumPlayers`) porque `numPlayers` é reatribuído por
+//    `setNumPlayers` a cada troca — e é justamente ele que decide quais linhas ficam cinzas.
+//
+// ======================= ARMADILHAS DE ORDEM DE BOOT =======================
+//  · Zero I/O no import: nada toca o DOM no corpo do módulo. `initMapHub` também não — ele só devolve
+//    `render()`, e é `render()` que procura `#map-hub`. Se o elemento não existir, `render()` desiste em
+//    silêncio (guard clause), como o original.
+//  · `render()` é chamado de dentro de `openMovement`, que é uma DECLARAÇÃO DE FUNÇÃO içada e aparece ANTES
+//    deste ponto no main.js. Não há TDZ: `openMovement` só roda a partir de um clique, muito depois do
+//    módulo ter avaliado. Ainda assim, a religação deve manter um invólucro `function renderMapHub()` no
+//    main.js — declaração içada, como manda a casa — para que a leitura de `openMovement` continue honesta.
+//  · O `np` é lido UMA vez por `render()` e fica preso no manipulador de clique daquela renderização. Isso é
+//    verbatim e é seguro hoje porque `openMovement` re-renderiza a cada abertura; se um dia o painel puder
+//    ficar aberto enquanto o nº de telas muda, esta é a linha a mexer.
+/**
+ * A TABELA — congelada. A ordem é a da tela: os quatro modos de teclado, o gamepad, e as três promessas.
+ * As três últimas são o roadmap deste jogo (webcam e fala), e é por causa delas que o módulo não é engine.
+ */
+export const MAP_HUB_ROWS = Object.freeze([
+    { lbl: '⌨ Mapear teclado para modo 1 jogador', mode: 1, act: 'options' },
+    { lbl: '⌨ Mapear teclado para modo 2 jogadores', mode: 2, act: 'options' },
+    { lbl: '⌨ Mapear teclado para modo 3 jogadores', mode: 3, act: 'options' },
+    { lbl: '⌨ Mapear teclado para modo 4 jogadores', mode: 4, act: 'options' },
+    { lbl: '🎮 Mapear gamepad', act: 'padwiz' }, // L1: assistente (DirectInput e afins) — mapa salvo por modelo
+    { lbl: '👁 Mapear olhos e boca', soon: true },
+    { lbl: '🎯 Mapear setores de olhar', soon: true },
+    { lbl: '🎤 Mapear palavras (fala)', soon: true },
+].map((r) => Object.freeze(r)));
+/** O estado de cada linha em `np` telas. Fonte única do markup e das duas mensagens de `srAlert`. */
+export function mapHubStates(np, rows = MAP_HUB_ROWS) {
+    return rows.map((r) => {
+        const off = !!r.mode && r.mode !== np; // teclado: só o modo em que o jogo ESTÁ fica clicável
+        return { off, dis: !!r.soon || off };
+    });
+}
+/** O HTML do painel inteiro — cabeçalho + uma `.ctrl-row` por linha. */
+export function mapHubMarkup(np, rows = MAP_HUB_ROWS) {
+    const st = mapHubStates(np, rows);
+    return '<h3 class="panel-sub">Mapear controles <span class="panel-sub__tag">por jogador</span></h3>' +
+        rows.map((it, i) => {
+            const dis = st[i].dis;
+            const note = it.soon ? ' <em style="opacity:.7">(em construção)</em>' : '';
+            // `aria-disabled` e NAO `disabled`: o atributo real tira o botao da ordem de foco e engole o clique,
+            // entao quem navega por teclado pulava seis das oito linhas e nunca ficava sabendo por que elas nao
+            // funcionam — enquanto quem enxerga ve a linha cinza e o "(em construcao)". Com `aria-disabled` o
+            // estado e anunciado, o botao continua alcancavel, e as duas frases de srAlert que ja existiam aqui
+            // finalmente chegam a alguem. O visual nao muda: quem pinta a linha cinza e a classe `row-off`.
+            return `<div class="ctrl-row${dis ? ' row-off' : ''}"><span>${it.lbl}${note}</span>` +
+                `<button class="mode-btn" type="button" data-map="${i}"${dis ? ' aria-disabled="true"' : ''}>${it.soon ? 'Em breve' : 'Abrir'}</button></div>`;
+        }).join('');
+}
+/** O rótulo sem o emoji da frente — "👁 Mapear olhos e boca" → "Mapear olhos e boca". */
+export function soonName(lbl) {
+    return lbl.replace(/^\S+\s/, '');
+}
+/** O aviso falado de uma linha em construção. */
+export function soonMessage(lbl) {
+    return soonName(lbl) + ': em construção — chega junto com os subsistemas de webcam e fala.';
+}
+/** O aviso falado de uma linha cujo modo não é o número de telas atual. */
+export function wrongModeMessage(mode) {
+    return 'Disponível só no modo ' + mode + ' jogador' + (mode > 1 ? 'es' : '') + '. Troque o nº de telas na barra do topo.';
+}
+export function initMapHub(ctx) {
+    /** Nome da ação → o painel de verdade. Fora da tabela, para a tabela poder ser dado congelado. */
+    function run(act) {
+        if (act === 'options')
+            ctx.openOptions();
+        else if (act === 'padwiz')
+            ctx.openPadWiz();
+    }
+    function render() {
+        const el = ctx.$('#map-hub');
+        if (!el)
+            return; // o painel não está neste documento — nada a fazer
+        const np = ctx.getNumPlayers(); // lido UMA vez; preso no manipulador desta renderização (ver o cabeçalho)
+        el.innerHTML = mapHubMarkup(np);
+        el.querySelectorAll('button[data-map]').forEach((b) => b.addEventListener('click', () => {
+            const it = MAP_HUB_ROWS[Number(b.dataset['map'])];
+            if (!it)
+                return;
+            if (it.soon) {
+                ctx.srAlert(soonMessage(it.lbl));
+                return;
+            } // em construção: diz o porquê
+            if (it.mode && it.mode !== np) {
+                ctx.srAlert(wrongModeMessage(it.mode));
+                return;
+            } // modo errado: idem
+            run(it.act ?? null);
+        }));
+    }
+    return { render };
+}

package/dist-pkg/ui/menu-nav.d.ts

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** ui/dom.ts `$` — injetado; o módulo nunca alcança `document`. */
+export type { DomQuery } from '../core/dom-query.js';
+/** A intenção, não a tecla. Definição única em input/edges; aqui só reexportada. */
+import type { NavKeys } from '../input/edges.js';
+export type { NavKeys } from '../input/edges.js';
+/** O que este módulo lê de um `KeyboardEvent`. */
+export interface NavKeyEvent {
+    code: string;
+    preventDefault(): void;
+    stopPropagation(): void;
+}
+/** Confirma/entra. `NumpadEnter` conta aqui (mas NÃO pausa: ver o ouvinte de bolha do game.js). */
+export declare const KEY_YES: ReadonlySet<string>;
+/** Volta. ⚠️ DEFEITO 2: `Escape` é a MESMA intenção que a ação "especial" do gamepad. Verbatim. */
+export declare const KEY_NO: ReadonlySet<string>;
+export declare const KEY_UP: ReadonlySet<string>;
+export declare const KEY_DOWN: ReadonlySet<string>;
+export declare const KEY_LEFT: ReadonlySet<string>;
+export declare const KEY_RIGHT: ReadonlySet<string>;
+/**
+ * Traduz (tecla física, ação remapeada do dono da tecla) → intenção. `act` é `null` quando a tecla não é de
+ * nenhum jogador (tecla genérica). Verbatim das seis linhas de `menuNavKey`.
+ */
+export declare function menuKeyIntent(code: string, act: string | null): NavKeys;
+import type { EventTargetLike } from '../input/touch-bindings.js';
+import type { DomQuery } from '../core/dom-query.js';
+export { hasNavIntent as hasIntent } from '../input/edges.js';
+export { passoNoAnel } from '../core/anel.js';
+/** `select` com esquerda/direita: um passo, SEM dar a volta — ajustar VALOR não é navegar lista (ver acima). */
+export declare function selectStep(selectedIndex: number, optionsLen: number, delta: number): number;
+/** `select` com "sim": um passo, COM volta. É a diferença deliberada entre confirmar e ajustar. */
+export declare function selectWrap(selectedIndex: number, optionsLen: number): number;
+/** `input[type=range]` com esquerda/direita: um `step` (default 1), preso entre `min` e `max`. */
+export declare function rangeStep(value: number, min: number, max: number, step: number, delta: number): number;
+/**
+ * O PASSO DO CURSOR NO MENU DE PAUSA — um ANEL, agora que a pausa é uma lista (ADR-0044, itens 1 e 7).
+ *
+ * ISTO SUBSTITUI `pauseGridMove`, e a substituição é o desfecho do ADR-0044, não uma limpeza. O que havia
+ * era uma GRADE de duas zonas — a barra de dez ícones em cima, a lista de itens em duas colunas embaixo — e
+ * uma fronteira entre elas com quatro regras próprias ("de cima, 'baixo' cai sempre no primeiro item", "da
+ * primeira linha, 'cima' sobe para o ícone de mesmo índice", …). Cada regra dessas era uma coisa a mais para
+ * a criança descobrir sem ver, e nenhuma delas era descobrível: só se aprendia esbarrando.
+ *
+ * A XAG 106 permite laço para menu LINEAR e o PROÍBE para grade de duas dimensões — numa grade, dar a volta
+ * teleporta o cursor para o outro canto e a pessoa perde a noção de onde está. Era por isso que o anel do
+ * item 1 valia para todo menu do jogo MENOS este. Com a barra no HUD (item 7), o cartão passou a ter uma
+ * lista só, e o laço deixou de ser proibido para virar o recomendado.
+ *
+ * O que se ganha em troca das quatro regras: `quit` fica a UMA tecla para CIMA de `resume`. Último na
+ * leitura, vizinho no dedo.
+ */
+export declare function passoNaPausa(len: number, idx: number, k: NavKeys): number;
+export interface MenuNavCtx {
+    /** ui/dom.ts `$` — só para achar `#padwiz`. */
+    $: DomQuery;
+    /** `document.activeElement` — injetado para o teste node poder simular foco sem DOM. */
+    getActiveElement: () => Element | null;
+    /** O overlay VISÍVEL de z-index mais alto dentro de `#game-region`. É o `sharedDialogOpen` original. */
+    topVisibleOverlay: () => HTMLElement | null;
+    /** `overlays.closeById(id)` — true se havia entrada registrada para aquele diálogo. */
+    closeById: (id: string) => boolean;
+    /** `vpPause[i]` — o menu de pausa da tela do jogador `i`. `buildGameHud` REATRIBUI a array. */
+    getPauseMenu: (playerIndex: number) => HTMLElement | null | undefined;
+    /** ui/shell.ts via o envelope içado do game.js. `no` na raiz do menu de pausa volta ao jogo. */
+    setPhase: (p: 'title' | 'playing' | 'paused') => void;
+    /** `let pauseActor` do game.js: "sim" no menu de pausa marca QUEM agiu (o submenu abre na aba dele).
+     *  ui/pause-icons.ts já recebe o mesmo setter — o `let` continua sendo do game.js, com seis leitores. */
+    setPauseActor: (playerIndex: number) => void;
+    /**
+     * ESTE É O MOMENTO DE NAVEGAR MENU? Se `false`, toda tecla passa direto.
+     *
+     * Era `if (phase !== 'paused') return`, com `phase` vindo por IMPORTAÇÃO de `core/state` — e o segundo
+     * consumidor mostrou o preço (achado 10 de `consumer-quiz`): um quiz cujos ajustes estão SEMPRE disponíveis
+     * precisava se declarar "pausado" para poder navegar os próprios menus. Não havia como trazer o próprio
+     * modelo de fases, porque não havia por onde.
+     *
+     * A pergunta injetada é PROPOSITALMENTE um booleano, e não a fase. Injetar `getPhase()` teria consertado a
+     * importação e mantido a mentira: o consumidor continuaria obrigado a devolver a string `'paused'`, que é
+     * um conceito do jogo de plataforma. Perguntando "dá para navegar agora?", o jogo de plataforma responde
+     * `phase === 'paused'` e um quiz responde `true` — cada um na sua língua, e nenhum dos dois mentindo.
+     */
+    isNavigable: () => boolean;
+    /**
+     * `core/a11y-sr.srSay` — a região `aria-live` "polite". INJETADO porque ela alcança o `document` na hora da
+     * chamada, e este módulo não pode alcançar documento nenhum por conta própria.
+     *
+     * O menu de PAUSA precisa dela e os diálogos não: eles selecionam por FOCO, e o leitor de tela anuncia o
+     * foco sozinho. A pausa seleciona por CLASSE (`.pm-sel`), porque é desenhada dentro da tela do jogador —
+     * e classe nenhuma dispara anúncio. Sem esta injeção o menu é mudo para quem o navega por escuta.
+     */
+    srSay: (texto: string) => void;
+    /**
+     * O índice "N de M" está ligado? (ADR-0044, item 3, e a XAG 106 exige que ele possa ser desligado.)
+     *
+     * PERGUNTADO ao ctx e não lido de `core/state`, e o motivo é o mesmo do `isNavigable`: enquanto este módulo
+     * importava `core/state`, um segundo jogo não tinha como trazer o próprio modelo — o quiz teve de se
+     * declarar "pausado" para navegar os menus dele. `tests/menu-nav.node.test.js` reprova se a aresta voltar,
+     * e ela quase voltou por aqui: eu tinha escrito o `import` antes de o gate me lembrar.
+     */
+    comIndice: () => boolean;
+    /**
+     * A tela `i` está no modo `accessibility` (ADR-0044, item 7)? Perguntado ANTES de `isNavigable`, porque
+     * esse modo roda com o jogo ANDANDO — é a única coisa deste módulo que age fora da pausa.
+     */
+    naBarraDe: (i: number) => boolean;
+    /** Um passo dentro da barra rápida da tela `i`. */
+    navBar: (i: number, k: NavKeys) => void;
+    /** ui/settings-controls.ts: um remap em andamento consome a tecla — o menu não pode roubá-la. */
+    isCapturing: () => boolean;
+    /** input/gamepad.ts: o assistente de mapeamento fica POR CIMA de tudo; só Escape (cancela) o alcança. */
+    closePadWiz: (save: boolean) => void;
+    /** input/keyboard-runtime.ts: de quem é esta tecla? (-1 = genérica). */
+    whichPlayer: (code: string) => number;
+    /** input/keyboard-runtime.ts: que ação esta tecla é PARA aquele jogador (respeitando o remap)? */
+    actionOf: (code: string, playerIndex: number) => string | null;
+    /** `window` — só para `attach()` instalar o ouvinte em CAPTURA, exatamente como o game.js fazia. */
+    /** A escuta de teclado dos menus. Ver `EventTargetLike` em input/touch-bindings. */
+    win: EventTargetLike;
+}
+export interface MenuNavApi {
+    /** O overlay visível mais alto (alias de `topVisibleOverlay` — ver "a duplicação que esta extração curou"). */
+    sharedDialogOpen: () => HTMLElement | null;
+    /** Os controles NAVEGÁVEIS de um menu: habilitados E visíveis (`offsetParent !== null`). */
+    menuItems: (menu: HTMLElement) => HTMLElement[];
+    /** Foca o item atual (se já for um deles) ou o primeiro. Sai calado com `menu` nulo — ver o DEFEITO 1. */
+    menuFocus: (menu: HTMLElement | null) => void;
+    /** Fecha o diálogo e tenta devolver o foco ao que ficou por baixo. */
+    dialogBack: (menu: HTMLElement) => void;
+    /** Um passo de navegação DENTRO de um diálogo de configuração. */
+    navDialog: (menu: HTMLElement, k: NavKeys) => void;
+    /** Marca `el` como o item selecionado de `menu` e atualiza a legenda dos ícones. */
+    pauseSetSel: (menu: HTMLElement, el: HTMLElement | null | undefined) => void;
+    /** Um passo de navegação DENTRO de um menu de pausa (barra de ícones + grade de itens). */
+    navPause: (menu: HTMLElement, playerIndex: number, k: NavKeys) => void;
+    /** O tradutor de teclado. Exportado à parte para o teste disparar sem depender da fase de propagação. */
+    menuNavKey: (e: NavKeyEvent) => void;
+    /** Instala `menuNavKey` em CAPTURA na janela — verbatim do game.js. */
+    attach: () => void;
+}
+export declare function initMenuNav(ctx: MenuNavCtx): MenuNavApi;