@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { NavKeys } from '../input/edges.js';
+import type { Action } from '../core/actions.js';
+/**
+ * The position a menu reads as «yes»: confirming the item under the cursor. Named once because a second reader presses it —
+ * the voice, which puts the cursor on an item said by name and confirms it the way every transport does (ADR-0194 §2).
+ */
+export declare const MENU_CONFIRM: Action;
+/** 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;
+/** A step of a menu one-button scanning offers — what a menu does, not a key (ADR-0218 erratum of 2026-09-26). */
+export type MenuStep = 'next' | 'previous' | 'confirm' | 'back' | 'increase' | 'decrease';
+/**
+ * WHAT ONE-BUTTON SCANNING OFFERS INSIDE A MENU, in order after «cancel» (interface log 2026-09-26). By how often a child needs
+ * each: every menu here is a ring, so «next» alone reaches every item, and it comes first; «confirm» ends every choice; «back»
+ * leaves — the quick pause, a sub-list, a panel, the card —; «previous» is a shortcut the ring already covers, so it waits last.
+ */
+export declare const MENU_SCAN: readonly MenuStep[];
+/**
+ * WHAT THE CONTROL UNDER A MENU'S CURSOR LETS A SIDEWAYS STEP DO — the question `ui/menu-nav` answers with the rule its left
+ * and right keys follow: `item` has no value (a button, a switch, the quick bar, the pause card); `list` is a `<select>`, whose
+ * value left and right step and whose «confirm» goes round; `value` is a slider or a ⯇ ⯈ steps control, which left and right
+ * adjust and «confirm» leaves untouched.
+ */
+export type MenuCursor = 'item' | 'list' | 'value';
+/**
+ * THE PASS IN A MENU, for the control under its cursor (ADR-0218 erratum; interface log 2026-09-26, the sideways step). Only a
+ * control with a value offers «increase» and «decrease» — they come right after «next», which keeps its place as the first
+ * step of every menu — and a slider or a steps control does not offer «confirm», which does nothing there: a cycle never
+ * stops on a position that does nothing (ADR-0155).
+ */
+export declare function menuScanFor(cursor: MenuCursor): readonly MenuStep[];
+export declare function menuStepKeys(step: MenuStep): 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,88 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { stepInRing } from '../core/ring.js';
+/**
+ * The position a menu reads as «yes»: confirming the item under the cursor. Named once because a second reader presses it —
+ * the voice, which puts the cursor on an item said by name and confirms it the way every transport does (ADR-0194 §2).
+ */
+export const MENU_CONFIRM = 'action2';
+/* 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 === MENU_CONFIRM,
+        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',
+    };
+}
+/**
+ * WHAT ONE-BUTTON SCANNING OFFERS INSIDE A MENU, in order after «cancel» (interface log 2026-09-26). By how often a child needs
+ * each: every menu here is a ring, so «next» alone reaches every item, and it comes first; «confirm» ends every choice; «back»
+ * leaves — the quick pause, a sub-list, a panel, the card —; «previous» is a shortcut the ring already covers, so it waits last.
+ */
+export const MENU_SCAN = ['next', 'confirm', 'back', 'previous'];
+/**
+ * THE PASS IN A MENU, for the control under its cursor (ADR-0218 erratum; interface log 2026-09-26, the sideways step). Only a
+ * control with a value offers «increase» and «decrease» — they come right after «next», which keeps its place as the first
+ * step of every menu — and a slider or a steps control does not offer «confirm», which does nothing there: a cycle never
+ * stops on a position that does nothing (ADR-0155).
+ */
+export function menuScanFor(cursor) {
+    if (cursor === 'item')
+        return MENU_SCAN;
+    const sideways = ['next', 'increase', 'decrease'];
+    return cursor === 'list' ? [...sideways, 'confirm', 'back', 'previous'] : [...sideways, 'back', 'previous'];
+}
+/**
+ * The intent a step is — the one a key with that meaning would carry, so it moves a menu the way the key does. «increase» is the
+ * right key and «decrease» the left one: the same step a keyboard adjusts a value with.
+ */
+const STEP_INTENT = {
+    next: { down: true }, previous: { up: true }, confirm: { yes: true }, back: { no: true },
+    increase: { right: true }, decrease: { left: true },
+};
+export function menuStepKeys(step) {
+    return { ...STEP_INTENT[step] };
+}
+/** `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,20 @@
+// 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[];
+/**
+ * KEEPS A MENU ITEM WHOLLY IN VIEW inside the box that scrolls it — the card, never the page (the Dev: the page itself
+ * does not scroll). A cursor that walks off the visible part of a list is a cursor the child has lost: this is what makes
+ * a list longer than the screen usable, whatever moved the cursor (issue #134, the Dev's «os menus não rolam»).
+ *
+ * The box's `scroll-padding` is honoured, so the band of explanation at the bottom of the screen, which the card runs
+ * under, never covers the item. Nothing moves when the item is already in view. A document with no layout (a node
+ * double) is left alone.
+ */
+export declare function keepInView(item: HTMLElement): void;

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

