@the-inclusionist/engine 8.0.0 → 10.0.0

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

@@ -1,44 +1,44 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
 import type { PlayerView } from '../core/entity.js';
 import { type EdgeFlag } from './edges.js';
-/** ui/dom.ts `$` — injetado; o módulo nunca alcança `document`. */
+/** ui/dom.ts `$` — injected; the module never reaches `document`. */
 export type { DomQuery } from '../core/dom-query.js';
-/** O que este módulo lê e faz com um `KeyboardEvent` de `keydown`. */
+/** What this module reads and does with a `keydown` `KeyboardEvent`. */
 export interface KeydownEventLike {
     code: string;
     altKey: boolean;
     ctrlKey: boolean;
     preventDefault(): void;
     /**
-     * O navegador viu a pessoa carregar? (ADR-0109) — OPCIONAL, e a opcionalidade é a decisão.
+     * Did the browser see the person press? (ADR-0109) — OPTIONAL, and the optionality is the decision.
      *
-     * ⚠️ Torná-lo obrigatório partiria todos os duplos de teste que já existem, e partiria-os por uma razão
-     * falsa: eles descrevem a decisão de teclado, que não depende disto. O que a ausência significa está
-     * escrito no `input/origem-sintetica` — «não afirmei nada», cuja resposta é `undefined` e não `'teclado'`.
+     * ⚠️ Making it required would break every existing test double, for a false reason: they describe the keyboard
+     * decision, which does not depend on this. What the absence means is written in `input/synthetic-source` — "I
+     * asserted nothing", whose answer is `undefined` and not `'teclado'`.
      */
     isTrusted?: boolean;
 }
-/** `keyup` só precisa do código. */
+/** `keyup` only needs the code. */
 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). */
+/** action -> list of physical codes. */
 export type { KeyScheme } from '../core/entity.js';
