@the-inclusionist/engine 6.36.1

package/dist-pkg/input/keyboard-runtime.js

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/keyboard-runtime.ts — keyboard ROUTING at play time: which key belongs to which player, which action
+// it fires. Extracted from game.js (kbFor/actionOf/whichPlayer/assignControls/applyControls). Pure logic, DI
+// via initKeyboardRuntime(ctx): reads the live KB config (input/keyboard.ts owns load/save/reset) and the live
+// numPlayers/players (still in game.js) through injected getters — never imports game.js, never touches
+// `document`. KJUMP/KLEFT/.../GAME_KEYS come back as a plain VALUE object (computeControlsState) instead of
+// being reassigned here: imported bindings can't be reassigned from outside their own module, so the game.js
+// wrapper is the one that copies the returned fields onto its own `let`s (same trap `core/state.ts` documents
+// for `coins`/`players`).
+// ---------------------------------------------------------------------------------------------
+// Pure logic (no ctx, no `document` — directly testable with plain KeyScheme fixtures)
+// ---------------------------------------------------------------------------------------------
+/** code -> action index for ONE scheme, first action wins when a code is bound twice in the same scheme
+ *  (mirrors ui/settings-controls.ts's keyUsedByOther: a Map built over the scheme, not a re-scan per query). */
+function buildActionIndex(scheme) {
+    const index = new Map();
+    for (const action in scheme) {
+        for (const code of scheme[action]) {
+            if (!index.has(code))
+                index.set(code, action);
+        }
+    }
+    return index;
+}
+/** Which action does `code` trigger in this ONE scheme? Pure — no player/KB involved. */
+export function actionForCode(scheme, code) {
+    return buildActionIndex(scheme).get(code) ?? null;
+}
+/** Which player owns `code`, given one scheme per player (index = player index)? -1 if none. Pure. */
+export function ownerOfCode(schemesByPlayer, code) {
+    for (let i = 0; i < schemesByPlayer.length; i++) {
+        if (actionForCode(schemesByPlayer[i], code))
+            return i;
+    }
+    return -1;
+}
+// ---------------------------------------------------------------------------------------------
+// DI runtime (closes over ctx — still no `document`)
+// ---------------------------------------------------------------------------------------------
+export function initKeyboardRuntime(ctx) {
+    function kbFor(playerIndex) {
+        const kb = ctx.getKB();
+        const n = ctx.getNumPlayers();
+        if (n <= 1)
+            return kb.solo;
+        if (n <= 2)
+            return kb.p2[playerIndex] || kb.p2[0];
+        if (n <= 3)
+            return kb.p3[playerIndex] || kb.p3[0];
+        return kb.p4[playerIndex] || kb.p4[0];
+    }
+    function schemesForActivePlayers() {
+        const n = ctx.getNumPlayers();
+        return Array.from({ length: n }, (_, i) => kbFor(i));
+    }
+    function actionOf(code, playerIndex) {
+        return actionForCode(kbFor(playerIndex), code);
+    }
+    function whichPlayer(code) {
+        return ownerOfCode(schemesForActivePlayers(), code);
+    }
+    function assignControls() {
+        ctx.getPlayers().forEach((p, i) => { p.ctrl = kbFor(i); });
+    }
+    function computeControlsState() {
+        const kb = ctx.getKB();
+        const controls = kb.solo; // alias do P1 — SEMPRE kb.solo, mesmo com numPlayers>1 (comportamento original; ver relato)
+        const { action2, left, right, up, down, action1 } = controls;
+        const gameKeySet = new Set();
+        ctx.getPlayers().forEach((_, i) => {
+            const scheme = kbFor(i);
+            for (const action in scheme)
+                for (const code of scheme[action])
+                    gameKeySet.add(code);
+        });
+        const gameKeys = gameKeySet.size ? [...gameKeySet] : [...action2, ...left, ...right, ...up, ...down];
+        return { controls, action2, left, right, up, down, action1, gameKeys };
+    }
+    let cache = null; // memória do estado derivado; só refreshControls a invalida
+    function controlsState() { return cache ?? (cache = computeControlsState()); }
+    function refreshControls() { cache = computeControlsState(); return cache; }
+    return { kbFor, actionOf, whichPlayer, assignControls, computeControlsState, controlsState, refreshControls };
+}

