@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -1,95 +1,25 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
 import type { PlayerView } from '../core/entity.js';
-import { type TabelaDoPad } from './pad-defaults.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, tabela?: TabelaDoPad): PadActions;
+import { type PadMaps } from './pad-wizard.js';
+import type { PadTableFor } from './pad-defaults.js';
+import type { LiveInput } from './state.js';
+import { type PadLike, type GetGamepads, type PadMap, type ActionKey } from './pad-reading.js';
 /**
- * O MODO DE UM BOTÃO, APLICADO AO CONTROLE — a metade que faltava da empatia motora (issue #120).
- *
- * ⚠️ ELE VALIA SÓ NO TECLADO. `input/keydown.ts:407` solta todas as outras teclas de jogo quando uma nova
- * chega com o modo ligado; `pollPads` não tinha equivalente nenhum, e `grep oneButton` neste ficheiro
- * devolvia zero. Uma criança que ligasse o modo e tivesse um controle na mão **não estava no modo** — sem
- * erro, sem aviso, sem sintoma, porque as definições continuavam a dizer que estava ligado.
- *
- * ⚠️ AS DIREÇÕES CONTAM, e é isso que torna a regra fiel ao teclado: lá, `isGameKeyCode` inclui as teclas
- * de `p.ctrl`, que são as quatro direções — andar e pular não coexistem. Um filtro que poupasse as
- * direções seria mais confortável e estaria a simular outra deficiência.
+ * The ORDER in which the wizard asks. ONLY the order — the same list `input/pad-wizard` walks, where it lives apart
+ * from any game (issue #182).
  *
- * ⚠️ E A ESCOLHA DE QUEM SOBREVIVE É DIFERENTE DA DO TECLADO, POR NECESSIDADE. No teclado a chegada nova
- * ganha, porque HÁ uma chegada: o evento diz qual é. Um controle é lido por SONDAGEM — o que chega é um
- * retrato, sem ordem. Então mantém-se a que já valia, e só quando ela solta é que a próxima assume. É o
- * que impede o botão de correr de ser cortado porque o polegar encostou noutro, e é a mesma leitura de
- * «segurar» que o ADR-0077 dá.
+ * ⚠️ NO WORDS HERE: the word comes from `ctx.actionLabel`, which the game supplies through its preset (ADR-0074 —
+ * platformer vocabulary, in one language, inside the engine was the defect this removed). What stays is what really
+ * is the engine's: the sequence of the questions — directions first, actions next, system last —, an ergonomic
+ * decision of the wizard and not of the game.
  *
- * A POLÍTICA é a mesma do `keydown`; a IMPLEMENTAÇÃO não pode ser partilhada hoje porque as formas do
- * estado diferem — lá é um `Set` de códigos de tecla, aqui é um retrato de booleanos por posição. Unificar
- * as duas é trabalho à parte, e escrevê-lo aqui é a alternativa a fingir que não há duas.
+ * ⚠️ AND AN ACTION THE GAME DOES NOT NAME IS NOT ASKED. `input/pad-wizard` skips it, because a game that does not use
+ * the position has nothing to map on it — and asking would produce a mute step or, worse, a step saying `action7` out
+ * loud. The exception is the system's two: START and SELECT are always asked, in the engine's words, because no game may
+ * name them and no pad may lack them (ADR-0144, erratum of 2026-09-26).
  */
-export declare function umBotaoPorVez(anterior: Readonly<Record<string, boolean | undefined>>, atual: PadActions, ligado: boolean): PadActions;
 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[];
@@ -101,7 +31,7 @@ interface WizAxTrack {
     changes: number;
     ticks: number;
 }
