@the-inclusionist/engine 6.36.1

package/dist-pkg/input/default-bindings.d.ts

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type Action } from '../core/actions.js';
+/** `null` = este transporte NÃO alcança esta ação por padrão. Ausência declarada, nunca esquecimento. */
+export type Binding<T> = T | null;
+/**
+ * Teclado, esquema SOLO. Códigos de `KeyboardEvent.code` — físicos, não a letra impressa, que muda com o
+ * layout ABNT2/US e é a razão de nunca se usar `key` aqui.
+ */
+export declare const KEYBOARD_SOLO: Readonly<Record<Action, Binding<readonly string[]>>>;
+/**
+ * Gamepad, mapa PADRÃO da Gamepad API (`mapping: "standard"`), que é o que um controle de Xbox reporta.
+ * O número é o índice em `gamepad.buttons`.
+ */
+export declare const GAMEPAD_STANDARD: Readonly<Record<Action, Binding<number>>>;
+/**
+ * Todos os problemas de uma tabela de binding. VAZIA quer dizer conforme.
+ *
+ * ⚠️ O QUE ISTO EXISTE PARA APANHAR É O DUPLO, e ele já aconteceu: a especificação chegou com `I` em duas
+ * ações. Um binding duplicado não dá erro em lado nenhum — as duas ações disparam juntas, e a criança vê uma
+ * ação dupla intermitente que ninguém consegue reproduzir de propósito.
+ */
+export declare function bindingProblems<T>(tabela: Readonly<Record<Action, Binding<T | readonly T[]>>>): string[];
+/** As ações que este transporte NÃO alcança. É o que uma tela de seleção precisa dizer ANTES de a criança começar. */
+export declare function unreachable<T>(tabela: Readonly<Record<Action, Binding<T | readonly T[]>>>): Action[];