package/dist-pkg/input/keyboard.d.ts

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { KeyScheme } from '../core/entity.js';
+export type { KeyScheme } from '../core/entity.js';
+/**
+ * O CONJUNTO DE ESQUEMAS de teclado — solo mais os de 2, 3 e 4 jogadores.
+ *
+ * Exportado desde 2026-08-26, e o motivo é que ele já era copiado: `input/keyboard-runtime` e
+ * `ui/settings-controls` declaravam cada um o seu `KeyboardConfig`, e AMBOS diziam no comentário que
+ * era "a forma do KBDefaults de input/keyboard". Sabiam que eram cópia e copiavam mesmo assim.
+ *
+ * A de `settings-controls` era `Record<string, unknown>` — pensada como opaca, para o módulo não
+ * depender da forma. Mas em posição de PARÂMETRO isso se inverte: para aceitar `(next: KBDefaults)`,
+ * o tipo declarado tem de ser SUBTIPO, não supertipo. A opacidade se preserva por disciplina — não
+ * indexar o valor — e não por escrever um tipo mais largo (ADR-0039).
+ */
+export type KBDefaults = {
+    solo: KeyScheme;
+    p2: KeyScheme[];
+    p3: KeyScheme[];
+    p4: KeyScheme[];
+};
+export declare const KB_SCHEMES4: KeyScheme[];
+export declare const KB_DEFAULTS: KBDefaults;
+export declare function loadKB(): KBDefaults;
+export declare function saveKB(kb: KBDefaults): void;
+/**
+ * O MAPA DE TECLAS VIVO. Migrado do composition root (#50): era um `let KB` do main.js com um envoltório
+ * `setKB: (k) => { KB = k; }` fabricado à mão para o painel de controles reatribuí-lo.
+ *
+ * Mora AQUI, e não em core/state como os outros migrados, porque o dono é evidente: `loadKB`, `saveKB` e
+ * `resetKB` já viviam neste arquivo. Separar o valor das três funções que o gerenciam seria mover o problema
+ * de lugar em vez de resolvê-lo.
+ *
+ * NASCE COM OS PADRÕES E NÃO LÊ DISCO NO IMPORT. `initKB()` é quem lê, chamado uma vez pelo boot. A regra vale
+ * para todo módulo do projeto, e aqui ela tem um custo concreto se for quebrada: um teste que importe qualquer
+ * coisa deste arquivo passaria a depender do localStorage do ambiente, e um mapa de teclas herdado de outro
+ * caso é uma falha que aparece longe da causa.
+ */
+export declare let kb: KBDefaults;
+/** Lê o mapa persistido para dentro de `kb`. O boot chama uma vez; devolve o valor para quem quiser encadear. */
+export declare function initKB(): KBDefaults;
+/** Troca o mapa inteiro. Só o "restaurar padrões" do painel de controles precisa disto — remapear uma tecla
+ *  MUTA o objeto, e reatribuir por engano faria as referências vivas apontarem para o mapa antigo. */
+export declare function setKB(next: KBDefaults): void;
+export declare function resetKB(): KBDefaults;

