@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/ui/shell.d.ts

@@ -1,114 +1,95 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
 import type { DomQuery } from '../core/dom-query.js';
-import type { PadMap } from '../input/gamepad.js';
-import type { FatosDaCena } from '../core/scenes.js';
-/** ui/dom.ts `$` — injetado para o teste node poder passar um DOM falso. */
+import type { PadMap } from '../input/pad-reading.js';
+import type { SceneFacts } from '../core/scenes.js';
+/** ui/dom.ts `$` — injected so a node test can pass a fake DOM. */
 export type { DomQuery } from '../core/dom-query.js';
-/** O subconjunto de `Window` que `printMode` usa (add/remove de ouvinte em CAPTURA + o adiamento de 80ms). */
+/** The part of `Window` that `printMode` uses (adding and removing a listener in CAPTURE, and the 80 ms delay). */
 export interface ShellWindow {
     addEventListener(type: string, fn: (e: Event) => void, capture: boolean): void;
     removeEventListener(type: string, fn: (e: Event) => void, capture: boolean): void;
     setTimeout(fn: () => void, ms: number): unknown;
 }
-/** Uma tela de pausa (`.screen-pause`) — só o que a casca toca. */
+/** A pause screen (`.screen-pause`) — only what the shell touches. */
 export interface PauseScreen {
     hidden: boolean;
     querySelectorAll<T extends Element = Element>(sel: string): ArrayLike<T> & Iterable<T>;
 }
-/** Um gamepad, do jeito mínimo que a legenda do título lê. */
+/** A gamepad, as little of it as the title legend reads. */
 interface PadLike {
     index: number;
     id: string;
     mapping: string;
 }
-/** Para onde o foco vai ao ENTRAR na fase. `null` = ninguém foca nada (não existe hoje; é o default seguro). */
+/** Where the focus goes on ENTERING a scene. */
 export type PhaseFocus = 'game-region' | 'pause-menu' | 'title-button';
 /**
- * O que a fase `p` manda o documento fazer. É a sequência de `if`s do `setPhase` original lida como o que ela
- * sempre foi: uma projeção da fase. Nenhum campo depende de histórico — o único que dependeria
- * (`#touch-controls`) mora em `touchControlsPlan`, separado de propósito.
+ * What the scene on top asks of the document — a projection of the scene facts, with no field depending on history (the
+ * one that would, `#touch-controls`, lives in `touchControlsPlan`, apart on purpose).
  */
-export type { FatosDaCena } from '../core/scenes.js';
+export type { SceneFacts } from '../core/scenes.js';
 export interface PhaseView {
-    /** `#title-overlay`.hidden — o splash só aparece no título. */
+    /** `#title-overlay`.hidden — the splash only shows on the title. */
     titleOverlayHidden: boolean;
     /**
-     * ⚠️ `pauseOverlayHidden` SAIU EM 2026-09-08, e a ausência é a notícia.
-     *
-     * Ele era `true` em toda fase, e existia porque a Etapa 2 aposentou a pausa GLOBAL sem apagar o elemento: a
-     * casca continuava a procurá-lo e a escondê-lo a cada troca de fase, com dois gates a afirmar que ele ficava
-     * escondido. Código a segurar um cadáver.
-     *
-     * E o cadáver custava mais do que as linhas: aquelas quarenta linhas de `#pause-overlay` no `index.html` do
-     * cartucho eram o menu de pausa com aspecto mais OFICIAL do repositório — o que o próximo autor de cartucho
-     * copia junto com o ficheiro —, e já tinham derivado do que a engine gera (dois itens «Comunicação», e um
-     * `#opt-letra` que hoje sai do `dynLabel`). Um campo que diz «está escondido» aceita que ele exista; não o
-     * ter diz que ele não existe.
+     * There is no global pause overlay to hide: each screen has its own pause card (below). A field saying «it is hidden»
+     * would accept that one exists — and a leftover global menu in a page is the one the next game author would copy.
      */
-    /** `.screen-pause`.hidden de CADA tela — os menus por tela só aparecem na pausa. */
+    /** `.screen-pause`.hidden of EACH screen — the per-screen cards only show while paused. */
     screenPauseHidden: boolean;
-    /** `setMasterMuted(...)` — GAG: fora de 'playing' TODO o som cala (loops de ambiente/chuva inclusive). */
+    /** `setMasterMuted(...)` — GAG: outside play ALL sound goes quiet (ambient and rain loops included). */
     masterMuted: boolean;
-    /** `hideTouchControls()` — menu ativo (título/pausa) = sem controle virtual. */
+    /** `hideTouchControls()` — an active menu (title or pause) = no virtual controller. */
     hideTouchControls: boolean;
     /**
-     * `aria-pressed` do botão de pausa — ele diz ao leitor de tela SE está pausado.
-     *
-     * O alvo era `#btn-pause`, e esse id NUNCA existiu no documento: o botão saiu da barra e a fiação ficou
-     * "guardada p/ compat". A linha que escrevia o atributo era morta, e o teste do navegador não pegava porque
-     * o FIXTURE inventava o elemento — um caso que provava que o código escreve num botão que só o teste tem.
-     *
-     * O alvo agora é `#touch-start`, que é o botão que existe, o que o Dev clica e o ÚNICO caminho de pausa num
-     * tablet (não há teclado no Positivo da issue #8).
+     * The pause button's `aria-pressed` — it tells a screen reader WHETHER the game is paused. The target is
+     * `#touch-start`, the pad's START: the button that exists, and the only way to pause on a tablet without a keyboard.
      */
     pausePressed: boolean;
-    /** Quem recebe o foco ao entrar nesta fase. */
+    /** Who receives the focus on entering this scene. */
     focus: PhaseFocus;
 }