-/** Estado do wizard em andamento; `null` = fechado. Espelha o `padWiz` do game.js. */
+/** The state of a wizard in progress; `null` = closed. */
 export interface WizState {
     gi: number;
     id: string;
@@ -116,100 +46,219 @@ export interface WizState {
 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.) */
+/** The minimal player shape this module reads/writes — DERIVED from core/entity, not retyped. There is no `quiz`
+ *  here (ADR-0033): the question is `ctx.hasModal(i)` and the answer is an INTENT, so this module never reads the
+ *  game's object. */
 export type GamepadPlayer = PlayerView<'pad' | 'quit' | 'waiting' | 'easy' | 'jumpEdge' | 'runEdge' | 'leftEdge' | 'rightEdge' | 'swapEdge' | 'specialEdge'>;
+/**
+ * WHAT ONLY THE CARTRIDGE KNOWS ABOUT ITS WORLD (ADR-0224). The engine mounts this transport — as it mounts touch, the
+ * eyes, the face, the hands, the voice and the scan —, and the root answers every door of `GamepadCtx` it can with what it
+ * already has. These are the ones left, and they are the ones nothing in the engine can know.
+ *
+ * 🎯 **ALL OPTIONAL, AND EVERY ABSENCE HAS A WRITTEN MEANING** — never guessed (ADR-0113 clause 3, ADR-0169). A
+ * cartridge that declares nothing has a working pad; what depends on its world simply does not happen. Refusing the
+ * boot for lack of these would break every game with a pad and no title screen, over a declaration that has a safe
+ * meaning — refusing where it should report.
+ *
+ * 📌 ONE FIELD in `CreateGameOptions`, not nine loose ones: nine fields are nine things every game has to learn in a
+ * contract whose cost is a one-way door (ADR-0172), and the next transport needing the same treatment would bring nine
+ * more. Grouping them also says something true — they belong together because they are what the pad needs from the
+ * game.
+ */
+export interface GamepadGameHooks {
+    /** Is the world moving? **Absent: it is**, whenever the pause card is not open. */
+    readonly worldRunning?: () => boolean;
+    /** This game's title screen. **Absent: no title to navigate** — the pad does nothing outside play and the pause. */
+    readonly navTitle?: (k: NavKeys) => void;
+    /** The demonstration that plays by itself. **Absent: no demo**, so nothing to stop. */
+    readonly attractActive?: () => boolean;
+    readonly stopAttract?: () => void;
+    /** This player's open challenge. **Absent: no modal**, and the d-pad belongs to the game. */
+    readonly hasModal?: (playerIndex: number) => boolean;
+    readonly modalInput?: (playerIndex: number, intent: ModalIntent) => void;
+    /** Joining a running game with a new screen. **Absent: nobody joins midway** (returns `false`). */
+    readonly joinPlayer?: (padIndex: number) => boolean;
+    /** Restarting only this player's screen. **Absent: nothing happens** — an abandoned screen stays abandoned. */
+    readonly respawnPlayer?: (playerIndex: number) => void;
+    /** The game's HUD "waiting" badge. **Absent: there is no badge** to remove. */
+    readonly clearWaitingBadge?: (playerIndex: number) => void;
+    /**
+     * A demonstration of what each position does, drawn by the GAME while the mapping wizard asks for it — `null` is
+     * the wizard opening. **Absent: the wizard speaks, with no drawing.** The engine asks the questions and in what
+     * order; what a position LOOKS like is the game's (note CD — the engine used to draw one game's boy here).
+     */
+    readonly wizardStep?: (position: string | null) => void;
+    /** One tick of the wizard's clock, for a demonstration that animates. **Absent: nothing animates.** */
+    readonly wizardTick?: () => void;
+}
+/** The same answers, all present: this is what `GamepadCtx` consumes, and what the table below guarantees. */
+export type PadGameAnswers = Required<Omit<GamepadGameHooks, 'worldRunning'>> & {
+    readonly worldRunning: () => boolean;
+};
+/**
+ * The cartridge's answers with every absence already resolved. 📌 A field DECLARED as `undefined` is an absence like any
+ * other — spreading the raw object over the table would erase the answer with an `undefined`, which is the silent
+ * defect this function exists not to have.
+ */
+export declare function padGameAnswers(hooks: GamepadGameHooks | undefined, worldRunningWhenSilent: () => boolean): PadGameAnswers;
+/**
+ * THE SEAT FIELDS, SEEDED BY THE ENGINE (ADR-0224). 📏 Measured: the players a cartridge declares are
+ * `{ ctrl, audioSink? }`, and this transport needs to know whose each pad is (`pad`), who is still waiting (`waiting`)
+ * and who left the screen (`quit`).
+ *
+ * 🔴 IT SEEDS THE OBJECT ITSELF and returns the SAME list — copying would lose the seat on the next frame, because
+ * `takeSeat` writes into this object. That is also why there is no `.map`: the identity is what carries the state.
+ * 📌 It only touches whoever does not have the fields yet, so a cartridge that declares them keeps its own.
+ */
+export declare function seatEveryPlayer(list: readonly object[]): GamepadPlayer[];
 export interface GamepadCtx {
-    /** Adaptador da Gamepad API (substitui `navigator.getGamepads()`) — o ponto de DI para testar sem browser. */
+    /** 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 controller maps a child made — this root's `createPadMaps(store)` (ADR-0232 D4), the SAME object its own mapping
+     * wizard writes. Required: a pad whose map is read from nowhere answers with the standard layout, and a custom pad goes
+     * dead with no word said.
+     */
+    padMaps: PadMaps;
+    /**
+     * THIS GAME'S BUTTON TABLE per arrangement and seat — `createPadTable(declaration.padMapping)` (ADR-0115, ADR-0232 D4).
+     * Required: a transport handed no table would give the ENGINE's map, in silence, to a game that declared another.
+     */
+    padTable: PadTableFor;
+    /** Where each pad's frame is kept — this root's input state (`Engine.input`), mutated in place every poll. */
+    input: Pick<LiveInput, 'padCur' | 'padPrevAct' | 'padPrevStart'>;
+    /**
+     * Is the ONE-BUTTON mode on (the motor empathy, issue #120)? Read each frame — the child turns it on mid-game. The
+     * root answers from the settings store it built (ADR-0232); required, see the note at the imports.
+     */
+    oneButton: () => boolean;
+    /** The Gamepad API adapter (replaces `navigator.getGamepads()`) — the DI point for testing with no browser. */
     getGamepads: GetGamepads;
-    /** Seletor DOM (querySelector), injetado — nunca alcança `document` global. */
+    /** DOM selector (querySelector), injected — never reaches the global `document`. */
     $: DomQuery;
     /**
-     * COMO SE CHAMA esta posição, na palavra do JOGO e no idioma vigente. `null` = o jogo não a usa.
+     * WHAT this position IS CALLED, in the GAME's word and the current language. `null` = the game does not use it.
      *
-     * ⚠️ É 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.
+     * ⚠️ It is the boundary between engine and game as a field: the engine knows a position exists, only the game knows
+     * the word. Without it the wizard would speak a constant of this file — in one language, without `t()`, inside the
+     * engine.
      */
-    rotuloDaAcao: (acao: string) => string | null;
-    /** Anúncios de leitor de tela (core/a11y-sr), injetados. */
+    actionLabel: (action: string) => string | null;
+    /** Screen-reader announcements (core/a11y-sr), injected. */
     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). */
+    /** Brings an overlay to the front + fills in the help text (the shared overlay helper, used by every 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. */
+    /** Is the world running? (START here PAUSES.) */
+    worldRunning: () => boolean;
+    /** Is the pause menu open? (START here RESUMES.) */
+    pauseMenu: () => boolean;
+    /**
+     * Pause and resume. The root stacks the scene; only the intent leaves from here. ⚠️ `pause` carries no seat: it is the
+     * mapping wizard's, which stops everything while a pad is mapped. START in play is PRESSED for the pad's seat (`press`).
+     * `resume` names the seat whose START asks it — the wizard's own resume is seat 0's, whose quick pause `pause` opened —, because
+     * the root decides whether that seat's START reaches this screen's pause: on a shared screen only the first seat's does
+     * (ADR-0144, erratum of 2026-09-26).
+     */
+    pause: () => void;
+    resume: (seat: number) => void;
+    /** Demonstration (attract) mode. */
     isAttractActive: () => boolean;
     stopAttract: () => void;
-    /** Controles virtuais de toque — somem no primeiro input físico. */
+    /** On-screen touch controls — they vanish on the first physical input. */
     isTouchMode: () => boolean;
     hideTouchControls: () => void;
-    /** Estado vivo de jogadores/telas (core/state.ts, injetado como getter — nunca cacheado por este módulo). */
+    /** Live state of players/screens (injected as a getter — never cached by this module). */
     getPlayers: () => GamepadPlayer[];
     getNumPlayers: () => number;
-    /** Navegação de menus (game.js): título, diálogo compartilhado (o de cima), e a pausa por tela. */
+    /** Menu navigation: the title, the shared dialog (the topmost), and the pause per screen. */
     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;
+    /** Is screen `i` in `accessibility` mode? (ADR-0044, item 7 — the d-pad steers the HUD bar.) */
+    onBar: (i: number) => boolean;
+    /** One step inside the bar. `hasStart` is the pause button's edge, which is the mode's SECOND exit. */
+    navBar: (i: number, k: NavKeys, hasStart: 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. */
+    /**
+     * Does this seat's pad steer the menus open on this screen — the dialog on top and the pause card? On a screen several players
+     * share, only the first's does (ADR-0144, erratum of 2026-09-26): another seat's d-pad and buttons move, press and close
+     * nothing there. Absent: every seat's does — each has a screen of her own. The same question `ui/menu-nav` asks of a key.
+     */
+    leadsTheScreen?: (seat: number) => boolean;
+    /** The player's pause screen. `HTMLElement` and not `{ hidden: boolean }`: the structural minimum works for READING,
+     *  but this module HANDS the menu to `navPause`, which needs the whole element — and in parameter position the
+     *  minimal slice inverts (ADR-0039). */
     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`). */
+    /** Which player opens the accessibility submenu next. */
     setPauseActor: (playerIndex: number) => void;
     /**
-     * ESTA ARESTA É DESTE JOGADOR, E VEIO DO CONTROLE (ADR-0113 cláusula 4, issue #127).
+     * THIS EDGE IS THIS PLAYER'S, AND IT CAME FROM THE PAD (ADR-0113 clause 4, issue #127).
      *
-     * 🔴 OBRIGATÓRIO, e a razão foi medida em 2026-09-09: `input/state.arestaDoJogador` tinha ZERO chamadores
-     * em produção, logo `entradaDe(i).emUso` respondia `teclado` a toda a gente — e a alternância lida era a do
-     * teclado mesmo com o controle na mão. 📌 Passe `criarArestaComAlternancia(() => players)` de
-     * `input/latch-edge`, e não o cru: é ela que também resolve a alternância deste aparelho no jogador.
+     * 🔴 REQUIRED: without it the input state's `playerEdge` has no caller for the pad, so `inputOf(i).inUse` answers
+     * `teclado` for everyone — and the latch read is the keyboard's even with the pad in hand. 📌 The latch is resolved where the
+     * pad's press lands: the root's virtual controller tells `pressedBy`, which records this edge through `input/latch-edge` too,
+     * so the root passes the raw one here. A host whose `press` does not reach such a door passes
+     * `createLatchedEdge(() => players, { store, input, holdsKeys })` instead.
      *
-     * ⚠️ O gamepad era o ÚNICO transporte que sobrevivia identificável sem isto — ele nunca passou pelo
-     * conjunto de teclas, passa por `padCur` —, e é exactamente por isso que a falta aqui era invisível: o
-     * módulo sabe de que controle veio a aresta, e o autómato não.
+     * ⚠️ The gamepad is the transport that stays identifiable without the key set — it goes through `padCur` —, and that
+     * is exactly why a gap here is invisible: the module knows which pad the edge came from, and the automaton does not.
+     */
+    playerEdge: (player: number, origin: 'gamepad') => void;
+    /**
+     * THE SINGLE DOOR TO THE CARTRIDGE (ADR-0223): press a POSITION on this pad's seat. Answers whether the press reached
+     * the GAME — `false` means a menu took it.
+     *
+     * 🔴 Edges alone are not a door: a cartridge that listens only to `onCommand` — which ADR-0111's erratum asks of
+     * everyone — would not answer a pad. The edges stay (a cartridge's physics learns from them that there was a press),
+     * but they are the CONSEQUENCE of a press that reached the game.
+     *
+     * 📌 REQUIRED, and ADR-0223's erratum says why: an optional door is one more field a game can forget, and forgetting
+     * it brings back the silence this work exists to end. The root passes its virtual controller's `press`.
+     */
+    press: (action: ActionKey | 'start' | 'select', source: 'gamepad', player: number) => boolean;
+    /** Release the POSITION. The controller lets go of the key it held and delivers the release — only for a press the game heard. */
+    release: (action: ActionKey, source: 'gamepad', player: number) => void;
+    /**
+     * ONE BUTTON ONLY (ADR-0218 §4): asked once per frame in which a button of a pad WENT DOWN — a position, START or SELECT.
+     * `true`: one-button scanning took it as «take the one shown», and nothing else of that pad's frame happens. It is the question
+     * the virtual controller asks of every press (`takeShown` there); the pad asks it too because it also steers the pause card,
+     * a panel, the quick bar and the title, and opens and leaves the pause, by itself and without pressing a position.
+     * Absent: every press is itself.
      */
-    arestaDoJogador: (jogador: number, origem: 'gamepad') => void;
+    takeShown?: () => boolean;
     /**
-     * MODAL do PRÓPRIO jogador: a engine entrega a INTENÇÃO, o jogo decide (ADR-0033).
+     * The player's OWN modal: the engine delivers the INTENT, the game decides (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.
+     * One intent and not four verbs (move, confirm, erase, announce Braille): with the verbs, the decision of which to
+     * call lived here, with the three-column grid and the Braille detour — and the pad and the keyboard each had a COPY
+     * of it, which is the worst way to have it: two to drift apart.
      */
-    /** 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. */
+    /** The player's INDEX, not the player (ADR-0033/0039): the engine delivers an intent and does not need to know what a
+     *  player with an open challenge is. The challenge's owner resolves the index. */
     modalInput: (playerIndex: number, intent: ModalIntent) => void;
-    /** Este jogador tem um modal aberto? Uma pergunta, e não o objeto do jogo. */
+    /** Does this player have a modal open? A question, and not the game's object. */
     hasModal: (playerIndex: number) => boolean;
-    /** Entra num jogo em andamento com uma tela nova (game.js's joinPlayer). */
+    /** Joins a running game with a new screen. */
     joinPlayer: (padIndex: number) => boolean;
-    /** Recomeça só a tela deste jogador (game.js's respawnPlayer). */
+    /** Restarts only this player's screen. */
     respawnPlayer: (playerIndex: number) => void;
-    /** Remove o selo "aguardando" da tela quando ela ganha um controle (parte do HUD, game.js). */
+    /** Removes the screen's "waiting" badge when it gets a pad (part of the game's HUD). */
     clearWaitingBadge: (playerIndex: number) => void;
+    /** The game's demonstration of each wizard step (`GamepadGameHooks.wizardStep`). */
+    wizardStep: (position: string | null) => void;
+    /** One tick of the wizard's clock for that demonstration (`GamepadGameHooks.wizardTick`). */
+    wizardTick: () => 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.
+     * THIS TRANSPORT'S OWN WIZARD HAS CLOSED (ADR-0248), whichever way it ended — saved, cancelled, or closed by the root. Called
+     * once per close, AFTER `#padwiz` is hidden and after the resume of a game the wizard paused, so whoever owns the focus
+     * returns it to what is really in front. The root answers by giving the focus back to whoever held it when the wizard
+     * opened (`overlays.restoreFocus('padwiz')`).
+     * 🔴 REQUIRED (ADR-0248, as ADR-0224 did for the door): the code that knows the wizard ended is this module, the code that owns
+     * the focus is the root — an optional port is one more field a game can forget, and forgetting it drops a screen-reader
+     * child's focus on `<body>`.
      */
-    spriteBase: string;
+    wizardClosed: () => void;
 }
 export interface GamepadApi {
     pollPads(): void;
@@ -218,7 +267,8 @@ export interface GamepadApi {
     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). */
+    /** The wizard's live state (`null` = closed). */
     getPadWiz(): WizState | null;
 }
 export declare function initGamepad(ctx: GamepadCtx): GamepadApi;
+export {};