package/dist-pkg/input/keyboard.js

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/keyboard.ts — esquemas de teclado (config) + persistência. Módulo-folha (só depende de storage).
+// ⚠️ AS AÇÕES SÃO POSIÇÕES, NÃO VERBOS, desde 2026-09-06: `up`, `down`, `left`, `right` e `action1`..`action4`.
+// A linha anterior listava «run(corre/interage), jump, swap(troca poder), especial» — vocabulário de PLATAFORMA
+// dentro da engine, que é exatamente o que o ADR-0074 tirou daqui. Qual verbo mora em qual posição é do JOGO,
+// e o ADR-0086 §2 diz qual é para a plataforma. Esquemas por contagem de jogadores (solo/p2/p3/p4).
+// A INSTÂNCIA atual (KB) e o remap ficam no composition root — aqui só config/load/save/reset.
+import * as store from '../platform/storage.js';
+const CKEY = 'inclusionist.kbcontrols.v3';
+// 4 esquemas base p/ 3–4 jogadores (modos 3 e 4 têm esquemas SEPARADOS, p3 e p4, editáveis por jogador)
+export const KB_SCHEMES4 = [
+    { left: ['KeyA'], right: ['KeyD'], up: ['KeyW'], down: ['KeyS'], action1: ['KeyZ'], action2: ['KeyX'], action4: ['KeyC'], action3: ['KeyV'] },
+    { left: ['KeyJ'], right: ['KeyL'], up: ['KeyI'], down: ['KeyK'], action1: ['KeyM'], action2: ['Comma'], action4: ['Period'], action3: ['Semicolon', 'Slash'] },
+    { left: ['ArrowLeft'], right: ['ArrowRight'], up: ['ArrowUp'], down: ['ArrowDown'], action1: ['Home'], action2: ['End'], action4: ['PageUp'], action3: ['PageDown'] },
+    { left: ['Numpad4'], right: ['Numpad6'], up: ['Numpad8'], down: ['Numpad5'], action1: ['Numpad2'], action2: ['Numpad0'], action4: ['Numpad3'], action3: ['NumpadDecimal'] },
+];
+export const KB_DEFAULTS = {
+    // 1 jogador: WASD + setas; pulo J/Espaço; UJIK como na mão pequena do DOS. Sem Alt/AltGr/Ctrl/Shift.
+    solo: { left: ['KeyA', 'ArrowLeft'], right: ['KeyD', 'ArrowRight'], up: ['KeyW', 'ArrowUp'], down: ['KeyS', 'ArrowDown'],
+        action1: ['KeyU'], action2: ['KeyJ', 'Space'], action4: ['KeyI'], action3: ['KeyK'] },
+    p2: [{ left: ['KeyA'], right: ['KeyD'], up: ['KeyW'], down: ['KeyS'], action1: ['KeyU'], action2: ['KeyJ'], action4: ['KeyI'], action3: ['KeyK'] },
+        { left: ['ArrowLeft'], right: ['ArrowRight'], up: ['ArrowUp'], down: ['ArrowDown'], action1: ['Numpad8'], action2: ['Numpad5'], action4: ['Numpad9'], action3: ['Numpad6'] }],
+    p3: JSON.parse(JSON.stringify(KB_SCHEMES4.slice(0, 3))), // modo 3 jogadores (independente do 4)
+    p4: JSON.parse(JSON.stringify(KB_SCHEMES4)), // modo 4 jogadores
+};
+// dado salvo (parcial): sobrepõe os defaults; p34 é o formato ANTIGO (migra p/ p3+p4).
+// A FORMA vem de `vocabulary-migration`, que é quem a traduz — declarar aqui outra vez seria a
+// cópia que o `core/entity` passou o mês a eliminar.
+import { migrarSalvo } from './vocabulary-migration.js';
+// ⚠️ A MIGRAÇÃO DE VOCABULÁRIO MORA NOUTRO FICHEIRO, e a separação é deliberada:
+// `input/vocabulary-migration.ts` é o ÚNICO sítio da engine autorizado a dizer `jump`, porque traduzir o
+// nome antigo é a função dele. Deixá-la aqui punha o acoplamento num módulo que não é histórico, e o gate
+// `action-vocabulary-boundary` reprovou — corretamente. Ver o cabeçalho de lá para saber quando se apaga.
+// carrega os esquemas salvos SOBRE os defaults (com migração do dado antigo p34 → p3+p4)
+export function loadKB() {
+    const d = JSON.parse(JSON.stringify(KB_DEFAULTS));
+    // ⚠️ O DADO SALVO ATRAVESSA O TRADUTOR ANTES DE TOCAR NOS PADRÕES. Sem esta linha, um esquema gravado com
+    // as chaves antigas (`run`, `jump`, `swap`, `especial`) seria fundido sobre defaults que já usam
+    // `action1`..`action4`: o objeto ficaria com AS DUAS famílias de chaves, os transportes leriam só as novas,
+    // e o remapeamento da criança viraria dado morto no navegador dela. Nada erraria em voz alta — as teclas
+    // dela simplesmente parariam de responder. Ver `input/vocabulary-migration.ts`.
+    const s = migrarSalvo(store.getJSON(CKEY, null));
+    if (s) {
+        if (s.solo)
+            Object.assign(d.solo, s.solo);
+        if (Array.isArray(s.p34)) {
+            s.p34.forEach((m, i) => { if (m) {
+                if (d.p4[i])
+                    Object.assign(d.p4[i], m);
+                if (i < 3 && d.p3[i])
+                    Object.assign(d.p3[i], m);
+            } });
+        }
+        ['p2', 'p3', 'p4'].forEach((g) => { const arr = s[g]; if (Array.isArray(arr))
+            arr.forEach((m, i) => { if (d[g][i] && m)
+                Object.assign(d[g][i], m); }); });
+    }
+    return d;
+}
+export function saveKB(kb) { store.setJSON(CKEY, kb); }
+/**
+ * O MAPA DE TECLAS VIVO. Migrado do composition root (#50): era um `let KB` do main.js com um envoltório
+ * `setKB: (k) => { KB = k; }` fabricado à mão para o painel de controles reatribuí-lo.
+ *
+ * Mora AQUI, e não em core/state como os outros migrados, porque o dono é evidente: `loadKB`, `saveKB` e
+ * `resetKB` já viviam neste arquivo. Separar o valor das três funções que o gerenciam seria mover o problema
+ * de lugar em vez de resolvê-lo.
+ *
+ * NASCE COM OS PADRÕES E NÃO LÊ DISCO NO IMPORT. `initKB()` é quem lê, chamado uma vez pelo boot. A regra vale
+ * para todo módulo do projeto, e aqui ela tem um custo concreto se for quebrada: um teste que importe qualquer
+ * coisa deste arquivo passaria a depender do localStorage do ambiente, e um mapa de teclas herdado de outro
+ * caso é uma falha que aparece longe da causa.
+ */
+export let kb = JSON.parse(JSON.stringify(KB_DEFAULTS));
+/** Lê o mapa persistido para dentro de `kb`. O boot chama uma vez; devolve o valor para quem quiser encadear. */
+export function initKB() { kb = loadKB(); return kb; }
+/** Troca o mapa inteiro. Só o "restaurar padrões" do painel de controles precisa disto — remapear uma tecla
+ *  MUTA o objeto, e reatribuir por engano faria as referências vivas apontarem para o mapa antigo. */
+export function setKB(next) { kb = next; }
+export function resetKB() { store.remove(CKEY); return JSON.parse(JSON.stringify(KB_DEFAULTS)); }