-/** Verbatim das nove perguntas que o `setPhase` do game.js fazia à fase, agora feitas de uma vez só. */
-export declare function phaseView(f: FatosDaCena): PhaseView;
-/** O estado de `#touch-controls` que interessa: escondido? e havia controle ligado antes da pausa? */
+/** Every question the scene change asks of the scene, asked at once. */
+export declare function phaseView(f: SceneFacts): PhaseView;
+/** The part of `#touch-controls` that matters: hidden? and was the pad on before the pause? */
 export interface TouchControlsState {
     /** `tc.hidden`. */
     hidden: boolean;
-    /** `tc.dataset.wasOn === '1'`. Ausente/qualquer outro valor = false, como no original. */
+    /** `tc.dataset.wasOn === '1'`. Absent or any other value = false. */
     wasOn: boolean;
 }
 /**
- * O ÚNICO pedaço de `setPhase` com memória: esconder os controles de toque ao pausar (guardando que estavam
- * ligados) e devolvê-los ao retomar. Pura, e por isso pinável sem navegador.
+ * The ONE part of a scene change with memory: hide the touch controls on pause (recording that they were on) and give them
+ * back on resume. Pure, so it can be pinned without a browser.
  *
- * O estado que chega aqui é o de ANTES de `hideTouchControls()` — quem chama lê primeiro e esconde depois.
- * Já foi o contrário, e o efeito era que `wasOn` nunca era gravado (o plano via o pad como se já estivesse
- * desligado): pausar no celular sumia com o direcional virtual e retomar não o devolvia.
+ * The state that arrives here is the one from BEFORE `hideTouchControls()` — the caller reads first and hides after.
+ * The other order never records `wasOn` (the plan sees the pad already off), and resuming on a phone would not give the
+ * virtual d-pad back.
  */
-export declare function touchControlsPlan(f: FatosDaCena, st: TouchControlsState, screens: number): TouchControlsState;
-/** Um "chip" da legenda: o glifo (com cor de fundo opcional) seguido da palavra que ele significa. */
+export declare function touchControlsPlan(f: SceneFacts, st: TouchControlsState, screens: number): TouchControlsState;
+/** One legend «chip»: the glyph (with an optional background colour) followed by the word it stands for. */
 export declare function chip(txt: string, col: string | null, word?: string): string;
 /**
- * O nome FALADO de um glifo de controle. Glifo que já se lê passa intocado.
+ * The SPOKEN name of a controller glyph. A glyph that already reads as a word passes untouched.
  *
- * Ver `PAD_GLYPH_SPOKEN` em `input/devices`: a tabela guarda CHAVES e não texto, porque ela é uma `const` de
- * módulo avaliada uma vez no import — texto já resolvido congelaria o idioma no boot. Quem resolve é aqui, a
- * cada chamada, com o idioma vigente naquele instante.
+ * `PAD_GLYPH_SPOKEN` in `input/devices` holds KEYS, not text, because it is a module `const` evaluated once on import —
+ * resolved text would freeze the language at boot. It is resolved here, on each call, in the language of that moment.
  */