package/dist-pkg/input/default-bindings.js

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/default-bindings — O QUE CADA TRANSPORTE OFERECE, POR PADRÃO, PARA CADA UMA DAS QUATORZE AÇÕES.
+//
+// ========================= O QUE ISTO É, E ONDE ELE MORA DE PROPÓSITO =========================
+// O ADR-0085 decidiu as quatorze POSIÇÕES (`core/actions.ts`) e disse, em tantas palavras, que os nomes
+// físicos — L1, R2, X, A — são BINDING e vivem no transporte, não no vocabulário. Este é o ficheiro onde eles
+// vivem. Um transporte novo (fala, olhar, toque) traz a sua tabela e não toca em `core/actions`.
+//
+// ⚠️ NADA AQUI ESTÁ LIGADO AINDA. `input/gamepad` e `input/keyboard` continuam a falar os oito nomes de
+// plataforma (`jump`, `run`, `swap`, `especial`); a migração é a issue #103. Esta tabela é o destino dela,
+// escrita agora porque o Dev especificou o padrão — e uma especificação que fica no chat é uma decisão
+// perdida.
+//
+// ========================= A SIMETRIA DO TECLADO, QUE NÃO É DECORAÇÃO =========================
+// O padrão que o Dev especificou apoia-se num bloco do QWERTY:
+//
+//        7  8          ← L1 sobre U, R1 sobre I
+//     Y  U  I  O       ← L2 à esquerda de U, R2 à direita de I
+//     H  J  K  L
+//
+// ⚠️ E O MAPEAMENTO TECLADO↔XBOX É UMA ROTAÇÃO DE 45°, consistente nos quatro: X(oeste)→U(noroeste),
+// Y(norte)→I(nordeste), B(leste)→K(sudeste), A(sul)→J(sudoeste). O losango do controle pousa no quadrado
+// `U I / J K` girando um oitavo de volta. É por isso que a tabela cai bem no dedo: o que a memória muscular
+// guarda é a POSIÇÃO RELATIVA, não a letra.
+//
+// ⚠️ E FOI ESSA SIMETRIA QUE DENUNCIOU UM ERRO NA ESPECIFICAÇÃO. Ela chegou com `I` atribuído DUAS vezes —
+// para `action4` e para R2 —, e o par simétrico de `Y` (à esquerda de U) é `O` (à direita de I). Adotado `O`.
+// O gate deste ficheiro reprova tecla repetida, então o erro não teria passado de qualquer forma; o que a
+// simetria deu foi a tecla CERTA em vez de só a notícia de que havia uma errada.
+import { ACTIONS } from '../core/actions.js';
+// ⚠️ UMA TECLA QUE EXISTE HOJE E NÃO TEM LUGAR NESTA TABELA: `Space`. O esquema solo de `input/keyboard.ts`
+// tem `jump:['KeyJ','Space']` — a barra é um segundo atalho para o pulo desde sempre. A especificação do
+// padrão não a menciona, e pô-la em `action2` por conta própria seria decidir que o pulo mora ali: se o
+// preset da plataforma puser o pulo noutra posição, a barra segue o verbo errado, que é pior do que ela não
+// existir. Fica de fora, dita aqui, e é decisão do Dev — não de quem escreve a tabela.
+/**
+ * Teclado, esquema SOLO. Códigos de `KeyboardEvent.code` — físicos, não a letra impressa, que muda com o
+ * layout ABNT2/US e é a razão de nunca se usar `key` aqui.
+ */
+export const KEYBOARD_SOLO = {
+    up: ['KeyW', 'ArrowUp'],
+    down: ['KeyS', 'ArrowDown'],
+    left: ['KeyA', 'ArrowLeft'],
+    right: ['KeyD', 'ArrowRight'],
+    action1: ['KeyU'],
+    action2: ['KeyJ', 'Space'],
+    action3: ['KeyK'],
+    action4: ['KeyI'],
+    leftShoulder: ['Digit7'], // L1
+    leftTrigger: ['KeyY'], // L2
+    rightShoulder: ['Digit8'], // R1
+    rightTrigger: ['KeyO'], // R2 — ver a nota da simetria acima
+    // ⚠️ E ESTAS DUAS FECHAM UMA DÍVIDA QUE O ADR-0074 §1 REGISTROU: `start` existia em dois transportes de
+    // nove e faltava no teclado. Deixa de faltar. A simetria é de MÃO: `F` fica ao lado do polegar da mão que
+    // se move (o bloco WASD), `H` ao lado da mão que age (o bloco UIJK).
+    // `Enter` acompanha `H` porque JÁ pausava — `input/keydown.ts:240` tem `PAUSE_KEYS = {Escape, Enter}` —,
+    // então declará-lo aqui descreve o que a tecla faz há muito, em vez de lhe dar um trabalho novo.
+    start: ['KeyH', 'Enter'],
+    select: ['KeyF'],
+};
+/**
+ * Gamepad, mapa PADRÃO da Gamepad API (`mapping: "standard"`), que é o que um controle de Xbox reporta.
+ * O número é o índice em `gamepad.buttons`.
+ */
+export const GAMEPAD_STANDARD = {
+    // As direções não vêm de botões: vêm do stick 0/1 e do D-pad 12–15, em `stdDirs`. Declarar `null` aqui
+    // diria "não alcança", que é falso — por isso os índices do D-pad estão nomeados.
+    up: 12,
+    down: 13,
+    left: 14,
+    right: 15,
+    action1: 2, // X
+    action2: 0, // A
+    action3: 1, // B
+    action4: 3, // Y
+    leftShoulder: 4, // L1
+    leftTrigger: 6, // L2 — ⚠️ gatilho ANALÓGICO: a API expõe-no como botão com `.value`, e em alguns
+    //     controles também como eixo. `bindActive` já trata os dois; `padActions` só lê
+    //     `pressed`, o que funciona mas descarta o curso do gatilho.
+    rightShoulder: 5, // R1
+    rightTrigger: 7, // R2 — mesma ressalva analógica
+    start: 9, // Start / Menu
+    select: 8, // Select / Back / View
+};
+/**
+ * Todos os problemas de uma tabela de binding. VAZIA quer dizer conforme.
+ *
+ * ⚠️ O QUE ISTO EXISTE PARA APANHAR É O DUPLO, e ele já aconteceu: a especificação chegou com `I` em duas
+ * ações. Um binding duplicado não dá erro em lado nenhum — as duas ações disparam juntas, e a criança vê uma
+ * ação dupla intermitente que ninguém consegue reproduzir de propósito.
+ */
+export function bindingProblems(tabela) {
+    const p = [];
+    const dono = new Map();
+    for (const acao of ACTIONS) {
+        if (!(acao in tabela)) {
+            p.push(`binding: ${acao} is not declared - write null if the transport cannot reach it`);
+            continue;
+        }
+        const v = tabela[acao];
+        if (v === null)
+            continue;
+        const itens = Array.isArray(v) ? v : [v];
+        if (itens.length === 0) {
+            p.push(`binding: ${acao} has an empty list - write null instead`);
+            continue;
+        }
+        for (const item of itens) {
+            const chave = String(item);
+            const anterior = dono.get(chave);
+            if (anterior)
+                p.push(`binding: ${chave} is bound to both ${anterior} and ${acao}`);
+            else
+                dono.set(chave, acao);
+        }
+    }
+    return p;
+}
+/** As ações que este transporte NÃO alcança. É o que uma tela de seleção precisa dizer ANTES de a criança começar. */
+export function unreachable(tabela) {
+    return ACTIONS.filter((a) => tabela[a] === null || tabela[a] === undefined);
+}

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

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+export declare const PAD_DESIGNS: Record<string, Record<string, string[]>>;
+/**
+ * Glifos de controle que NÃO SE LEEM — chave i18n do nome falado de cada um (ADR-0044, item 4).
+ *
+ * Um leitor de tela lê `✕` como "sinal de multiplicação", ou não lê nada, e `△` costuma sair mudo. É por isso
+ * que a legenda da pausa carregava `aria-hidden="true"`: escondiam-se o ruído E a informação juntos. Aqui está
+ * a metade que faltava para poder tirar o atributo — o glifo continua na tela para quem o reconhece, e a
+ * PALAVRA existe para quem o escuta.
+ *
+ * Só os quatro do PlayStation entram. `A`, `B`, `X`, `Y` e `0`–`3` já se leem, e traduzi-los para "letra A"
+ * seria acrescentar ruído em nome de acessibilidade — o defeito que este item conserta pelo avesso.
+ */
+export declare const PAD_GLYPH_SPOKEN: Record<string, string>;
+export declare const TOUCH_DEFAULT: Record<string, string>;