package/dist-pkg/input/keydown.d.ts

@@ -0,0 +1,270 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { PlayerView } from '../core/entity.js';
+import { type EdgeFlag } from './edges.js';
+/** ui/dom.ts `$` — injetado; o módulo nunca alcança `document`. */
+export type { DomQuery } from '../core/dom-query.js';
+/** O que este módulo lê e faz com um `KeyboardEvent` de `keydown`. */
+export interface KeydownEventLike {
+    code: string;
+    altKey: boolean;
+    ctrlKey: boolean;
+    preventDefault(): void;
+}
+/** `keyup` só precisa do código. */
+export interface KeyupEventLike {
+    code: string;
+}
+/** ação -> lista de códigos físicos. Cópia ESTRUTURAL do `KeyScheme` de input/keyboard-runtime.ts: a casa
+ *  prefere a cópia a puxar um alias de tipo através de camadas (ver o cabeçalho de keyboard-runtime). */
+export type { KeyScheme } from '../core/entity.js';
+/** As seis bordas de entrada que o keydown levanta no jogador (consumidas e zeradas pela física). */
+/**
+ * O que este módulo lê (e escreve) de um jogador — e SÓ isso. DERIVADA de core/entity.
+ *
+ *  · `i`        — índice PRÓPRIO do jogador (`makePlayer(i)`). O original roteia por ele, não pela posição.
+ *  · `ctrl`     — esquema de teclas; `null` antes do assignControls.
+ *  (`quiz` SAIU em 2026-08-25 — ADR-0033. O desafio aberto chega por `modalOpen` no snapshot, e o que a
+ *   tecla SIGNIFICA lá dentro é decisão do jogo. Ver o bloco "MODAL" abaixo.)
+ *  · `waiting`  — tela em espera (multi-tela): a 1ª tecla DAQUELE jogador entra na partida.
+ *  · `easy`     — modo Fácil (deficiência motora): sem correr, e ganha os atalhos Ctrl/Shift no solo.
+ */
+export type KeydownPlayer = PlayerView<'i' | 'ctrl' | 'waiting' | 'easy' | 'jumpEdge' | 'runEdge' | 'leftEdge' | 'rightEdge' | 'swapEdge' | 'specialEdge'>;
+/** Subconjunto do `ControlsState` de input/keyboard-runtime.ts que a decisão consulta (`controls` não entra:
+ *  o original nunca o usa aqui, só os seis aliases e a lista achatada). */
+export interface ControlsSnapshot {
+    action2: string[];
+    left: string[];
+    right: string[];
+    up: string[];
+    down: string[];
+    action1: string[];
+    gameKeys: string[];
+}
+/** A intenção de navegação do menu inicial. Era uma quarta cópia estrutural, sob outro nome; agora é o
+ *  `NavKeys` de input/edges, reexportado com o nome que os chamadores deste módulo já usam. */
+import type { NavKeys as TitleNav } from './edges.js';
+export type { NavKeys as TitleNav } from './edges.js';
+/** TUDO o que a decisão precisa saber do mundo, num objeto só, montado ANTES de qualquer efeito. */
+export interface KeydownSnapshot {
+    /** A tela de título está no topo? (Só o Jogador 1 escolhe o jogo; os outros ouvem um aviso.) */
+    telaDeTitulo: boolean;
+    /** Há jogo em curso — rodando OU pausado? (Alt+N e a tecla de pausa exigem isto, e quiz fechado.) */
+    emJogo: boolean;
+    numPlayers: number;
+    players: readonly KeydownPlayer[];
+    /**
+     * Há MODAL aberto para o jogador de cada POSIÇÃO? — a resposta, ao lado dos jogadores (ADR-0033).
+     *
+     * Era `players[i].quiz`, e o custo nunca foi a leitura: `players` já chega por injeção. O custo era que
+     * ler o campo obrigava `core/entity.Player` — a entidade canônica da ENGINE — a DECLARÁ-LO, e com isso
+     * todo jogo do catálogo a ter um "quiz" com aquele formato.
+     *
+     * Por que aqui e não em duas funções de ctx: este módulo já monta um snapshot antes de qualquer efeito, e
+     * acrescentar ctx a quem já tem snapshot é peça a mais. Por que um array PARALELO e não um campo no
+     * `KeydownPlayer`: aquele tipo é `PlayerView<>` derivado de `Player`, então o campo voltaria a ser exigido
+     * na entidade — nome melhor, mesmo lugar errado. E por que não embrulhar os jogadores numa cópia: este
+     * módulo ESCREVE neles (as seis bordas), e a cópia perderia a escrita.
+     */
+    modalOpen: readonly boolean[];
+    controls: ControlsSnapshot;
+    /** `keys` de input/state.ts: as teclas seguradas AGORA (inclui códigos injetados por toque/webcam). */
+    heldKeys: ReadonlySet<string>;
+    /** empatia motora: um botão de jogo por vez. */
+    oneButton: boolean;
+    /** `overlays.escapeTarget()` — id do 1º diálogo REGISTRADO que está aberto, ou null. */
+    escapeTargetId: string | null;
+    touchCfgVisible: boolean;
+    padWizVisible: boolean;
+    winVisible: boolean;
+    actionOf(code: string, playerIndex: number): string | null;
+    whichPlayer(code: string): number;
+}
+export type ModalIntent = 'left' | 'right' | 'up' | 'down' | 'confirm' | 'erase';
+/** Uma borda a levantar: qual jogador (POSIÇÃO no array) e qual flag. */
+export interface EdgeRaise {
+    playerIndex: number;
+    edge: EdgeFlag;
+}
+/**
+ * A resposta única: o que esta tecla SIGNIFICA. `kind` é o ramo da ordem de precedência que venceu — e é essa
+ * palavra, e não o efeito, que os testes de precedência afirmam.
+ */
+export type KeydownDecision = 
+/** 1º · diálogo REGISTRADO aberto: Escape fecha (`closeId`), qualquer outra tecla é engolida. */
+{
+    kind: 'overlay';
+    closeId: string | null;
+    preventDefault: boolean;
+}
+/** 2º · `#touchcfg` visível: Escape esconde, o resto é engolido. */
+ | {
+    kind: 'touchcfg';
+    close: boolean;
+    preventDefault: boolean;
+}
+/** 3º · `#padwiz` (assistente de gamepad) visível: Escape CANCELA (`save:false`), o resto é engolido. */
+ | {
+    kind: 'padwiz';
+    close: boolean;
+    preventDefault: boolean;
+}
+/** 4º · tela de vitória: pulo (de qualquer jogador) ou Escape/Enter apertam "Jogar de novo". */
+ | {
+    kind: 'win';
+    again: boolean;
+    preventDefault: boolean;
+}
+/** 5º · tela de título: `wait` = multi-tela e a tecla é de outro jogador (só o J1 comanda). */
+ | {
+    kind: 'title';
+    wait: boolean;
+    nav: TitleNav | null;
+    preventDefault: boolean;
+}
+/** 6º · Alt+1..4 = número de telas. */
+ | {
+    kind: 'screens';
+    count: number;
+    preventDefault: boolean;
+}
+/** 7º · Escape/Enter = pausa. */
+ | {
+    kind: 'pause';
+    preventDefault: boolean;
+}
+/** 8º · modal aberto: a tecla age no modal do DONO dela (`playerIndex` = posição no array). */
+ | {
+    kind: 'modal';
+    playerIndex: number;
+    intent: ModalIntent | null;
+    preventDefault: boolean;
+}
+/** 9º · jogo normal. */
+ | {
+    kind: 'play';
+    gameKey: boolean;
+    wake: number[];
+    edges: EdgeRaise[];
+    releaseKeys: string[];
+    preventDefault: boolean;
+};
+/** Fácil (SOLO): Ctrl = Especial, Shift = Trocar poder. Fora de Win/Alt/AltGr, de propósito. */
+export declare const EASY_SHORTCUTS: ReadonlySet<string>;
+/** Alt + fileira de números (NÃO o teclado numérico) = 1..4 telas. Alt fica livre: o solo não o usa. */
+export declare const SCREEN_DIGITS: RegExp;
+/** Pausa: Escape ou o Enter CENTRAL. `NumpadEnter` NÃO pausa (E14, verbatim). */
+export declare const PAUSE_KEYS: ReadonlySet<string>;
+export { EDGE_BY_ACTION, edgeAllowed } from './edges.js';
+export type { EdgeFlag } from './edges.js';
+/** A tecla vale como PULO para alguém? O alias do J1 OU a ação `jump` de qualquer jogador (é o que faz
+ *  "qualquer um pode apertar Jogar de novo" e "qualquer um confirma no título" serem verdade). */
+export declare function isJumpKey(code: string, s: KeydownSnapshot): boolean;
+/** A tecla é de JOGO? Verbatim do `isGameKeyCode` do game.js — o alias achatado OU o esquema de algum
+ *  jogador. NÃO inclui os atalhos do Fácil (o original também não: por isso `easyKey` é somado à parte). */
+export declare function isGameKeyCode(code: string, s: KeydownSnapshot): boolean;
+/** Os atalhos de acessibilidade do Fácil só existem SOLO (`numPlayers<=1`) e só para o Jogador 1. */
+export declare function isEasyShortcut(code: string, s: KeydownSnapshot): boolean;
+/**
+ * A intenção no menu inicial. Repare na ASSIMETRIA, preservada verbatim: `up`/`down` aceitam ArrowUp/ArrowDown
+ * ALÉM do alias configurado, `left`/`right` não aceitam ArrowLeft/ArrowRight. No esquema de fábrica isso não
+ * aparece (o solo já tem as setas nos quatro lados); aparece para quem REMAPEIA — remapeou esquerda para KeyA
+ * e a seta deixa de andar no menu, enquanto cima continua funcionando pelas duas. Está anotado como caso de
+ * teste em tests/keydown.node.test.js, e é candidato a conserto, não a "limpeza" silenciosa.
+ */
+export declare function titleNavOf(code: string, s: KeydownSnapshot, action2: boolean): TitleNav;
+import type { EventTargetLike } from './touch-bindings.js';
+import type { DomQuery } from '../core/dom-query.js';
+export { hasNavIntent as hasTitleIntent } from './edges.js';
+/**
+ * Quem é o dono do modal que esta tecla comanda? Devolve a POSIÇÃO no array, ou -1.
+ * Regra verbatim: tecla de um jogador vai para o modal DAQUELE jogador (e só se ele tiver um aberto); tecla
+ * genérica cai no Jogador 1. Tecla de um jogador SEM modal aberto não cai no P1 — ela desce para o jogo
+ * normal, que é o que deixa a partida dele continuar enquanto o outro resolve o desafio.
+ */
+export declare function modalOwnerIndex(code: string, s: KeydownSnapshot): number;
+/**
+ * Que INTENÇÃO esta tecla exprime dentro do modal do dono. `owner` é a posição no array; `generic` diz se a
+ * tecla chegou sem dono (aí as seis leituras usam os aliases do J1 em vez da ação remapeada).
+ *
+ * As seis leituras são as mesmas de antes, letra por letra. O que saiu foi a linha seguinte: a que trocava
+ * "cima" por `delta:-3` e "esquerda" por `delta:-1`, e o desvio de Braille. Isso é grade, e grade é do jogo.
+ */
+export declare function modalIntentOf(code: string, s: KeydownSnapshot, owner: number, generic: boolean): ModalIntent | null;
+/**
+ * As bordas que esta tecla levanta. Só é chamada quando a tecla AINDA NÃO está segurada — é isso que a torna
+ * uma BORDA e não um estado, e é o que impede o auto-repeat do sistema de virar dez pulos.
+ * `p.ctrl[act] || []`: o original alcançava `p.ctrl.jump` direto e estouraria num esquema sem a ação. Trocar
+ * um TypeError por um no-op não remove rede de conserto nenhuma (o precedente é a guarda de `navPause` em
+ * ui/menu-nav.ts) — é a única linha desta função que não é cópia literal.
+ */
+export declare function edgesFor(code: string, s: KeydownSnapshot): EdgeRaise[];
+/**
+ * A CADEIA. Nove perguntas, nesta ordem — e a ordem É a especificação.
+ * O que NÃO está aqui, e vem antes no wrapper: a demo (attract) e a captura de remapeamento. Ver o cabeçalho.
+ */
+export declare function decideKeydown(ev: {
+    code: string;
+    altKey?: boolean;
+    ctrlKey?: boolean;
+}, s: KeydownSnapshot): KeydownDecision;
+export interface KeydownCtx {
+    /** game/attract.ts: zera a ociosidade e encerra a demo; `true` = a tecla foi só para acordar. */
+    attractOnInput: () => boolean;
+    /** ui/settings-controls.ts: remapeamento em curso — a próxima tecla VIRA o controle. */
+    handleCaptureKeydown: (e: KeydownEventLike) => boolean;
+    /** Os dois fatos da cena. Ver `KeydownSnapshot`: booleanos, nunca a fase. */
+    isTelaDeTitulo: () => boolean;
+    isEmJogo: () => boolean;
+    getNumPlayers: () => number;
+    getPlayers: () => readonly KeydownPlayer[];
+    /** `kbRuntime.controlsState()` — memorizado do lado de lá; uma chamada por tecla, como no original. */
+    getControls: () => ControlsSnapshot;
+    /** `keys` de input/state.ts: `const` mutado in place → entra por VALOR (é sempre o mesmo objeto). */
+    heldKeys: Set<string>;
+    /** `let oneButton` do game.js (empatia motora) → getter. */
+    isOneButton: () => boolean;
+    actionOf: (code: string, playerIndex: number) => string | null;
+    whichPlayer: (code: string) => number;
+    $: DomQuery;
+    /** `overlays.escapeTarget()` de ui/settings-panel.ts. */
+    escapeTarget: () => string | null;
+    /** `overlays.closeById(id)` — o retorno é ignorado, verbatim. */
+    closeOverlayById: (id: string) => void;
+    /** input/gamepad.ts. LAZY: `gamepadApi` é `const` declarado ~800 linhas abaixo do ponto de init. */
+    closePadWiz: (save: boolean) => void;
+    /** input/touch.ts via o envelope içado do game.js. Sem motivo no título; `'teclado'` no jogo (E13). */
+    hideTouchControls: (reason?: string) => void;
+    srSay: (msg: string) => void;
+    navTitle: (k: TitleNav) => void;
+    activateScreens: (n: number) => void;
+    togglePause: () => void;
+    /**
+     * A INTENÇÃO chega, e o JOGO decide o que ela significa (ADR-0033).
+     *
+     * Eram quatro: `quizMove(pl, delta)`, `quizConfirm`, `quizErase` e `announceBraille` — e as quatro só
+     * existiam porque a decisão de qual chamar morava aqui, com a grade de três colunas e o desvio de Braille.
+     * Viraram uma. Um jogo com grade de quatro colunas, ou com lista vertical, responde diferente sem que este
+     * módulo saiba que existe grade.
+     */
+    /** O ÍNDICE do jogador, não o jogador (ADR-0033/0039). Ver a mesma nota em input/gamepad. */
+    modalInput: (playerIndex: number, intent: ModalIntent) => void;
+    /** O jogador da POSIÇÃO `i` tem um modal aberto? Uma pergunta, e não o objeto: ver `modalOpen` no snapshot. */
+    hasModal: (playerIndex: number) => boolean;
+    /** ui/hud.ts: some com o selo "tela em espera" quando o jogador daquela tela entra. */
+    clearWaitingBadge: (playerIndex: number) => void;
+    /** `window` — só para `attach()` instalar os dois ouvintes de BOLHA, exatamente como o game.js fazia. */
+    /** A escuta de teclado. Ver `EventTargetLike` em input/touch-bindings: genérica sobre `WindowEventMap`,
+     *  porque a versão com `fn: (e: never)` obrigava um cast aqui e um adaptador em cada consumidor. */
+    win: EventTargetLike;
+}
+export interface KeydownApi {
+    /** O snapshot que a decisão consome. Exposto para o teste poder montá-lo e comparar. */
+    snapshot: () => KeydownSnapshot;
+    /** O ouvinte de bolha inteiro (sondas + decisão + efeito). Exportado à parte para o teste disparar sem DOM. */
+    onKeydown: (e: KeydownEventLike) => void;
+    /** A outra metade do `keys.add`. */
+    onKeyup: (e: KeyupEventLike) => void;
+    /** Instala os dois na janela, em BOLHA, na mesma ordem de antes. */
+    attach: () => void;
+}
+export declare function initKeydown(ctx: KeydownCtx): KeydownApi;