-export declare function glifoFalado(g: string): string;
+export declare function spokenGlyph(t: Translate, g: string): string;
 /**
- * A LEGENDA DA PAUSA — duas camadas no mesmo lugar (ADR-0044, item 4).
- *
- * Ela dizia qual botão confirma e qual volta, e carregava `aria-hidden="true"` — ou seja, era invisível
- * justamente para quem não pode ver o glifo. A XAG 106 manda narrar exatamente isto ("A to Select").
+ * THE PAUSE LEGEND — two layers in the same place (ADR-0044 item 4).
  *
- * Mas só tirar o atributo devolveria o ruído que provavelmente o motivou: um leitor de tela lê `✕` como
- * "sinal de multiplicação". Então os CHIPS ficam visíveis e mudos, e ao lado nasce UMA frase só para leitor
- * de tela, com os glifos já traduzidos em palavra. Duas leituras da mesma informação, cada uma no sentido
- * que a alcança.
+ * It says which button confirms and which goes back, and XAG 106 asks for exactly this to be narrated ("A to Select").
+ * The CHIPS stay visible and silent — a screen reader would read `✕` as a multiplication sign — and beside them a single
+ * sentence exists for screen readers only, with the glyphs already turned into words. Two readings of the same
+ * information, each in the sense that reaches it.
  *
- * Recebe os pares `[glifo, cor]` que `simNaoGlyphs` escolhe a partir do desenho do controle — a inversão
- * PlayStation/Nintendo (onde "sim" é o botão 1) já vem decidida de lá.
+ * Takes the `[glyph, colour]` pairs of the pad's design by position: yes is the south button (A · ✕ · B) and no the east one
+ * (B · ◯ · A) on every design — no design swaps them (the Dev's association, ADR-0013 erratum).
  */