-/** As seis bordas de entrada que o keydown levanta no jogador (consumidas e zeradas pela física). */
+/** The six input edges keydown raises on the player (consumed and cleared by the game's physics). */
 /**
- * O que este módulo lê (e escreve) de um jogador — e SÓ isso. DERIVADA de core/entity.
+ * What this module reads (and writes) of a player — and ONLY that. DERIVED from 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.
+ *  · `i`        — the player's OWN index. Routing goes by it, not by the position in the array.
+ *  · `ctrl`     — the key scheme; `null` before assignControls.
+ *  (There is no `quiz` — ADR-0033. The open challenge arrives through `modalOpen` in the snapshot, and what the key
+ *   MEANS inside it is the game's decision. See the "MODAL" block below.)
+ *  · `waiting`  — a screen on standby (multi-screen): THAT player's 1st key joins the match.
+ *  · `easy`     — Easy mode (motor difficulty): no running, and the Ctrl/Shift shortcuts in 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). */
+/** The subset of input/keyboard-runtime.ts's `ControlsState` the decision consults (`controls` stays out: only the six
+ *  aliases and the flattened list are used here). */
 export interface ControlsSnapshot {
     action2: string[];
     left: string[];
@@ -48,38 +48,37 @@ export interface ControlsSnapshot {
     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. */
+/** The title menu's navigation intent — `NavKeys` from input/edges, re-exported under the name this module's callers
+ *  already use (it was a fourth structural copy under another name). */
 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. */
+/** EVERYTHING the decision needs to know about the world, in one object, built BEFORE any effect. */
 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;
+    /** Is the title screen on top? (Only Player 1 picks the game; the others hear a notice.) */
+    titleScreen: boolean;
+    /** Is a game in progress — running OR paused? (Alt+N and the pause key need this, and no modal open.) */
+    inGame: boolean;
     numPlayers: number;
     players: readonly KeydownPlayer[];
     /**
-     * Há MODAL aberto para o jogador de cada POSIÇÃO? — a resposta, ao lado dos jogadores (ADR-0033).
+     * Is a MODAL open for the player at each POSITION? — the answer, beside the players (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.
+     * Not `players[i].quiz`: reading that field would force `core/entity.Player` — the ENGINE's canonical entity — to
+     * DECLARE it, and every game in the catalogue to have a "quiz" of that shape.
      *
-     * 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.
+     * Why here and not two ctx functions: this module already builds a snapshot before any effect, and adding ctx to
+     * whoever has a snapshot is one more piece. Why a PARALLEL array and not a field on `KeydownPlayer`: that type is a
+     * `PlayerView<>` derived from `Player`, so the field would be required on the entity again — a better name, the same
+     * wrong place. And why not wrap the players in a copy: this module WRITES into them (the six edges), and a copy would
+     * lose the write.
      */
     modalOpen: readonly boolean[];
     controls: ControlsSnapshot;
-    /** `keys` de input/state.ts: as teclas seguradas AGORA (inclui códigos injetados por toque/webcam). */
+    /** input/state.ts's `keys`: the keys held NOW (every transport's, mixed). */
     heldKeys: ReadonlySet<string>;
-    /** empatia motora: um botão de jogo por vez. */
+    /** motor empathy: one game button at a time. */
     oneButton: boolean;
-    /** `overlays.escapeTarget()` — id do 1º diálogo REGISTRADO que está aberto, ou null. */
+    /** `overlays.escapeTarget()` — the id of the 1st REGISTERED dialog that is open, or null. */
     escapeTargetId: string | null;
     touchCfgVisible: boolean;
     padWizVisible: boolean;
@@ -88,66 +87,66 @@ export interface KeydownSnapshot {
     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. */
+/** An edge to raise: which player (POSITION in the array) and which 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.
+ * The single answer: what this key MEANS. `kind` is the precedence branch that won — and it is that word, not the
+ * effect, that the precedence tests assert.
  */
 export type KeydownDecision = 
-/** 1º · diálogo REGISTRADO aberto: Escape fecha (`closeId`), qualquer outra tecla é engolida. */
+/** 1st · a REGISTERED dialog open: Escape closes (`closeId`), any other key is swallowed. */
 {
     kind: 'overlay';
     closeId: string | null;
     preventDefault: boolean;
 }
-/** 2º · `#touchcfg` visível: Escape esconde, o resto é engolido. */
+/** 2nd · `#touchcfg` visible: Escape hides, the rest is swallowed. */
  | {
     kind: 'touchcfg';
     close: boolean;
     preventDefault: boolean;
 }
-/** 3º · `#padwiz` (assistente de gamepad) visível: Escape CANCELA (`save:false`), o resto é engolido. */
+/** 3rd · `#padwiz` (the pad wizard) visible: Escape CANCELS (`save:false`), the rest is swallowed. */
  | {
     kind: 'padwiz';
     close: boolean;
     preventDefault: boolean;
 }
-/** 4º · tela de vitória: pulo (de qualquer jogador) ou Escape/Enter apertam "Jogar de novo". */
+/** 4th · win screen: jump (any player's) or Escape/Enter press "Play again". */
  | {
     kind: 'win';
     again: boolean;
     preventDefault: boolean;
 }
-/** 5º · tela de título: `wait` = multi-tela e a tecla é de outro jogador (só o J1 comanda). */
+/** 5th · title screen: `wait` = multi-screen and the key is another player's (only P1 commands). */
  | {
     kind: 'title';
     wait: boolean;
     nav: TitleNav | null;
     preventDefault: boolean;
 }
-/** 6º · Alt+1..4 = número de telas. */
+/** 6th · Alt+1..4 = number of screens. */
  | {
     kind: 'screens';
     count: number;
     preventDefault: boolean;
 }
-/** 7º · Escape/Enter = pausa. */
+/** 7th · Escape/Enter = pause. */
  | {
     kind: 'pause';
     preventDefault: boolean;
 }
-/** 8º · modal aberto: a tecla age no modal do DONO dela (`playerIndex` = posição no array). */
+/** 8th · a modal open: the key acts on its OWNER's modal (`playerIndex` = position in the array). */
  | {
     kind: 'modal';
     playerIndex: number;
     intent: ModalIntent | null;
     preventDefault: boolean;
 }
-/** 9º · jogo normal. */
+/** 9th · normal play. */
  | {
     kind: 'play';
     gameKey: boolean;
@@ -156,153 +155,146 @@ export type KeydownDecision =
     releaseKeys: string[];
     preventDefault: boolean;
 };
-/** Fácil (SOLO): Ctrl = Especial, Shift = Trocar poder. Fora de Win/Alt/AltGr, de propósito. */
+/** Easy (SOLO): Ctrl = Special, Shift = Swap power. Not Win/Alt/AltGr, on purpose. */
 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. */
+/** Alt + the digit row (NOT the numeric keypad) = 1..4 screens. Alt is free: solo does not use it. */
 export declare const SCREEN_DIGITS: RegExp;
-/** Pausa: Escape ou o Enter CENTRAL. `NumpadEnter` NÃO pausa (E14, verbatim). */
+/** Pause: Escape or the MAIN Enter. `NumpadEnter` does NOT pause. */
 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). */
+/** Does the key count as JUMP for anybody? P1's alias OR any player's `action2` (it is what makes "anyone can press
+ *  Play again" and "anyone confirms on the title" true). */
 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). */
+/** Is the key a GAME key? The flattened alias OR some player's scheme. It does NOT include the Easy shortcuts: those
+ *  are added apart (`isEasyShortcut`). */
 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. */
+/** Easy's accessibility shortcuts exist only in SOLO (`numPlayers<=1`) and only for Player 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.
+ * The title menu intent. Note the ASYMMETRY, kept as it is: `up`/`down` accept ArrowUp/ArrowDown ON TOP of the
+ * configured alias, `left`/`right` do not accept ArrowLeft/ArrowRight. It does not show in the factory scheme (solo
+ * already has the arrows on all four sides); it shows for whoever REMAPS — remap left to KeyA and the arrow stops moving
+ * in the menu, while up keeps working both ways. It is a test case in tests/keydown.node.test.js, and a candidate for a
+ * fix, not for a silent "cleanup".
  */
 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';
-import type { Transporte } from './transporte-em-uso.js';
+import type { TransportName } from './transport-in-use.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.
+ * Who owns the modal this key commands? Returns the POSITION in the array, or -1.
+ * A player's key goes to THAT player's modal (and only if they have one open); a generic key falls to Player 1. A key of
+ * a player WITHOUT an open modal does not fall to P1 — it goes down to normal play, which is what lets their match go on
+ * while the other solves the challenge.
  */
 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.
+ * The edges this key raises. It is only called when the key is NOT YET held — that is what makes it an EDGE and not a
+ * state, and what keeps the system's auto-repeat from becoming ten jumps.
+ * `p.ctrl[act] || []`: a scheme without the action turns a TypeError into a no-op (the precedent is `navPause`'s guard
+ * in ui/menu-nav.ts) — a net that removes no chance of a fix.
  */
 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: {
+/** The event as the chain reads it. */
+type KeyEventFacts = {
     code: string;
     altKey?: boolean;
     ctrlKey?: boolean;
-}, s: KeydownSnapshot): KeydownDecision;
+};
+/**
+ * THE CHAIN. Nine questions, in this order — and the order IS the specification.
+ * What is NOT here, and comes first in the wrapper: the demo (attract) and the remapping capture. See the header.
+ */
+export declare function decideKeydown(ev: KeyEventFacts, s: KeydownSnapshot): KeydownDecision;
 export interface KeydownCtx {
-    /** game/attract.ts: zera a ociosidade e encerra a demo; `true` = a tecla foi só para acordar. */
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    /** The demo: resets idleness and ends the demo; `true` = the key was only to wake it up. */
     attractOnInput: () => boolean;
-    /** ui/settings-controls.ts: remapeamento em curso — a próxima tecla VIRA o controle. */
+    /** ui/settings-controls.ts: a remap in progress — the next key BECOMES the control. */
     handleCaptureKeydown: (e: KeydownEventLike) => boolean;
-    /** Os dois fatos da cena. Ver `KeydownSnapshot`: booleanos, nunca a fase. */
-    isTelaDeTitulo: () => boolean;
-    isEmJogo: () => boolean;
+    /** The scene's two facts. See `KeydownSnapshot`: booleans, never the phase. */
+    isTitleScreen: () => boolean;
+    isInGame: () => boolean;
     getNumPlayers: () => number;
     getPlayers: () => readonly KeydownPlayer[];
-    /** `kbRuntime.controlsState()` — memorizado do lado de lá; uma chamada por tecla, como no original. */
+    /** The keyboard runtime's `controlsState()` — memoised over there; one call per key. */
     getControls: () => ControlsSnapshot;
     /**
-     * O PAR DE `input/state`, E NÃO O CONJUNTO CRU (ADR-0109) — o mesmo corte que o `input/touch-bindings` fez.
+     * THE `input/state` DOORS, NOT THE RAW SET (ADR-0109) — the same cut `input/touch-bindings` made.
      *
-     * ⚠️ `ReadonlySet` e não `Set`, e a diferença É a razão de o par existir: LER o conjunto nunca foi o
-     * problema; ESCREVER nele apagava a origem. Com o tipo assim, uma escrita crua deixa de compilar — o crivo
-     * do inventário passa a ter o compilador do lado dele, em vez de ser a única coisa a segurar a linha.
+     * ⚠️ `ReadonlySet` and not `Set`, and the difference IS why the doors exist: READING the set was never the problem;
+     * WRITING into it erased the source. With the type like this, a raw write stops compiling — the inventory gate has the
+     * compiler on its side instead of being the only thing holding the line.
      */
     readonly heldKeys: ReadonlySet<string>;
-    /** Uma tecla foi segurada, e sabe-se por quem. */
-    marcarTecla: (code: string, origem: Transporte) => void;
+    /** A key was held, and who pressed it is known. */
+    markKey: (code: string, origin: TransportName) => void;
     /**
-     * Uma tecla foi segurada e NÃO se sabe por quem — o evento sintético que ninguém assinou.
+     * A key was held and who pressed it is NOT known — an event nobody signed, which every real key is.
      *
-     * ⚠️ Está no ctx a par das outras duas de propósito: se fosse importada, um consumidor não teria como ver
-     * que ela existe, e é justamente ele quem produz os eventos que caem aqui.
+     * ⚠️ It sits in the ctx beside the other two on purpose: imported, a consumer would have no way to see it exists, and
+     * the consumer is exactly who produces the events that land here.
      */
-    marcarTeclaSemOrigem: (code: string) => void;
+    markKeyWithoutSource: (code: string) => void;
     /**
-     * ESTA ARESTA É DESTE JOGADOR, E VEIO DAQUI (ADR-0113 cláusula 4, issue #127) — `input/state.arestaDoJogador`.
+     * THIS EDGE IS THIS PLAYER'S, AND IT CAME FROM HERE (ADR-0113 clause 4, issue #127) — `input/state.playerEdge`.
      *
-     * 🔴 CAMPO OBRIGATÓRIO, e a medição é a razão: em 2026-09-09 o autómato do ADR-0109 tinha ZERO alimentadores
-     * em produção, logo `entradaDe(i).emUso` respondia `teclado` a toda a gente — para sempre, e sem erro
-     * nenhum. Com isso, a recusa da cláusula 3 nunca dispara: a criança que joga por webcam consegue desligar a
-     * alternância de que a entrada dela depende, e nada o diz.
+     * 🔴 A REQUIRED FIELD: without a feeder, ADR-0109's automaton answers `teclado` for everyone through
+     * `inputOf(i).inUse` — forever, with no error. Then clause 3's refusal never fires: the child who plays by webcam can
+     * turn off the latch their input depends on, and nothing says so.
      *
-     * ⚠️ E É AQUI QUE ELE VALE, e não no teclado que já é o padrão: o evento sintético que a webcam despacha
-     * chega carimbado (`input/origem-sintetica`), então é por esta linha que `olhos`/`rosto`/`gestos`/`fala`
-     * passam a ser o transporte em uso. Uma tecla premida a sério devolve o teclado, que é a regra 3 do ADR-0109.
+     * ⚠️ AND IT IS HERE THAT IT COUNTS, not on the keyboard, which is already the default: a stamped synthetic event
+     * (`input/synthetic-source`) is how `olhos`/`rosto`/`gestos`/`fala` become the transport in use through this module.
+     * A key really pressed brings back the keyboard, which is ADR-0109's rule 3.
      */
-    arestaDoJogador: (jogador: number, origem: Transporte) => void;
-    soltarTecla: (code: string) => void;
-    /** `let oneButton` do game.js (empatia motora) → getter. */
+    playerEdge: (player: number, origin: TransportName) => void;
+    releaseKey: (code: string) => void;
+    /** Motor empathy's one-button mode → getter. */
     isOneButton: () => boolean;
     actionOf: (code: string, playerIndex: number) => string | null;
     whichPlayer: (code: string) => number;
     $: DomQuery;
-    /** `overlays.escapeTarget()` de ui/settings-panel.ts. */
+    /** ui/settings-panel.ts's `overlays.escapeTarget()`. */
     escapeTarget: () => string | null;
-    /** `overlays.closeById(id)` — o retorno é ignorado, verbatim. */
+    /** `overlays.closeById(id)` — its return value is ignored. */
     closeOverlayById: (id: string) => void;
-    /** input/gamepad.ts. LAZY: `gamepadApi` é `const` declarado ~800 linhas abaixo do ponto de init. */
+    /** input/gamepad.ts's. LAZY: the pad api may be built after this module. */
     closePadWiz: (save: boolean) => void;
-    /** input/touch.ts via o envelope içado do game.js. Sem motivo no título; `'teclado'` no jogo (E13). */
+    /** input/touch.ts's. No reason on the title; `'teclado'` in play. */
     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).