package/dist-pkg/input/devices.js

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/devices.ts — rótulos/mapeamentos de gamepad e toque (dados). Módulo-folha, ZERO deps.
+// PAD_DESIGNS: como rotular os 4 botões de ação por modelo de controle (o navegador detecta genérico no
+// Windows). TOUCH_DEFAULT: mapa padrão dos 9 slots de toque.
+// A leitura de pads (pollPads) e o layout de toque ficam no game.js. (Fase 2, subsistema input)
+//
+// POR QUE CHAVES E NÃO TEXTO: a tabela é uma `const` de módulo, avaliada UMA vez no import. Se guardasse
+// `t('…')` já resolvido, o idioma congelaria no boot — `dict` em core/i18n é um `let` que `setLocale`
+// reatribui, e quem leu antes da troca nunca mais vê a troca. Guardando a chave, quem resolve é o ponto de
+// Este módulo continua ZERO deps de propósito: chave é dado, `t` é comportamento e mora no consumidor.
+export const PAD_DESIGNS = {
+    generic: { '0': ['0', '#3a4a6a'], '1': ['1', '#3a4a6a'], '2': ['2', '#3a4a6a'], '3': ['3', '#3a4a6a'] },
+    microsoft: { '0': ['A', '#2fae4e'], '1': ['B', '#d23b3b'], '2': ['X', '#2f6fd2'], '3': ['Y', '#d9a400'] },
+    sony: { '0': ['✕', '#4f8fd0'], '1': ['○', '#d23b3b'], '2': ['□', '#d76fae'], '3': ['△', '#2fae7e'] },
+    nintendo: { '0': ['B', '#d9a400'], '1': ['A', '#d23b3b'], '2': ['Y', '#2fae4e'], '3': ['X', '#2f6fd2'] },
+};
+/**
+ * Glifos de controle que NÃO SE LEEM — chave i18n do nome falado de cada um (ADR-0044, item 4).
+ *
+ * Um leitor de tela lê `✕` como "sinal de multiplicação", ou não lê nada, e `△` costuma sair mudo. É por isso
+ * que a legenda da pausa carregava `aria-hidden="true"`: escondiam-se o ruído E a informação juntos. Aqui está
+ * a metade que faltava para poder tirar o atributo — o glifo continua na tela para quem o reconhece, e a
+ * PALAVRA existe para quem o escuta.
+ *
+ * Só os quatro do PlayStation entram. `A`, `B`, `X`, `Y` e `0`–`3` já se leem, e traduzi-los para "letra A"
+ * seria acrescentar ruído em nome de acessibilidade — o defeito que este item conserta pelo avesso.
+ */
+export const PAD_GLYPH_SPOKEN = {
+    '✕': 'pad.glyph.cross', '○': 'pad.glyph.circle', '□': 'pad.glyph.square', '△': 'pad.glyph.triangle',
+};
+export const TOUCH_DEFAULT = { up: 'up', down: 'down', left: 'left', right: 'right', start: 'start', b0: 'action2', b1: 'action3', b2: 'action1', b3: 'action4' };

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

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** As seis bordas de entrada, pelo nome do campo que elas levantam no jogador. */
+export type EdgeFlag = 'jumpEdge' | 'runEdge' | 'leftEdge' | 'rightEdge' | 'swapEdge' | 'specialEdge';
+/** As seis ações que levantam borda. Nomeado (e não `string`) para o compilador casar com o `ActionKey` de
+ *  input/gamepad, que é quem lê a tabela passando a ação adiante. */
+export type EdgeAction = 'action2' | 'action1' | 'left' | 'right' | 'action4' | 'action3';
+/** Ação → borda, na ORDEM em que os três caminhos as levantam. */
+export declare const EDGE_BY_ACTION: ReadonlyArray<readonly [EdgeAction, EdgeFlag]>;
+/**
+ * Este jogador pode levantar a borda desta ação?
+ *
+ * Hoje há uma regra só, e ela é de acessibilidade: no modo Fácil o `run` não levanta borda — sem correr, e
+ * portanto sem escalada de parede. Vale para teclado, controle e toque, que é justamente o ponto.
+ * Se um dia houver uma segunda regra, ela entra AQUI e passa a valer nos três de uma vez.
+ */
+export declare function edgeAllowed(action: EdgeAction, easy: boolean | undefined): boolean;
+/**
+ * As seis intenções de navegação de menu — a mesma história das bordas, um andar acima.
+ *
+ * Estava declarada QUATRO vezes: `input/gamepad`, `ui/menu-nav`, `ui/activities-menu` e, sob o nome
+ * `TitleNav`, `input/keydown`. Três delas traziam um comentário dizendo "MESMA forma que…", que é uma cópia
+ * pedindo para ser notada. E já tinham divergido: a de `ui/activities-menu` declarava os seis campos
+ * OPCIONAIS e as outras três, obrigatórios — de modo que `navTitle` aceitava `{}` enquanto quem a alimenta
+ * sempre manda os seis.
+ *
+ * Mora em `input/` porque é uma intenção de ENTRADA: quem a produz são os tradutores (teclado, controle,
+ * toque, e amanhã voz e webcam) e quem a consome é a UI. `input/` nunca importa de `ui/`; `ui/` já importa de
+ * `input/devices`. A direção é essa.
+ *
+ * OPCIONAIS de propósito, ao contrário das bordas: um tradutor manda só o que aconteceu. `{ down: true }` é
+ * uma frase completa — "para baixo" —, e obrigar os outros cinco `false` faria cada chamada carregar cinco
+ * negações que ninguém lê. É a forma que `ui/activities-menu` já usava, e é a certa; o que estava errado era
+ * as outras três discordarem dela.
+ */
+export interface NavKeys {
+    up?: boolean;
+    down?: boolean;
+    left?: boolean;
+    right?: boolean;
+    /** Confirmar / entrar. */
+    yes?: boolean;
+    /** Voltar / cancelar. */
+    no?: boolean;
+}
+/**
+ * Alguma intenção foi expressa neste quadro? Sem intenção, a tecla NÃO é consumida — nem `preventDefault`,
+ * nem `stopPropagation`, nem `navTitle`.
+ *
+ * Estava escrita DUAS vezes, com o mesmo corpo e nomes diferentes: `hasIntent` em `ui/menu-nav` e
+ * `hasTitleIntent` em `input/keydown`. Quase deixei as duas onde estavam, no raciocínio de que mover o tipo
+ * para cá e criar uma função nova seria trocar seis por meia dúzia — o raciocínio estava certo e o número,
+ * errado: não era uma cópia, eram duas, e o canônico apaga as duas. Os dois módulos reexportam com o nome
+ * que os chamadores e os testes deles já usam.
+ *
+ * O `!!` importa: com os campos opcionais, a cadeia de `||` devolve `boolean | undefined`. Foi o compilador
+ * que apontou, ao estreitar o tipo — as duas funções vinham devolvendo `undefined` como se fosse `false`.
+ */
+export declare function hasNavIntent(k: NavKeys): boolean;