@@ -0,0 +1,51 @@
+// 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.)
+//
+// And how a stop is kept in view inside the card that scrolls it (`keepInView`), which every mover of a cursor shares.
+//
+// 📌 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`.
+/**
+ * KEEPS A MENU ITEM WHOLLY IN VIEW inside the box that scrolls it — the card, never the page (the Dev: the page itself
+ * does not scroll). A cursor that walks off the visible part of a list is a cursor the child has lost: this is what makes
+ * a list longer than the screen usable, whatever moved the cursor (issue #134, the Dev's «os menus não rolam»).
+ *
+ * The box's `scroll-padding` is honoured, so the band of explanation at the bottom of the screen, which the card runs
+ * under, never covers the item. Nothing moves when the item is already in view. A document with no layout (a node
+ * double) is left alone.
+ */
+export function keepInView(item) {
+    const view = item.ownerDocument?.defaultView;
+    if (!view || typeof item.getBoundingClientRect !== 'function')
+        return;
+    let box = item.parentElement;
+    while (box && !(/(auto|scroll)/.test(view.getComputedStyle(box).overflowY) && box.scrollHeight > box.clientHeight))
+        box = box.parentElement;
+    if (!box || box === item.ownerDocument.documentElement || box === item.ownerDocument.body)
+        return;
+    const style = view.getComputedStyle(box);
+    const top = box.getBoundingClientRect().top + box.clientTop + (parseFloat(style.scrollPaddingTop) || 0);
+    const bottom = box.getBoundingClientRect().top + box.clientTop + box.clientHeight - (parseFloat(style.scrollPaddingBottom) || 0);
+    const r = item.getBoundingClientRect();
+    if (r.top < top)
+        box.scrollTop -= top - r.top;
+    else if (r.bottom > bottom)
+        box.scrollTop += Math.min(r.bottom - bottom, r.top - top); // a tall item shows its top
+}

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

@@ -1,141 +1,147 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** ui/dom.ts `$` — injetado; o módulo nunca alcança `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. */
 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';
+import { type MenuCursor } from './menu-intent.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)? */
+    /**
+     * Does player `i` steer this screen's menus — the dialog on top and the pause card? On a screen several players share, only
+     * the first does (ADR-0144, erratum of 2026-09-26): another player's direction, confirm and back move, press and close nothing.
+     * Absent: every player does — each has a screen of her own. The quick bar is asked per player already (`onBar`).
+     */
+    leadsTheScreen?: (i: number) => boolean;
+    /** 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. */
+    /**
+     * Did the menus CONSUME this key event? `stopPropagation()` keeps it from the nodes further on, not from the listeners after
+     * `menuNavKey` on the same window capture — and the keyboard conductor is one. It asks here, so a key that moved, confirmed
+     * or CLOSED a menu is never also played in the same event (ADR-0111 erratum of 2026-09-26): with the menu already closed,
+     * «is a menu open?» answers no, and resume was answering a question too.
+     */
+    consumed: (e: object) => boolean;
+    /**
+     * ONE STEP OF A MENU WITH NO KEY: the intents move the menu a key of player `playerIndex` would move now — the quick bar,
+     * the dialog on top or that player's open pause card — through the same path and guards as `menuNavKey`. Answers whether a
+     * menu took it. One-button scanning is the caller (ADR-0218 erratum of 2026-09-26): its press is not a menu key.
+     */
+    navIntent: (playerIndex: number, keys: NavKeys) => boolean;
+    /**
+     * WHAT A SIDEWAYS STEP OF PLAYER `playerIndex` WOULD DO NOW (ADR-0218 erratum; one-button scanning offers «increase» and
+     * «decrease» only where they act): the kind of the control under the cursor of the panel on top — the focused item, or the
+     * first, where a step enters — under the guards a name said by voice has; `item` wherever a step would adjust nothing: the
+     * quick bar, a pause card, no menu, a remap, the controller-mapping panel.
+     */
+    underCursor: (playerIndex: number) => MenuCursor;
+    /**
+     * THE NAMES A CHILD CAN SAY (ADR-0194 §1): the accessible names of the items a key of player `playerIndex` would move now —
+     * the dialog on top, else that player's open pause card — and none while a key would move no menu. LOCKED items are in it
+     * (ADR-0194 §5): saying one confirms it like any transport, and a locked item confirmed says its reason and does nothing.
+     */
+    itemNames: (playerIndex: number) => string[];
+    /**
+     * PUTS THE CURSOR on the item with this accessible name, without activating it and without announcing it — the menu the
+     * name belongs to is the one `itemNames` reads. The caller then confirms through the virtual controller like any
+     * transport (ADR-0194 §2). `false` when no such item is there now: nothing moved.
+     */
+    pointAt: (name: string, playerIndex: number) => boolean;
+    /** 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;