+     * The INTENT arrives, and the GAME decides what it means (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.
+     * One door and not four verbs (move, confirm, erase, announce Braille): with the verbs, which one to call was decided
+     * here, with a three-column grid and a Braille detour. A game with a four-column grid, or a vertical list, answers
+     * differently without this module knowing there is a grid.
      */
-    /** O ÍNDICE do jogador, não o jogador (ADR-0033/0039). Ver a mesma nota em input/gamepad. */
+    /** The player's INDEX, not the player (ADR-0033/0039). See the same note in 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. */
+    /** Does the player at POSITION `i` have a modal open? A question, and not the object: see `modalOpen` in the snapshot. */
     hasModal: (playerIndex: number) => boolean;
-    /** ui/hud.ts: some com o selo "tela em espera" quando o jogador daquela tela entra. */
+    /** Removes the "screen on standby" badge when that screen's player joins. */
     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. */
+    /** The keyboard listener. See `EventTargetLike` in input/touch-bindings: generic over `WindowEventMap`, because the
+     *  `fn: (e: never)` version forced a cast here and an adapter in every consumer. */
     win: EventTargetLike;
 }
 export interface KeydownApi {
-    /** O snapshot que a decisão consome. Exposto para o teste poder montá-lo e comparar. */
+    /** The snapshot the decision consumes. Exposed so the test can build and compare it. */
     snapshot: () => KeydownSnapshot;
-    /** O ouvinte de bolha inteiro (sondas + decisão + efeito). Exportado à parte para o teste disparar sem DOM. */
+    /** The whole bubbling listener (probes + decision + effect). Exported apart so the test can fire it without DOM. */
     onKeydown: (e: KeydownEventLike) => void;
-    /** A outra metade do `keys.add`. */
+    /** The other half of the hold. */
     onKeyup: (e: KeyupEventLike) => void;
-    /** Instala os dois na janela, em BOLHA, na mesma ordem de antes. */
+    /** Installs both on the window, in BUBBLE. */
     attach: () => void;
 }
 export declare function initKeydown(ctx: KeydownCtx): KeydownApi;