package/dist-pkg/input/edges.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/edges — a tabela "ação → borda de entrada", e a regra de quem pode levantá-la. Módulo FOLHA: zero
+// imports, nada de DOM, nada de estado.
+//
+// POR QUE ISTO EXISTE COMO MÓDULO
+// Uma "borda" é o instante em que o jogador ACABOU de acionar algo — `jumpEdge`, `runEdge`, `leftEdge`… — em
+// oposição a manter pressionado. Quem levanta borda são os três caminhos de entrada, e cada um tinha a sua
+// própria cópia da mesma tabela: `input/keydown.ts`, `input/gamepad.ts` (seis `if` à mão) e
+// `input/touch-bindings.ts`. Três cópias que precisavam concordar, e nada obrigando.
+//
+// Elas divergiram. A cópia do toque não tinha a guarda do modo Fácil, e como `runEdge` NÃO é a velocidade de
+// corrida — é o gatilho que gruda e solta da parede, a escalada tipo aranha de `updateCling` em
+// `game/physics.ts:177` e `:179` — o resultado foi que a criança em modo Fácil (que existe para dificuldade
+// motora) não conseguia escalar com teclado nem com controle, e conseguia com o botão da tela. No tablet de
+// escola pública, o toque não é o caminho alternativo: é o único. O sintoma foi corrigido antes deste módulo;
+// este módulo é o que impede a divergência de voltar, porque agora só há um lugar onde ela poderia morar.
+//
+// A ORDEM DA TABELA É OBSERVÁVEL: `edgesFor` devolve a lista na ordem em que percorre, e há teste ancorando-a.
+/** Ação → borda, na ORDEM em que os três caminhos as levantam. */
+export const EDGE_BY_ACTION = Object.freeze([
+    ['action2', 'jumpEdge'], ['action1', 'runEdge'], ['left', 'leftEdge'],
+    ['right', 'rightEdge'], ['action4', 'swapEdge'], ['action3', 'specialEdge'],
+]);
+/**
+ * Este jogador pode levantar a borda desta ação?
+ *
+ * Hoje há uma regra só, e ela é de acessibilidade: no modo Fácil o `run` não levanta borda — sem correr, e
+ * portanto sem escalada de parede. Vale para teclado, controle e toque, que é justamente o ponto.
+ * Se um dia houver uma segunda regra, ela entra AQUI e passa a valer nos três de uma vez.
+ */
+export function edgeAllowed(action, easy) {
+    return !(action === 'action1' && !!easy);
+}
+/**
+ * Alguma intenção foi expressa neste quadro? Sem intenção, a tecla NÃO é consumida — nem `preventDefault`,
+ * nem `stopPropagation`, nem `navTitle`.
+ *
+ * Estava escrita DUAS vezes, com o mesmo corpo e nomes diferentes: `hasIntent` em `ui/menu-nav` e
+ * `hasTitleIntent` em `input/keydown`. Quase deixei as duas onde estavam, no raciocínio de que mover o tipo
+ * para cá e criar uma função nova seria trocar seis por meia dúzia — o raciocínio estava certo e o número,
+ * errado: não era uma cópia, eram duas, e o canônico apaga as duas. Os dois módulos reexportam com o nome
+ * que os chamadores e os testes deles já usam.
+ *
+ * O `!!` importa: com os campos opcionais, a cadeia de `||` devolve `boolean | undefined`. Foi o compilador
+ * que apontou, ao estreitar o tipo — as duas funções vinham devolvendo `undefined` como se fosse `false`.
+ */
+export function hasNavIntent(k) {
+    return !!(k.yes || k.no || k.up || k.down || k.left || k.right);
+}

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