-export declare function pauseLegendHtml(sim: readonly [string, string], nao: readonly [string, string]): string;
-/** Os quatro botões de ação, na ordem fixa da legenda: pular · especial · correr · trocar. */
+export declare function pauseLegendHtml(t: Translate, sim: readonly [string, string], no: readonly [string, string]): string;
+/** The four action buttons, in the legend's fixed glyph order: action2 · action3 · action1 · action4. */
 export interface ActionGlyphs {
     action2: readonly [string, string | null];
     action3: readonly [string, string | null];
@@ -116,95 +97,93 @@ export interface ActionGlyphs {
     action4: readonly [string, string | null];
 }
 /**
- * Linha 1 da legenda: direcional + START/Enter. Igual para toque e gamepad; o teclado sobrescreve os rótulos.
+ * Legend row 1: the d-pad and START/Enter. The same for touch and gamepad; the keyboard overrides the labels.
  *
- * As palavras vêm de `legend.*` e são resolvidas AQUI, a cada chamada — não numa tabela de módulo, que
- * congelaria o idioma no boot. Registro CURTO de propósito: esta fileira fica embaixo de um glifo e não tem
- * largura para o "Correr / interagir" que a lista de mapeamento usa (ver a nota em pt.ts).
+ * The words come from `legend.*` and are resolved HERE, on each call — not in a module table, which would freeze the
+ * language at boot. The SHORT register on purpose: this row sits under a glyph and has no room for the longer wording the
+ * remapping list uses.
  */
-export declare function legendRow1(dirTxt: string, pauseTxt: string): string;
+export declare function legendRow1(t: Translate, dirTxt: string, pauseTxt: string): string;
 /**
- * Linha 2 da legenda: os botões de ação, na ordem dos glifos.
+ * Legend row 2: the action buttons, in glyph order.
  *
- * ⚠️ AS PALAVRAS DEIXARAM DE ESTAR AQUI. Esta função dizia `t('legend.jump')`, `t('legend.run')` — o
- * vocabulário da plataforma dentro de um módulo de engine, e a engine a afirmar que todo jogo tem pular,
- * especial, correr e trocar, nessa ordem. Agora `rotulo` é perguntado ao jogo (a versão CURTA, ver
- * `ActionWord.short`), e uma posição que o jogo não nomeia não vira ficha nenhuma.
+ * The words are asked of the GAME (`wordFor`, the SHORT version — see `ActionWord.short`): the engine does not assume
+ * every game has jump, special, run and swap. A position the game does not name becomes no chip at all.
  */
-export declare function legendRow2(g: ActionGlyphs, rotulo: (acao: string) => string | null): string;
-/** O innerHTML final de `#title-legend`: duas `.lg-row`. */
+export declare function legendRow2(g: ActionGlyphs, wordFor: (action: string) => string | null): string;
+/** The final innerHTML of `#title-legend`: two `.lg-row`. */
 export declare function legendHtml(l1: string, l2: string): string;
 /**
- * Glifos de um pad FÍSICO. `layout` sai de `padLayoutFromId` (só quando `mapping === 'standard'`; fora do
- * padrão é sempre 'generic'), e `custom` é o mapa do assistente (só consultado FORA do padrão). Verbatim:
- * um botão sem entrada no mapa custom cai no índice default ('0'..'3'), e um índice que o design não conhece
- * vira o par `[índice, '#3a4a6a']` — o cinza de fallback.
+ * The glyphs of a PHYSICAL pad. `layout` comes from `padLayoutFromId` (only when `mapping === 'standard'`; off-standard it
+ * is always 'generic'), and `custom` is the wizard's map (only consulted OFF the standard). A button with no entry in the
+ * custom map falls back to its default index ('0'..'3'), and an index the design does not know becomes the pair
+ * `[index, '#3a4a6a']` — the fallback grey.
  */
 export declare function padActionGlyphs(layout: string, custom: PadMap | null): ActionGlyphs;
-/** Glifos do joystick VIRTUAL (toque): sempre o design 'generic' (0/1/2/3), sem mapa custom. */
+/** The glyphs of the VIRTUAL (touch) pad: always the 'generic' design (0/1/2/3), no custom map. */
 export declare function touchActionGlyphs(): ActionGlyphs;
 /**
- * Escolhe QUAL gamepad a legenda descreve: o do Jogador 1, se ele tiver um associado (`players[0].pad`);
- * senão o primeiro conectado. Verbatim do laço do game.js — inclusive o detalhe de que, com `p1pad >= 0` e
- * nenhum pad daquele índice presente, o resultado é `null` (a legenda cai no teclado) em vez de pegar outro.
+ * Chooses WHICH gamepad the legend describes: Player 1's, if they have one (`players[0].pad`); otherwise the first one
+ * connected. With `p1pad >= 0` and no pad of that index present, the result is `null` (the legend falls back to the
+ * keyboard) rather than picking another.
  */
 export declare function pickLegendPad(pads: readonly (PadLike | null)[], p1pad: number): PadLike | null;
 export interface ShellCtx {
-    /** Os três fatos da cena do TOPO, perguntados a cada uso — a raiz é quem tem a pilha e quem nomeia as
-     *  cenas. Getter, e não valor: a casca projeta o estado ATUAL, não o do momento em que foi ligada. */
-    fatosDaCena: () => FatosDaCena;
-    /** VOLTAR AO JOGO. É o que o "Continuar" do menu de pausa faz, e o que a entrada de um jogador novo faz.
-     *  Era `setPhase('playing')` daqui mesmo — mas empilhar é da raiz, e "retomar" é o que a casca quer dizer. */
-    retomarJogo: () => void;
-    /** Quantos jogadores/telas. Estado de RODADA (ADR-0038): vem da instância que a raiz possui.
-     *  Era `numPlayers`, um `let` de `core/state` importado como binding vivo — e um `let` de módulo
-     *  é compartilhado por qualquer segundo jogo que a mesma página carregue (D13 do `demos`). */
+    /** 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 three facts of the scene on TOP, asked on each use — the root holds the stack and names the scenes. A getter,
+     *  not a value: the shell projects the CURRENT state, not the one of the moment it was wired. */
+    sceneFacts: () => SceneFacts;
+    /** BACK TO THE GAME. What the pause card's «Continue» does, and what a new player joining does. Resuming is what the
+     *  shell means; pushing and popping scenes is the root's. */
+    resumeGame: () => void;
+    /** How many players/screens. ROUND state (ADR-0038): it comes from the instance the host owns — a module-level
+     *  binding would be shared by a second game on the same page. */
     getNumPlayers: () => number;
-    /** Os jogadores. Estado de RODADA, pelo mesmo motivo. `readonly unknown[]` porque cada consumidor
-     *  estreita para a SUA fatia — o tipo real é do jogo, não da engine (ADR-0033). */
+    /** The players. ROUND state, for the same reason. `readonly unknown[]` because each consumer narrows to ITS slice —
+     *  the real type is the game's, not the engine's (ADR-0033). */
     getPlayers: () => readonly unknown[];
-    /** ui/dom.ts `$`. Injetado: o módulo nunca alcança `document`. */
+    /** ui/dom.ts `$`. Injected: the module never reaches `document`. */
     $: DomQuery;
-    /** `window` — só para os dois ouvintes em CAPTURA do modo Print e o adiamento de 80ms. */
+    /** `window` — only for Print mode's two CAPTURE listeners and the 80 ms delay. */
     win: ShellWindow;
-    /** platform/audio.ts `setMasterMuted` — o nó mestre que cala TUDO na pausa/título (GAG). */
+    /** platform/audio.ts `setMasterMuted` — the master node that silences EVERYTHING on pause and title (GAG). */
     setMasterMuted: (muted: boolean) => void;
-    /** core/a11y-sr `srSay` (educado) e `srAlert` (assertivo). */
+    /** core/a11y-sr `srSay` (polite) and `srAlert` (assertive). */
     srSay: (msg: string) => void;
     srAlert: (msg: string) => void;
-    /** `let vpPause` — `buildGameHud` REATRIBUI a array a cada troca de nº de telas. */
+    /** The pause cards, one per screen; the host rebuilds them when the number of screens changes. */
     getPauseScreens: () => PauseScreen[];
-    /** `let pauseActor` — quem abriu o menu; os submenus de a11y escopam no jogador dele. */
+    /** Who opened the pause card; the accessibility panels open scoped to that player. */
     getPauseActor: () => number;
-    /** input/touch.ts via o envelope içado do game.js: some com o direcional virtual. */
+    /** input/touch.ts: hides the virtual d-pad. */
     hideTouchControls: () => void;
-    /** ui/pause-icons.ts: reflete os `.pi-btn` de todas as telas (estado de a11y). */
+    /** ui/pause-icons.ts: reflects the `.pi-btn` of every screen (accessibility state). */
     reflectPauseIcons: () => void;
-    /** Adaptador da Gamepad API — mesmo padrão de input/gamepad.ts (é o que a torna testável sem navegador). */
+    /** Gamepad API adapter — the same pattern as input/gamepad.ts (it is what makes it testable without a browser). */
     getGamepads: () => readonly (PadLike | null)[];
-    /** `document.body.classList.contains('touch-mode')` — injetado para não alcançar `document`. */
+    /** `document.body.classList.contains('touch-mode')` — injected so as not to reach `document`. */
     isTouchMode: () => boolean;
-    /** input/touch.ts `padLayoutFromId` — id do controle → design de botões. */
+    /** input/touch.ts `padLayoutFromId` — controller id → button design. */
     padLayoutFromId: (id: string) => string;
-    /** input/gamepad.ts `padMapFor` — mapa do assistente para aquele modelo (só usado FORA do padrão). */
-    /** O mapa do controle. `PadMap` vem de `input/gamepad`, que é dono dele — a versão escrita aqui,
-     *  `Record<string, { b?: number }>`, era uma aproximação: perdia o `boolean` que o mapa admite. */
+    /** The wizard's map for that controller model (only used OFF the standard). `PadMap` comes from `input/pad-reading`,
+     *  which owns it, including the `boolean` the map admits. */
     padMapFor: (id: string) => PadMap | null;
-    /** input/keyboard-runtime.ts `kbFor(i)` — as teclas CONFIGURADAS do jogador `i` (remap respeitado). */
+    /** input/keyboard-runtime.ts `kbFor(i)` — player `i`'s CONFIGURED keys (the remap honoured). */
     kbFor: (i: number) => Record<string, string[]>;
-    /** ui/settings-controls.ts `keyName` — `KeyboardEvent.code` → rótulo humano. */
+    /** ui/control-choices `keyName` — `KeyboardEvent.code` → a human label. */
     keyName: (code: string) => string;
     /**
-     * A palavra CURTA desta posição, na língua do jogo. `null` = o jogo não a usa.
+     * The SHORT word for this position, in the game's language. `null` = the game does not use it.
      *
-     * ⚠️ Curta e não a longa: a legenda põe a palavra debaixo de um glifo, numa fileira de quatro, e não tem
-     * largura para o «Correr / interagir» que a lista de remapeamento usa. A distinção já estava no dicionário
-     * (`legend.*` contra `act.*`) e agora atravessa a fronteira COM as palavras — ver `ActionWord.short`.
+     * ⚠️ Short and not the long one: the legend puts the word under a glyph, in a row of four, and has no room for the
+     * «Correr / interagir» the remapping list uses. The distinction was already in the dictionary (`legend.*` against
+     * `act.*`) and now crosses the boundary WITH the words — see `ActionWord.short`.
      */
-    rotuloCurto: (acao: string) => string | null;
-    /** `setQuizLevel(n, announce)` — o ciclo 1..5 do nível de alfabetização. */
+    shortLabel: (action: string) => string | null;
+    /** `setQuizLevel(n, announce)` — the 1..5 cycle of the literacy level. */
     setQuizLevel: (n: number, announce: boolean) => void;
-    /** `quizLevel` de core/state.ts — lido para calcular o próximo do ciclo. */
+    /** The current literacy level — read to compute the next in the cycle. */
     getQuizLevel: () => number;
     openTypo: () => void;
     openAudio: () => void;
@@ -212,38 +191,38 @@ export interface ShellCtx {
     openVisual: () => void;
     openHelp: () => void;
     quitGame: () => void;
-    /** game/session.ts: cabe mais uma tela nesta janela? */
+    /** Does one more screen fit in this window? */
     fitsN: (n: number) => boolean;
-    /** game/session.ts: cria/ativa o jogador seguinte; `null` = sem pad associado ainda. */
+    /** Creates/activates the next player; `null` = no pad associated yet. */
     joinPlayer: (padIdx: number | null) => boolean;
-    /** ui/hud.ts: crachá "aperte um botão para entrar" na tela do jogador novo. */
+    /** ui/hud.ts: the «press a button to join» badge on the new player's screen. */
     showWaitingBadge: (i: number) => void;
-    /** ui/settings-motor.ts: escopa o painel Movimento no jogador que abriu. */
-    setMotorPlayer: (i: number) => void;
-    /** ui/settings-motion.ts `setSelectedPlayer`: idem para o painel Animação. */
+    /** ui/settings-mobility.ts: scopes the Mobility panel to the player who opened it. */
+    setMobilityPlayer: (i: number) => void;
+    /** ui/settings-motion.ts `setSelectedPlayer`: the same for the Motion panel. */
     setMotionPlayer: (i: number) => void;
     /** ui/settings-motion.ts `motion.open`. */
     openMotion: () => void;
-    /** Abre o menu de Comunicação Aumentada e Alternativa (ui/settings-caa). */
-    openCaa: () => void;
+    /** Opens the Augmentative and Alternative Communication menu (ui/settings-aac). */
+    openAac: () => void;
     /** ui/settings-empathy.ts `empathy.open`. */
     openEmpathy: () => void;
-    /** `let selVizPlayer` do game.js — escopa Visual e Empatia no jogador que abriu. */
+    /** Scopes Visual and Empathy to the player who opened them. */
     setSelVizPlayer: (i: number) => void;
 }
-/** A tabela de ações dos `.pm-btn`. Chave = `data-act` do botão (PM_BTNS, de ui/activities-menu.ts). */
+/** The table of the `.pm-btn` actions. Key = the button's `data-act`. */
 export type PauseActs = Record<string, () => void>;
 export interface ShellApi {
-    /** Projeta no documento a cena que está no topo da pilha AGORA. A raiz chama depois de empilhar/desempilhar.
-     *  (Era `setPhase(p)`: a casca gravava o valor E projetava. Empilhar é da raiz — ela é quem nomeia as cenas.) */
-    aplicarCena: () => void;
-    /** Põe o 1º `.pm-btn` (Continuar) selecionado em CADA tela de pausa. */
+    /** Projects onto the document the scene on top of the stack NOW. The root calls it after pushing or popping: pushing
+     *  is the root's, since the root names the scenes. */
+    applyScene: () => void;
+    /** Selects the 1st `.pm-btn` (Continue) on EACH pause screen. */
     pauseSelect: () => void;
-    /** Modo Print: esconde as pausas para ver a tela limpa; qualquer tecla/clique as traz de volta. */
+    /** Print mode: hides the pause cards to see the screen clean; any key or click brings them back. */
     printMode: () => void;
-    /** Repinta `#title-legend` com o dispositivo e o mapeamento vigentes do Jogador 1. */
+    /** Repaints `#title-legend` with Player 1's current device and mapping. */
     updateTitleLegend: () => void;
-    /** A tabela de ações do menu de pausa — consumida por ui/pause-icons.ts (`getPauseActs`). */
+    /** The pause card's action table — read by ui/pause-icons.ts (`getPauseActs`). */
     pauseActs: PauseActs;
 }
 export declare function initShell(ctx: ShellCtx): ShellApi;