@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/ui/loop-crash.d.ts

@@ -1,23 +1,23 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** O id da caixa do aviso. Estável porque a folha de estilo e o teste a procuram. */
-export declare const AVISO_DE_QUEDA_ID = "incl-parou";
-export interface AvisoDeQuedaCtx {
-    /** `querySelector` do documento deste jogo. Injetado: a engine recebe o dela, `main.ts` passa o `$` global. */
-    procurar: (sel: string) => HTMLElement | null;
-    /** `document.createElement` — a caixa do aviso é um elemento de verdade, não um pseudo-elemento. */
-    criar: (tag: string) => HTMLElement;
-    /** A narração falada, quando o jogo tiver uma. Ausente = o aviso escrito basta. */
-    narrar?: (texto: string) => void;
+import type { Translate } from '../core/i18n.js';
+export interface CrashNoticeCtx {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    /** `querySelector` of this game's document. Injected: the engine receives its own. */
+    find: (sel: string) => HTMLElement | null;
+    /** `document.createElement` — the notice box is a real element, not a pseudo-element. */
+    create: (tag: string) => HTMLElement;
+    /** The spoken narration, when the game has one. Absent = the written notice is enough. */
+    narrate?: (text: string) => void;
 }
 /**
- * Monta o `aoFalhar` para entrar em `startLoop(ticker, quadro, maxDt, { aoFalhar })`.
+ * Builds the handler for `startLoop(ticker, frame, maxDt, { speed, onFailure })`.
  *
- * A ORDEM DOS CANAIS É DELIBERADA e vale escrever: o console PRIMEIRO, porque quem depura não pode perder o
- * erro se o DOM estiver quebrado — e um DOM quebrado é um dos motivos plausíveis para o quadro ter lançado.
- * Depois o leitor de tela, que é quem não tem outra pista nenhuma. O visível por último, porque quem o vê já
- * viu a tela parar.
+ * THE ORDER OF THE CHANNELS IS DELIBERATE: the console FIRST, because whoever debugs must not lose the error if the DOM
+ * is broken — and a broken DOM is one plausible reason the frame threw. Then the screen reader, which has no other clue
+ * at all. The visible one last, because whoever sees it has already seen the screen stop.
  *
- * Cada canal é isolado do seguinte: se a narração lançar, o aviso escrito já saiu. Um aviso que falha pela
- * metade tem de entregar a outra metade — é a mesma regra que o `startLoop` aplica a este próprio callback.
+ * Each channel is isolated from the next: if narration throws, the written notice has already gone out. A notice that
+ * fails halfway must deliver the other half — the same rule `startLoop` applies to this very callback.
  */
-export declare function criarAvisoDeQueda(ctx: AvisoDeQuedaCtx): (erro: unknown) => void;
+export declare function createCrashNotice(ctx: CrashNoticeCtx): (failure: unknown) => void;

package/dist-pkg/ui/loop-crash.js

@@ -1,79 +1,50 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/loop-crash.ts — O ANÚNCIO DE QUE O LAÇO PAROU. A outra metade do ADR-0054.
-//
-// `core/loop.startLoop` já PARA quando um quadro lança, e já chama `aoFalhar`. O que faltava era alguém que
-// passasse um `aoFalhar` — e a `confirmation` do ADR-0054 diz isso por escrito: *"a raiz de composição ainda
-// não liga o `aoFalhar`, então hoje o laço para em silêncio... enquanto isto não existir este registro é só
-// metade verdadeiro."*
-//
-// ⚠️ E A METADE QUE FALTAVA É A QUE IMPORTA. Tela congelada é sintoma VISUAL. No modo cego, um jogo parado e
-// um jogo pensando produzem a mesma coisa: silêncio. A criança fica a esperar por um jogo que já morreu, sem
-// nada que lhe diga para recarregar — e o único aviso que existia era um erro no console, que ela não lê.
-//
-// ⚠️ POR QUE UM MÓDULO E NÃO UMA LINHA DENTRO DE `createGame`. Porque o jogo de plataforma NÃO PASSA POR
-// `createGame` — `main.ts` monta a engine à mão, e é ele quem chama `startLoop`. Uma solução que vivesse só
-// na raiz de composição da engine deixaria de fora exatamente o jogo que existe. As duas raízes importam
-// daqui.
-//
-// ⚠️ E NÃO USA `srAlert` DE `core/a11y-sr`, o que é uma escolha e não um esquecimento:
-//
-//   · `srAlert` limpa, espera um `requestAnimationFrame` e só então escreve. Essa dança existe para forçar o
-//     leitor a REANUNCIAR texto repetido; uma queda é anunciada uma vez e nunca se repete, então não compra
-//     nada aqui — e faz o aviso depender de um quadro futuro, no instante em que os quadros pararam.
-//   · `srAlert` busca no documento GLOBAL. Quem recebe o documento por injeção (a engine, um teste, um
-//     segundo jogo na mesma página) perderia o aviso. O anúncio de que tudo parou é o último lugar que
-//     deveria depender de uma busca global.
-import { t } from '../core/i18n.js';
-/** O id da caixa do aviso. Estável porque a folha de estilo e o teste a procuram. */
-export const AVISO_DE_QUEDA_ID = 'incl-parou';
+/** The id of the notice box. Stable because the stylesheet and the test look for it. */
+const CRASH_NOTICE_ID = 'incl-parou';
 /**
- * Monta o `aoFalhar` para entrar em `startLoop(ticker, quadro, maxDt, { aoFalhar })`.
+ * Builds the handler for `startLoop(ticker, frame, maxDt, { speed, onFailure })`.
  *
- * A ORDEM DOS CANAIS É DELIBERADA e vale escrever: o console PRIMEIRO, porque quem depura não pode perder o
- * erro se o DOM estiver quebrado — e um DOM quebrado é um dos motivos plausíveis para o quadro ter lançado.
- * Depois o leitor de tela, que é quem não tem outra pista nenhuma. O visível por último, porque quem o vê já
- * viu a tela parar.
+ * THE ORDER OF THE CHANNELS IS DELIBERATE: the console FIRST, because whoever debugs must not lose the error if the DOM
+ * is broken — and a broken DOM is one plausible reason the frame threw. Then the screen reader, which has no other clue
+ * at all. The visible one last, because whoever sees it has already seen the screen stop.
  *
- * Cada canal é isolado do seguinte: se a narração lançar, o aviso escrito já saiu. Um aviso que falha pela
- * metade tem de entregar a outra metade — é a mesma regra que o `startLoop` aplica a este próprio callback.
+ * Each channel is isolated from the next: if narration throws, the written notice has already gone out. A notice that
+ * fails halfway must deliver the other half — the same rule `startLoop` applies to this very callback.
  */
-export function criarAvisoDeQueda(ctx) {
-    return (erro) => {
+export function createCrashNotice(ctx) {
+    const { t } = ctx;
+    return (failure) => {
         try {
-            console.error('[inclusionist] the frame threw; the loop stopped.', erro);
+            console.error('[inclusionist] the frame threw; the loop stopped.', failure);
         }
         catch { /* noop */ }
         const msg = t('sr.laco.parou');
-        // O leitor de tela: assertivo, porque interromper é justamente o ponto.
-        const alerta = ctx.procurar('#sr-alert');
-        if (alerta)
-            alerta.textContent = msg;
+        // The screen reader: assertive, because interrupting is exactly the point.
+        const alert = ctx.find('#sr-alert');
+        if (alert)
+            alert.textContent = msg;
         try {
-            ctx.narrar?.(msg);
+            ctx.narrate?.(msg);
         }
-        catch { /* noop: a narração falhou; o aviso escrito já saiu */ }
-        // O VISÍVEL, e é um ELEMENTO DE VERDADE — não um pseudo-elemento.
+        catch { /* noop: narration failed; the written notice has already gone out */ }
+        // THE VISIBLE ONE, and it is a REAL ELEMENT — not a pseudo-element, for two reasons:
         //
-        // ⚠️ ERA `::after` COM `content: attr(data-incl-parou)`, E NUNCA TERIA APARECIDO. Medido no arranque real
-        // em 2026-09-06: `.game-region.crt-scan-1::after` é o efeito de scanline do CRT, ligado por padrão, e um
-        // elemento tem UM `::after` só — as duas regras não se empilham, a do CRT vem depois e vence. O
-        // `::before` está igualmente tomado, pela vinheta. O aviso disputava um lugar já ocupado.
+        // ⚠️ the region's `::after` and `::before` are already taken by the CRT scanlines and the vignette, and an element
+        // has ONE of each — a notice there competes for an occupied place and loses;
         //
-        // ⚠️ E O PSEUDO-ELEMENTO ERA ERRADO POR UMA SEGUNDA RAZÃO, que a primeira escondia: texto de `content`
-        // não entra de forma confiável na árvore de acessibilidade. O aviso de que o jogo morreu é exatamente o
-        // que não pode depender disso.
+        // ⚠️ and `content` text does not reliably enter the accessibility tree. The notice that the game died is exactly
+        // what cannot depend on that.
         //
-        // O raciocínio que continua de pé é o da TRADUÇÃO: a frase vem de `t()` e entra por `textContent`, então
-        // ela chega traduzida e escapada. O que muda é o recipiente.
-        const regiao = ctx.procurar('#game-region');
-        if (!regiao)
+        // The sentence comes from `t()` and goes in through `textContent`, so it arrives translated and escaped.
+        const region = ctx.find('#game-region');
+        if (!region)
             return;
-        const anterior = ctx.procurar('#' + AVISO_DE_QUEDA_ID);
-        const caixa = anterior ?? ctx.criar('div');
-        caixa.id = AVISO_DE_QUEDA_ID;
-        caixa.setAttribute('role', 'alert');
-        caixa.textContent = msg;
-        if (!anterior)
-            regiao.appendChild(caixa);
+        const previous = ctx.find('#' + CRASH_NOTICE_ID);
+        const notice = previous ?? ctx.create('div');
+        notice.id = CRASH_NOTICE_ID;
+        notice.setAttribute('role', 'alert');
+        notice.textContent = msg;
+        if (!previous)
+            region.appendChild(notice);
     };
 }

package/dist-pkg/ui/menu-intent.d.ts

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { NavKeys } from '../input/edges.js';
+/** Confirm/enter. `NumpadEnter` counts here (but does NOT pause — see `input/keydown`). */
+export declare const KEY_YES: ReadonlySet<string>;
+/** Back. ⚠️ DEFECT 2: `Escape` is the SAME intent as the gamepad's "special" action. */
+export declare const KEY_NO: ReadonlySet<string>;
+export declare const KEY_UP: ReadonlySet<string>;
+export declare const KEY_DOWN: ReadonlySet<string>;
+export declare const KEY_LEFT: ReadonlySet<string>;
+export declare const KEY_RIGHT: ReadonlySet<string>;
+/**
+ * Translates (physical key, the key owner's remapped action) → intent. `act` is `null` when the key belongs to no
+ * player (a generic key).
+ */
+export declare function menuKeyIntent(code: string, act: string | null): NavKeys;
+/** `select` with left/right: one step, WITHOUT wrapping — adjusting a VALUE is not navigating a list. */
+export declare function selectStep(selectedIndex: number, optionsLen: number, delta: number): number;
+/** `select` with "yes": one step, WITH wrapping. That is the deliberate difference between confirming and adjusting. */
+export declare function selectWrap(selectedIndex: number, optionsLen: number): number;
+/** `input[type=range]` with left/right: one `step` (default 1), clamped between `min` and `max`. */
+export declare function rangeStep(value: number, min: number, max: number, step: number, delta: number): number;
+/**
+ * THE CURSOR STEP IN THE PAUSE MENU — a RING, because the pause card is one list (ADR-0044, items 1 and 7).
+ *
+ * XAG 106 allows wrapping for a LINEAR menu and FORBIDS it for a two-dimensional grid — in a grid, wrapping
+ * teleports the cursor to the other corner and the person loses track of where they are. With the icon bar in the
+ * HUD, the card is a single list, so wrapping is the recommended behaviour rather than a forbidden one — and there
+ * are no zone-crossing rules for a child to discover without seeing.
+ *
+ * What it buys: `quit` is ONE key UP from `resume`. Last to be read, next to the finger.
+ */
+export declare function stepInPause(len: number, idx: number, k: NavKeys): number;

package/dist-pkg/ui/menu-intent.js

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { stepInRing } from '../core/ring.js';
+/* The GENERIC key tables (the ones that hold for any player, even with no remap). They are `Set`s because that is
+   what they are — membership, not order — and because a named `Set` keeps the table auditable from outside (the
+   test imports the constant instead of repeating the literals). */
+/** Confirm/enter. `NumpadEnter` counts here (but does NOT pause — see `input/keydown`). */
+export const KEY_YES = new Set(['Space', 'KeyJ', 'Enter', 'NumpadEnter']);
+/** Back. ⚠️ DEFECT 2: `Escape` is the SAME intent as the gamepad's "special" action. */
+export const KEY_NO = new Set(['Escape']);
+export const KEY_UP = new Set(['ArrowUp', 'KeyW']);
+export const KEY_DOWN = new Set(['ArrowDown', 'KeyS']);
+export const KEY_LEFT = new Set(['ArrowLeft', 'KeyA']);
+export const KEY_RIGHT = new Set(['ArrowRight', 'KeyD']);
+/**
+ * Translates (physical key, the key owner's remapped action) → intent. `act` is `null` when the key belongs to no
+ * player (a generic key).
+ */
+export function menuKeyIntent(code, act) {
+    return {
+        yes: KEY_YES.has(code) || act === 'action2',
+        no: KEY_NO.has(code) || act === 'action3',
+        up: KEY_UP.has(code) || act === 'up',
+        down: KEY_DOWN.has(code) || act === 'down',
+        left: KEY_LEFT.has(code) || act === 'left',
+        right: KEY_RIGHT.has(code) || act === 'right',
+    };
+}
+/** `select` with left/right: one step, WITHOUT wrapping — adjusting a VALUE is not navigating a list. */
+export function selectStep(selectedIndex, optionsLen, delta) {
+    return Math.max(0, Math.min(optionsLen - 1, selectedIndex + delta));
+}
+/** `select` with "yes": one step, WITH wrapping. That is the deliberate difference between confirming and adjusting. */
+export function selectWrap(selectedIndex, optionsLen) {
+    return (selectedIndex + 1) % optionsLen;
+}
+/** `input[type=range]` with left/right: one `step` (default 1), clamped between `min` and `max`. */
+export function rangeStep(value, min, max, step, delta) {
+    const st = step || 1; // a missing/0/NaN step becomes 1
+    return Math.max(min, Math.min(max, value + delta * st));
+}
+/**
+ * THE CURSOR STEP IN THE PAUSE MENU — a RING, because the pause card is one list (ADR-0044, items 1 and 7).
+ *
+ * XAG 106 allows wrapping for a LINEAR menu and FORBIDS it for a two-dimensional grid — in a grid, wrapping
+ * teleports the cursor to the other corner and the person loses track of where they are. With the icon bar in the
+ * HUD, the card is a single list, so wrapping is the recommended behaviour rather than a forbidden one — and there
+ * are no zone-crossing rules for a child to discover without seeing.
+ *
+ * What it buys: `quit` is ONE key UP from `resume`. Last to be read, next to the finger.
+ */
+export function stepInPause(len, idx, k) {
+    const d = (k.down || k.right) ? 1 : -1;
+    return stepInRing(len, idx < 0 ? 0 : idx, d);
+}

package/dist-pkg/ui/menu-items.d.ts

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** The controls that are a stop of the cursor. `[data-passos]` is ONE stop: its arrows are finger targets. */
+export declare const ITEM_SELECTOR = "button:not([disabled]), select:not([disabled]), input[type=range]:not([disabled]), [data-passos]";
+/**
+ * The stops of a card, in reading order — only the ones laid out.
+ *
+ * `offsetParent === null` = out of the layout flow (hidden, `display:none`, or inside a hidden tab). Without it the
+ * cursor lands on an invisible control and the screen reader announces something nobody sees.
+ */
+export declare function navigableItems(card: ParentNode): HTMLElement[];

package/dist-pkg/ui/menu-items.js

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/menu-items — WHAT COUNTS AS A MENU ITEM: the stops of the cursor, whose position the spoken index says.
+//
+// The list of stops lives HERE, once, and everything that speaks a place or keeps focus by place reads it: a second
+// copy of the selector is how «2 de 7» and the item the cursor is on drift apart. (Until ADR-0167 it also drew a
+// visible number per stop; that left — the place is heard, after the name.)
+//
+// 📌 A LEAF, importing nothing: `ui/mount-panel` needs the stops and must not pull `ui/menu-nav`, which pulls the
+// whole pause slice.
+/** The controls that are a stop of the cursor. `[data-passos]` is ONE stop: its arrows are finger targets. */
+export const ITEM_SELECTOR = 'button:not([disabled]), select:not([disabled]), input[type=range]:not([disabled]), [data-passos]';
+/**
+ * The stops of a card, in reading order — only the ones laid out.
+ *
+ * `offsetParent === null` = out of the layout flow (hidden, `display:none`, or inside a hidden tab). Without it the
+ * cursor lands on an invisible control and the screen reader announces something nobody sees.
+ */
+export function navigableItems(card) {
+    return [...card.querySelectorAll(ITEM_SELECTOR)].filter((el) => el.offsetParent !== null);
+}
+// 🔴 `numerarItens` AND `ATRIBUTO_DO_NUMERO` LEFT (ADR-0167): no stop shows a number. The list above still gives the
+// spoken index its position — «…, 2 de 7» after the name, from `ui/item-announcement.announceItem`.

package/dist-pkg/ui/menu-nav.d.ts

@@ -1,141 +1,111 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** 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';
-/** A intenção, não a tecla. Definição única em input/edges; aqui só reexportada. */
+/** The intent, not the key. Defined once in input/edges; only re-exported here. */
 import type { NavKeys } from '../input/edges.js';
 export type { NavKeys } from '../input/edges.js';
-/** O que este módulo lê de um `KeyboardEvent`. */
+/** What this module reads from a `KeyboardEvent`. */
 export interface NavKeyEvent {
     code: string;
     preventDefault(): void;
     stopPropagation(): void;
 }
-/** Confirma/entra. `NumpadEnter` conta aqui (mas NÃO pausa: ver o ouvinte de bolha do game.js). */
-export declare const KEY_YES: ReadonlySet<string>;
-/** Volta. ⚠️ DEFEITO 2: `Escape` é a MESMA intenção que a ação "especial" do gamepad. Verbatim. */
-export declare const KEY_NO: ReadonlySet<string>;
-export declare const KEY_UP: ReadonlySet<string>;
-export declare const KEY_DOWN: ReadonlySet<string>;
-export declare const KEY_LEFT: ReadonlySet<string>;
-export declare const KEY_RIGHT: ReadonlySet<string>;
-/**
- * Traduz (tecla física, ação remapeada do dono da tecla) → intenção. `act` é `null` quando a tecla não é de
- * nenhum jogador (tecla genérica). Verbatim das seis linhas de `menuNavKey`.
- */
-export declare function menuKeyIntent(code: string, act: string | null): NavKeys;
 import type { EventTargetLike } from '../input/touch-bindings.js';
 import type { DomQuery } from '../core/dom-query.js';
+import type { Translate } from '../core/i18n.js';
 export { hasNavIntent as hasIntent } from '../input/edges.js';
-export { passoNoAnel } from '../core/anel.js';
-/** `select` com esquerda/direita: um passo, SEM dar a volta — ajustar VALOR não é navegar lista (ver acima). */
-export declare function selectStep(selectedIndex: number, optionsLen: number, delta: number): number;
-/** `select` com "sim": um passo, COM volta. É a diferença deliberada entre confirmar e ajustar. */
-export declare function selectWrap(selectedIndex: number, optionsLen: number): number;
-/** `input[type=range]` com esquerda/direita: um `step` (default 1), preso entre `min` e `max`. */
-export declare function rangeStep(value: number, min: number, max: number, step: number, delta: number): number;
-/**
- * O PASSO DO CURSOR NO MENU DE PAUSA — um ANEL, agora que a pausa é uma lista (ADR-0044, itens 1 e 7).
- *
- * ISTO SUBSTITUI `pauseGridMove`, e a substituição é o desfecho do ADR-0044, não uma limpeza. O que havia
- * era uma GRADE de duas zonas — a barra de dez ícones em cima, a lista de itens em duas colunas embaixo — e
- * uma fronteira entre elas com quatro regras próprias ("de cima, 'baixo' cai sempre no primeiro item", "da
- * primeira linha, 'cima' sobe para o ícone de mesmo índice", …). Cada regra dessas era uma coisa a mais para
- * a criança descobrir sem ver, e nenhuma delas era descobrível: só se aprendia esbarrando.
- *
- * A XAG 106 permite laço para menu LINEAR e o PROÍBE para grade de duas dimensões — numa grade, dar a volta
- * teleporta o cursor para o outro canto e a pessoa perde a noção de onde está. Era por isso que o anel do
- * item 1 valia para todo menu do jogo MENOS este. Com a barra no HUD (item 7), o cartão passou a ter uma
- * lista só, e o laço deixou de ser proibido para virar o recomendado.
- *
- * O que se ganha em troca das quatro regras: `quit` fica a UMA tecla para CIMA de `resume`. Último na
- * leitura, vizinho no dedo.
- */
-export declare function passoNaPausa(len: number, idx: number, k: NavKeys): number;
+export { stepInRing } from '../core/ring.js';
 export interface MenuNavCtx {
-    /** ui/dom.ts `$` — só para achar `#padwiz`. */
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    /** ui/dom.ts `$` — only to find `#padwiz`. */
     $: DomQuery;
-    /** `document.activeElement` — injetado para o teste node poder simular foco sem DOM. */
+    /** `document.activeElement` — injected so a node test can simulate focus without a DOM. */
     getActiveElement: () => Element | null;
-    /** O overlay VISÍVEL de z-index mais alto dentro de `#game-region`. É o `sharedDialogOpen` original. */
+    /** The VISIBLE overlay with the highest z-index inside `#game-region`. */
     topVisibleOverlay: () => HTMLElement | null;
-    /** `overlays.closeById(id)` — true se havia entrada registrada para aquele diálogo. */
+    /** `overlays.closeById(id)` — true if that dialog had a registered entry. */
     closeById: (id: string) => boolean;
-    /** `vpPause[i]` — o menu de pausa da tela do jogador `i`. `buildGameHud` REATRIBUI a array. */
+    /** The pause card of player `i`'s screen, looked up when asked. */
     getPauseMenu: (playerIndex: number) => HTMLElement | null | undefined;
-    /** ui/shell.ts via o envelope içado do game.js. `no` na raiz do menu de pausa volta ao jogo. */
+    /** Changes the game phase. `no` at the pause card's root goes back to the game. */
     setPhase: (p: 'title' | 'playing' | 'paused') => void;
-    /** `let pauseActor` do game.js: "sim" no menu de pausa marca QUEM agiu (o submenu abre na aba dele).
-     *  ui/pause-icons.ts já recebe o mesmo setter — o `let` continua sendo do game.js, com seis leitores. */
+    /** «Yes» on the pause card marks WHO acted (the options open on that player's tab). `ui/pause-icons` receives the
+     *  same setter. */
     setPauseActor: (playerIndex: number) => void;
     /**
-     * ESTE É O MOMENTO DE NAVEGAR MENU? Se `false`, toda tecla passa direto.
-     *
-     * Era `if (phase !== 'paused') return`, com `phase` vindo por IMPORTAÇÃO de `core/state` — e o segundo
-     * consumidor mostrou o preço (achado 10 de `consumer-quiz`): um quiz cujos ajustes estão SEMPRE disponíveis
-     * precisava se declarar "pausado" para poder navegar os próprios menus. Não havia como trazer o próprio
-     * modelo de fases, porque não havia por onde.
+     * IS THIS A MOMENT TO NAVIGATE A MENU? If `false`, every key passes through.
      *
-     * A pergunta injetada é PROPOSITALMENTE um booleano, e não a fase. Injetar `getPhase()` teria consertado a
-     * importação e mantido a mentira: o consumidor continuaria obrigado a devolver a string `'paused'`, que é
-     * um conceito do jogo de plataforma. Perguntando "dá para navegar agora?", o jogo de plataforma responde
-     * `phase === 'paused'` e um quiz responde `true` — cada um na sua língua, e nenhum dos dois mentindo.
+     * A boolean on purpose, not the phase: asking for the phase would oblige every game to answer with the string
+     * `'paused'`, a platformer's concept. Asked «can a menu be navigated now?», a platformer answers `phase === 'paused'`
+     * and a quiz whose settings are always open answers `true` — each in its own terms, neither pretending.
      */
     isNavigable: () => boolean;
     /**
-     * `core/a11y-sr.srSay` — a região `aria-live` "polite". INJETADO porque ela alcança o `document` na hora da
-     * chamada, e este módulo não pode alcançar documento nenhum por conta própria.
+     * `core/a11y-sr.srSay` — the «polite» `aria-live` region. INJECTED because it reaches the `document` when called, and
+     * this module reaches no document on its own.
      *
-     * O menu de PAUSA precisa dela e os diálogos não: eles selecionam por FOCO, e o leitor de tela anuncia o
-     * foco sozinho. A pausa seleciona por CLASSE (`.pm-sel`), porque é desenhada dentro da tela do jogador —
-     * e classe nenhuma dispara anúncio. Sem esta injeção o menu é mudo para quem o navega por escuta.
+     * The PAUSE card needs it and the dialogs do not: dialogs select by FOCUS, which a screen reader announces by itself.
+     * The pause card selects by CLASS (`.pm-sel`), because it is drawn inside the player's screen — and no class fires an
+     * announcement. Without this the card is silent to whoever navigates it by ear.
      */
-    srSay: (texto: string) => void;
+    srSay: (text: string) => void;
     /**
-     * O índice "N de M" está ligado? (ADR-0044, item 3, e a XAG 106 exige que ele possa ser desligado.)
+     * Is the «N of M» index on? (ADR-0044 item 3; XAG 106 requires that it can be turned off.)
      *
-     * PERGUNTADO ao ctx e não lido de `core/state`, e o motivo é o mesmo do `isNavigable`: enquanto este módulo
-     * importava `core/state`, um segundo jogo não tinha como trazer o próprio modelo — o quiz teve de se
-     * declarar "pausado" para navegar os menus dele. `tests/menu-nav.node.test.js` reprova se a aresta voltar,
-     * e ela quase voltou por aqui: eu tinha escrito o `import` antes de o gate me lembrar.
+     * ASKED of the ctx rather than read from `core/state`, for the same reason as `isNavigable`: a game answers in its own
+     * model. `tests/menu-nav.node.test.js` fails if the import of `core/state` comes back.
      */
-    comIndice: () => boolean;
+    withIndex: () => boolean;
+    /** Writes the reason of a locked pause item in the screen footer, or clears it with `null` (ADR-0161). Optional. */
+    explainItem?: (text: string | null) => void;
     /**
-     * A tela `i` está no modo `accessibility` (ADR-0044, item 7)? Perguntado ANTES de `isNavigable`, porque
-     * esse modo roda com o jogo ANDANDO — é a única coisa deste módulo que age fora da pausa.
+     * Is screen `i` on the quick bar (ADR-0044 item 7)? Asked BEFORE `isNavigable`, because the bar works with the game
+     * RUNNING — the only thing in this module that acts outside the pause.
      */
-    naBarraDe: (i: number) => boolean;
-    /** Um passo dentro da barra rápida da tela `i`. */
+    onBar: (i: number) => boolean;
+    /** One step inside screen `i`'s quick bar. */
     navBar: (i: number, k: NavKeys) => void;
-    /** ui/settings-controls.ts: um remap em andamento consome a tecla — o menu não pode roubá-la. */
+    /** ui/settings-controls.ts: a remap in progress consumes the key — the menu must not steal it. */
     isCapturing: () => boolean;
-    /** input/gamepad.ts: o assistente de mapeamento fica POR CIMA de tudo; só Escape (cancela) o alcança. */
+    /** Closes the controller-mapping panel (`#padwiz`), which sits ON TOP of everything; only Escape (cancel) reaches it. */
     closePadWiz: (save: boolean) => void;
-    /** input/keyboard-runtime.ts: de quem é esta tecla? (-1 = genérica). */
+    /** input/keyboard-runtime.ts: whose key is this? (-1 = generic). */
     whichPlayer: (code: string) => number;
-    /** input/keyboard-runtime.ts: que ação esta tecla é PARA aquele jogador (respeitando o remap)? */
+    /** input/keyboard-runtime.ts: which action is this key FOR that player (honouring the remap)? */
     actionOf: (code: string, playerIndex: number) => string | null;
-    /** `window` — só para `attach()` instalar o ouvinte em CAPTURA, exatamente como o game.js fazia. */
-    /** A escuta de teclado dos menus. Ver `EventTargetLike` em input/touch-bindings. */
+    /** Where `attach()` installs the menus' listeners, in CAPTURE. See `EventTargetLike` in input/touch-bindings. */
     win: EventTargetLike;
 }
 export interface MenuNavApi {
-    /** O overlay visível mais alto (alias de `topVisibleOverlay` — ver "a duplicação que esta extração curou"). */
+    /** The highest visible overlay (an alias of `topVisibleOverlay` — see the header). */
     sharedDialogOpen: () => HTMLElement | null;
-    /** Os controles NAVEGÁVEIS de um menu: habilitados E visíveis (`offsetParent !== null`). */
+    /** A menu's NAVIGABLE controls: enabled AND visible (`offsetParent !== null`). */
     menuItems: (menu: HTMLElement) => HTMLElement[];
-    /** Foca o item atual (se já for um deles) ou o primeiro. Sai calado com `menu` nulo — ver o DEFEITO 1. */
+    /** Focuses the current item (if the focus is already on one) or the first. Leaves quietly with a null `menu` — see DEFECT 1. */
     menuFocus: (menu: HTMLElement | null) => void;
-    /** Fecha o diálogo e tenta devolver o foco ao que ficou por baixo. */
+    /** Closes the dialog and tries to give the focus back to what is left underneath. */
     dialogBack: (menu: HTMLElement) => void;
-    /** Um passo de navegação DENTRO de um diálogo de configuração. */
+    /** One navigation step INSIDE a settings dialog. */
     navDialog: (menu: HTMLElement, k: NavKeys) => void;
-    /** Marca `el` como o item selecionado de `menu` e atualiza a legenda dos ícones. */
+    /** Marks `el` as `menu`'s selected item. */
     pauseSetSel: (menu: HTMLElement, el: HTMLElement | null | undefined) => void;
-    /** Um passo de navegação DENTRO de um menu de pausa (barra de ícones + grade de itens). */
+    /** One navigation step INSIDE a pause card (its items; the quick bar is not in the card). */
     navPause: (menu: HTMLElement, playerIndex: number, k: NavKeys) => void;
-    /** O tradutor de teclado. Exportado à parte para o teste disparar sem depender da fase de propagação. */
+    /** The keyboard translator. Exported on its own so a test can fire it without depending on the propagation phase. */
     menuNavKey: (e: NavKeyEvent) => void;
-    /** Instala `menuNavKey` em CAPTURA na janela — verbatim do game.js. */
+    /** Installs `menuNavKey` on the window, in CAPTURE. */
     attach: () => void;
 }
+/**
+ * The parts a panel control SAYS (ADR-0159 rule 1, XAG 106: «Gamma, slider, 38%, 6 of 9»): the label with the ROLE, and
+ * the VALUE. The index is added by `announceItem`.
+ *
+ * The label is the row's `<strong>` when the control lives in one (it is what is SEEN, and a switch's text is its state,
+ * not its name); outside a row, or on a slider with a name of its own («Volume de Música»), it is the accessible name.
+ */
+export declare function controlParts(t: Translate, el: HTMLElement): {
+    label: string;
+    state: string;
+};
 export declare function initMenuNav(ctx: MenuNavCtx): MenuNavApi;