@@ -0,0 +1,203 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { PlayerView } from '../core/entity.js';
+export interface PadButtonLike {
+    pressed: boolean;
+}
+export interface PadLike {
+    id: string;
+    index: number;
+    mapping: string;
+    buttons: readonly (PadButtonLike | null | undefined)[];
+    axes: readonly number[];
+}
+/** Adapter for `navigator.getGamepads()` — the DI point that lets tests feed a fake pad without a browser. */
+export type GetGamepads = () => readonly (PadLike | null | undefined)[] | null | undefined;
+export type { DomQuery } from '../core/dom-query.js';
+/** One binding captured by the wizard: a digital button, a signed analog threshold, or an exact hat/POV value.
+ *  Loosely-shaped (all fields optional) rather than a strict union: bindings round-trip through JSON in
+ *  localStorage, so `bindActive` must stay defensive against malformed/partial saved data, same as the original. */
+export interface PadBinding {
+    b?: number;
+    ax?: number;
+    s?: number;
+    av?: number;
+    v?: number;
+}
+/** action -> binding, keyed by the 9 wizard steps (left/right/up/down/jump/run/swap/especial/start), PLUS the
+ *  `_skip: true` sentinel meaning "user cancelled the wizard for this model — use the default mapping, don't
+ *  ask again this session" (not persisted). A flat index signature (not `Partial<Record<..>> & {_skip}`) so the
+ *  boolean `_skip` and the PadBinding action values can coexist under TS's index-signature rule; `bindingAt`
+ *  narrows a lookup back down to a PadBinding for `bindActive`. */
+export type PadMap = Record<string, PadBinding | boolean | undefined>;
+export type ActionKey = 'left' | 'right' | 'up' | 'down' | 'action2' | 'action1' | 'action4' | 'action3';
+export interface Dirs {
+    left: boolean;
+    right: boolean;
+    up: boolean;
+    down: boolean;
+}
+export interface PadActions extends Dirs {
+    [key: string]: boolean;
+    action2: boolean;
+    action1: boolean;
+    action4: boolean;
+    action3: boolean;
+    _start: boolean;
+    _pause: boolean;
+}
+/** Direções pelas FONTES PADRÃO: stick 0/1 (zona morta PAD_DEAD), D-pad 12-15, e o "hat" nos eixos >=6 (POV do
+ *  DirectInput). Controles com os dois direcionais mapeados ficam com ambos vivos (dedo no stick não mata o D-pad). */
+export declare function stdDirs(gp: PadLike): Dirs;
+/** Está o binding `bd` ativo agora neste gamepad? Digital = pressed; analógico ({ax,s}) = limiar por sinal
+ *  (metade do curso); hat ({av,v}) = valor exato do passo (±0.13 — os 8 passos distam ~0.286). */
+export declare function bindActive(gp: PadLike, bd: PadBinding | null | undefined): boolean;
+/** Ações do frame para este gamepad. `custom` = mapa salvo pelo wizard para este `gp.id` (null/`_skip` = usa o
+ *  mapa PADRÃO da Gamepad API "standard": 0=pulo · 1=especial · 2/5/7=correr · 3=troca · 9=START). Direções
+ *  custom caem de volta em stdDirs quando o binding do usuário não está ativo (D-pad/stick continuam vivos). */
+export declare function padActions(gp: PadLike, custom: PadMap | null): PadActions;
+/**
+ * A ORDEM em que o assistente pergunta. SÓ a ordem.
+ *
+ * ⚠️ ELA CARREGAVA AS PALAVRAS, EM PORTUGUÊS CRU, DENTRO DA ENGINE: `['action2', 'PULAR']`,
+ * `['action1', 'CORRER / INTERAGIR']`. Era o defeito do ADR-0074 na sua forma mais visível — não só
+ * vocabulário de plataforma dentro do motor, mas vocabulário de plataforma NUM IDIOMA SÓ, à frente de uma
+ * criança, num ficheiro que o pilar 3 obriga a ser localizável.
+ *
+ * A palavra vem agora de `ctx.rotuloDaAcao`, que o jogo fornece pelo seu preset. Aqui fica o que é mesmo da
+ * engine: a sequência em que se pergunta — direções primeiro, ação depois, sistema no fim —, que é uma
+ * decisão de ergonomia do assistente e não do jogo.
+ *
+ * ⚠️ E UMA AÇÃO QUE O JOGO NÃO NOMEIA NÃO É PERGUNTADA. `wizPrompt` salta-a, porque um jogo que não usa a
+ * posição não tem o que mapear nela — e perguntar produziria um passo mudo, ou pior, um passo a dizer
+ * `action7` em voz alta.
+ */
+export declare const PADWIZ_ORDER: readonly string[];
+export interface WizAnimDef {
+    seq?: string[];
+    hold?: number;
+    cls: string;
+    fx?: string;
+    noimg?: number;
+    flip?: number;
+}
+/** Demonstração animada de cada ação (frames reais do jogo) mostrada durante o passo correspondente do wizard. */
+export declare const PADWIZ_ANIM: Record<string, WizAnimDef>;
+interface WizBase {
+    b: boolean[];
+    a: number[];
+}
+interface WizAxTrack {
+    i: number;
+    v: number;
+    last: number;
+    changes: number;
+    ticks: number;
+}
+/** Estado do wizard em andamento; `null` = fechado. Espelha o `padWiz` do game.js. */
+export interface WizState {
+    gi: number;
+    id: string;
+    step: number;
+    base: WizBase | null;
+    map: PadMap;
+    release: boolean;
+    baseWait: boolean;
+    axTrack: WizAxTrack | null;
+    timer: ReturnType<typeof setInterval> | null;
+}
+import type { NavKeys } from './edges.js';
+import type { ModalIntent } from './keydown.js';
+import type { DomQuery } from '../core/dom-query.js';
+export type { NavKeys } from './edges.js';
+/** Forma mínima de jogador que este módulo lê/escreve — DERIVADA de core/entity, não redigitada.
+ *  (`quiz` SAIU em 2026-08-25 — ADR-0033. Era `{ kind: string } | null` aqui e `{ kind?: string } | null` no
+ *  keydown, o mesmo objeto do JOGO com o discriminante obrigatório num módulo e opcional no outro. Hoje
+ *  nenhum dos dois o lê: a pergunta é `ctx.hasModal(i)` e a resposta é uma INTENÇÃO.) */
+export type GamepadPlayer = PlayerView<'pad' | 'quit' | 'waiting' | 'easy' | 'jumpEdge' | 'runEdge' | 'leftEdge' | 'rightEdge' | 'swapEdge' | 'specialEdge'>;
+export interface GamepadCtx {
+    /** Adaptador da Gamepad API (substitui `navigator.getGamepads()`) — o ponto de DI para testar sem browser. */
+    getGamepads: GetGamepads;
+    /** Seletor DOM (querySelector), injetado — nunca alcança `document` global. */
+    $: DomQuery;
+    /**
+     * COMO SE CHAMA esta posição, na palavra do JOGO e no idioma vigente. `null` = o jogo não a usa.
+     *
+     * ⚠️ É a fronteira do corte de 2026-09-06 em forma de campo: a engine sabe que existe uma posição,
+     * só o jogo sabe a palavra. Antes desta linha o assistente dizia «PULAR» a partir de uma constante
+     * deste ficheiro — em português, sem passar por `t()`, dentro do motor.
+     */
+    rotuloDaAcao: (acao: string) => string | null;
+    /** Anúncios de leitor de tela (core/a11y-sr), injetados. */
+    srSay: (msg: string) => void;
+    srAlert: (msg: string) => void;
+    /** Traz um overlay para frente + preenche o texto de ajuda (game.js's frontOverlay, compartilhado por todo overlay). */
+    frontOverlay: (el: HTMLElement | null) => void;
+    /** O mundo está rodando? (START aqui PAUSA.) */
+    mundoRodando: () => boolean;
+    /** O menu de pausa está aberto? (START aqui RETOMA.) */
+    menuDePausa: () => boolean;
+    /** Pausar e retomar. Quem empilha a cena é a raiz; daqui sai só a intenção. */
+    pausar: () => void;
+    retomar: () => void;
+    /** Modo demonstração (attract) — game.js's attractCtl. */
+    isAttractActive: () => boolean;
+    stopAttract: () => void;
+    /** Controles virtuais de toque — somem no primeiro input físico. */
+    isTouchMode: () => boolean;
+    hideTouchControls: () => void;
+    /** Estado vivo de jogadores/telas (core/state.ts, injetado como getter — nunca cacheado por este módulo). */
+    getPlayers: () => GamepadPlayer[];
+    getNumPlayers: () => number;
+    /** Navegação de menus (game.js): título, diálogo compartilhado (o de cima), e a pausa por tela. */
+    navTitle: (k: NavKeys) => void;
+    /** A tela `i` está no modo `accessibility`? (ADR-0044, item 7 — o direcional dirige a barra do HUD.) */
+    naBarraDe: (i: number) => boolean;
+    /** Um passo dentro da barra. `temStart` é a borda do botão de pausa, que é a SEGUNDA saída do modo. */
+    navBar: (i: number, k: NavKeys, temStart: boolean) => void;
+    sharedDialogOpen: () => HTMLElement | null;
+    navDialog: (dlg: HTMLElement, k: NavKeys) => void;
+    /** A tela de pausa do jogador. `HTMLElement` e não `{ hidden: boolean }`: o mínimo estrutural funciona
+     *  para LER, mas este módulo REPASSA o menu para `navPause`, que precisa do elemento inteiro — e em
+     *  posição de parâmetro a fatia mínima se inverte (ADR-0039). Mesma lição do `held` em audio-nav. */
+    getPauseMenu: (playerIndex: number) => HTMLElement | null | undefined;
+    navPause: (menu: HTMLElement, playerIndex: number, k: NavKeys) => void;
+    /** Qual jogador abre o submenu de a11y em seguida (game.js's `pauseActor`). */
+    setPauseActor: (playerIndex: number) => void;
+    /**
+     * MODAL do PRÓPRIO jogador: a engine entrega a INTENÇÃO, o jogo decide (ADR-0033).
+     *
+     * Eram quatro — `quizMove(p, delta)`, `quizConfirm`, `quizErase`, `announceBraille` — e as quatro existiam
+     * porque a decisão de qual chamar morava aqui, com a grade de três colunas e o desvio de Braille. O pad e
+     * o teclado tinham CÓPIAS dessa mesma decisão, o que é a pior forma de tê-la: duas para divergir.
+     */
+    /** O ÍNDICE do jogador, não o jogador (ADR-0033/0039): a engine entrega intenção e não precisa saber o
+     *  que é um jogador com desafio aberto. Quem resolve o índice é o dono do desafio. */
+    modalInput: (playerIndex: number, intent: ModalIntent) => void;
+    /** Este jogador tem um modal aberto? Uma pergunta, e não o objeto do jogo. */
+    hasModal: (playerIndex: number) => boolean;
+    /** Entra num jogo em andamento com uma tela nova (game.js's joinPlayer). */
+    joinPlayer: (padIndex: number) => boolean;
+    /** Recomeça só a tela deste jogador (game.js's respawnPlayer). */
+    respawnPlayer: (playerIndex: number) => void;
+    /** Remove o selo "aguardando" da tela quando ela ganha um controle (parte do HUD, game.js). */
+    clearWaitingBadge: (playerIndex: number) => void;
+    /**
+     * Caminho-base dos sprites usado pela demo animada do wizard. NOTA — bug encontrado, não corrigido: o
+     * game.js original referencia um identificador `SPR` que NUNCA é declarado/importado ali (só existe, sem
+     * export, em render/sprites.ts) — `padWizDemo`/`padWizDemoTick` lançam ReferenceError em runtime assim que
+     * o wizard mostra qualquer demonstração animada (inclusive ao abrir: `padWizDemo(null)` já cai no ramo que lê
+     * `SPR`). Fica como dependência EXPLÍCITA aqui em vez de reproduzir o global inexistente — ver retorno da tarefa.
+     */
+    spriteBase: string;
+}
+export interface GamepadApi {
+    pollPads(): void;
+    openPadWiz(): void;
+    openPadWizFor(gp: PadLike): void;
+    closePadWiz(save: boolean): void;
+    padWizTick(): void;
+    padMapFor(id: string): PadMap | null;
+    /** Estado vivo do wizard (para expor via `get padWiz(){}` no window.__incl, como o game.js original). */
+    getPadWiz(): WizState | null;
+}
+export declare function initGamepad(ctx: GamepadCtx): GamepadApi;