@the-inclusionist/engine 10.0.0 → 11.0.0

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

@@ -1,5 +1,11 @@
 // 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. */
@@ -13,6 +19,29 @@ export declare const KEY_RIGHT: ReadonlySet<string>;
  * 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. */

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

@@ -1,5 +1,10 @@
 // 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). */
@@ -17,7 +22,7 @@ export const KEY_RIGHT = new Set(['ArrowRight', 'KeyD']);
  */
 export function menuKeyIntent(code, act) {
     return {
-        yes: KEY_YES.has(code) || act === 'action2',
+        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',
@@ -25,6 +30,35 @@ export function menuKeyIntent(code, act) {
         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));

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

@@ -8,3 +8,13 @@ export declare const ITEM_SELECTOR = "button:not([disabled]), select:not([disabl
  * 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

@@ -5,6 +5,8 @@
 // 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. */
@@ -20,3 +22,30 @@ export function navigableItems(card) {
 }
 // 🔴 `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,9 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** ui/dom.ts `$` — injected; the module never reaches `document`. */
-export type { DomQuery } from '../core/dom-query.js';
-/** The intent, not the key. Defined once in input/edges; only re-exported here. */
+/** The intent, not the key. Defined once in input/edges. */
 import type { NavKeys } from '../input/edges.js';
-export type { NavKeys } from '../input/edges.js';
 /** What this module reads from a `KeyboardEvent`. */
 export interface NavKeyEvent {
     code: string;
@@ -13,6 +10,7 @@ export interface NavKeyEvent {
 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 { stepInRing } from '../core/ring.js';
 export interface MenuNavCtx {
@@ -72,6 +70,12 @@ export interface MenuNavCtx {
     closePadWiz: (save: boolean) => void;
     /** input/keyboard-runtime.ts: whose key is this? (-1 = generic). */
     whichPlayer: (code: string) => number;
+    /**
+     * 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;
     /** Where `attach()` installs the menus' listeners, in CAPTURE. See `EventTargetLike` in input/touch-bindings. */
@@ -94,6 +98,38 @@ export interface MenuNavApi {
     navPause: (menu: HTMLElement, playerIndex: number, k: NavKeys) => void;
     /** The keyboard translator. Exported on its own so a test can fire it without depending on the propagation phase. */
     menuNavKey: (e: NavKeyEvent) => void;
+    /**
+     * 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;
 }

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

@@ -51,7 +51,7 @@
 // ---------------------------------------------------------------------------------------------------------
 /** Was any intent expressed? Defined once in input/edges; here under the name this module has always used. */
 import { hasNavIntent as hasIntent } from '../input/edges.js';
-import { showPauseOptions, PM_VISIBLE_ITEMS } from './pause-icons.js';
+import { backToRoot, markPauseItem, PM_VISIBLE_ITEMS } from './pause-icons.js';
 import { announceItem } from './item-announcement.js';
 import { accessibleLabel } from '../core/accessible-label.js';
 import { stepInRing } from '../core/ring.js';
@@ -103,6 +103,17 @@ const CONTROL_KINDS = [
 ];
 /** Where the items live: the dialog's card (`.overlay__card`) or the pause card (`.pause-card`). */
 const CARD_SELECTOR = '.overlay__card, .pause-card';
+/**
+ * WHAT LEFT AND RIGHT DO TO A PANEL'S CONTROL — ONE answer, read by the keys (`sideways`, `confirm`) and by one-button scanning
+ * (`underCursor`), so a scan never offers «increase» where the right key would walk the ring instead: a `<select>` is a list, a
+ * slider (the only `<input>` an item can be, `ui/menu-items`) or a ⯇ ⯈ steps control (ADR-0151) is a value, anything else
+ * is an item.
+ */
+function cursorKind(el) {
+    if (el.tagName === 'SELECT')
+        return 'list';
+    return el.tagName === 'INPUT' || el.hasAttribute('data-passos') ? 'value' : 'item';
+}
 export function initMenuNav(ctx) {
     const { t } = ctx;
     /* ===================== settings dialogs ===================== */
@@ -168,6 +179,10 @@ export function initMenuNav(ctx) {
      */
     function sideways(items, idx, d) {
         const cur = items[idx];
+        if (cursorKind(cur) === 'item') {
+            focusAndSay(items, stepInRing(items.length, idx, d));
+            return;
+        }
         if (cur.tagName === 'SELECT') {
             const before = cur.value;
             tweakSelect(cur, d);
@@ -182,23 +197,19 @@ export function initMenuNav(ctx) {
             return;
         }
         // A steps control ⯇ ⯈ (ADR-0151): left and right are the adjustment itself; its owner listens to `passo` (and announces).
-        if (cur.hasAttribute('data-passos')) {
-            cur.dispatchEvent(new CustomEvent('passo', { detail: d, bubbles: true }));
-            return;
-        }
-        focusAndSay(items, stepInRing(items.length, idx, d));
+        cur.dispatchEvent(new CustomEvent('passo', { detail: d, bubbles: true }));
     }
     /** «Yes»: a list goes round and says the new option; a slider or a steps control has nothing to confirm; anything else is clicked. */
     function confirm(items, idx) {
         const cur = items[idx];
-        if (cur.tagName === 'SELECT') {
+        const kind = cursorKind(cur);
+        if (kind === 'list') {
             tweakSelect(cur, 'wrap');
             sayItem(items, idx);
             return;
         }
-        if (cur.tagName === 'INPUT' || cur.hasAttribute('data-passos'))
-            return;
-        cur.click();
+        if (kind === 'item')
+            cur.click();
     }
     function navDialog(menu, k) {
         const items = menuItems(menu);
@@ -228,8 +239,7 @@ export function initMenuNav(ctx) {
     function pauseSetSel(menu, el) {
         if (!el)
             return; // an index outside the list (an empty card): touch nothing
-        menu.querySelectorAll('.pm-sel').forEach((b) => b.classList.remove('pm-sel'));
-        el.classList.add('pm-sel');
+        markPauseItem(menu, el); // the one place the card's cursor moves, and is kept in view (issue #134)
     }
     function navPause(menu, playerIndex, k) {
         if (k.no) {
@@ -238,8 +248,9 @@ export function initMenuNav(ctx) {
             // «is this the options list?»: with three lists (ADR-0146), asking the second would make «no» from the game's own
             // options resume the game when the child asked to go back.
             const open = menu.querySelector('.pause-menu:not([hidden])');
+            // ⚠️ AND THE CURSOR LANDS ON THE DOOR THAT OPENED THE LIST (ADR-0130 rule 1), not on the root's first item.
             if (open && open.dataset.sub && open.dataset.sub !== 'raiz') {
-                showPauseOptions(menu, 'raiz');
+                backToRoot(menu);
                 return;
             }
             ctx.setPhase('playing');
@@ -275,20 +286,21 @@ export function initMenuNav(ctx) {
         ctx.explainItem?.(reason || null);
     }
     /* ===================== keyboard ===================== */
+    const padWizOpen = () => { const pw = ctx.$('#padwiz'); return !!pw && !pw.hidden; };
     /** The controller-mapping panel sits ON TOP of everything: while it is open, only Escape gets through (and cancels). */
     function padWizKey(e) {
-        const pw = ctx.$('#padwiz');
-        if (!pw || pw.hidden)
+        if (!padWizOpen())
             return false;
         if (e.code === 'Escape') {
             ctx.closePadWiz(false);
-            e.preventDefault();
-            e.stopPropagation();
+            consume(e);
         }
         return true; // open = consumed (even when it is not Escape: no menu underneath navigates while it is open)
     }
-    /** Consumes the key: it was ours, and nobody else should see it. One function, so the pair never comes apart. */
-    const consume = (e) => { e.preventDefault(); e.stopPropagation(); };
+    /** The key events the menus consumed, for `consumed` — weak, so an event is forgotten with it. */
+    const consumedKeys = new WeakSet();
+    /** Consumes the key: it was ours, and nobody else should see it. One function, so the three never come apart. */
+    const consume = (e) => { e.preventDefault(); e.stopPropagation(); consumedKeys.add(e); };
     function menuNavKey(e) {
         if (ctx.isCapturing())
             return; // a remap in progress: the key is its
@@ -303,16 +315,54 @@ export function initMenuNav(ctx) {
         // through `input/gamepad`; the keyboard has no pair of its own for it, because Enter is already «confirm» and taking
         // it would leave the child no way to ACTIVATE the icon under the cursor.
         const { player, keys } = intentOf(e.code);
-        if (ctx.onBar(player)) {
-            if (hasIntent(keys)) {
-                consume(e);
-                ctx.navBar(player, keys);
-            }
-            return; // on the bar, a menu key belongs to the bar — with or without an intent, it does not reach the character
-        }
-        if (!ctx.isNavigable() || !hasIntent(keys))
+        // on the bar, a key with no intent is not consumed either — it simply moves nothing
+        if (!hasIntent(keys) || !menusTake(player))
             return;
-        navOpenMenu(e, player, keys);
+        // THE KEY IS CONSUMED BEFORE THE MENU MOVES: a step that closes the last menu leaves no menu for a later listener to see
+        consume(e);
+        steerMenus(player, keys);
+    }
+    /**
+     * Would a key of player `pi` with an intent move a menu now? The quick bar first — it works with the game RUNNING — then the
+     * dialog on top or that player's open pause card, and only where a menu may be navigated.
+     *
+     * 📌 THE KEY IS CONSUMED ONLY IF THERE IS SOMETHING TO NAVIGATE. A game whose settings are always open answers
+     * `isNavigable(): true`, and consuming before knowing would swallow every key with a menu intent — the arrows that choose
+     * an answer in the quiz, for one. DEFECT 2's safety net stays: with a dialog open the key IS consumed, so one Escape closes
+     * the dialog and no later listener sees it.
+     */
+    function menusTake(pi) {
+        return ctx.onBar(pi) || (ctx.isNavigable() && !!menuUnderKeys(pi));
+    }
+    /** One step of the menu a key of `pi` moves: the bar, else the dialog on top, else that player's own pause card. */
+    function steerMenus(pi, k) {
+        if (ctx.onBar(pi)) {
+            ctx.navBar(pi, k);
+            return;
+        }
+        const open = menuUnderKeys(pi);
+        if (open?.inPause)
+            navPause(open.menu, pi, k);
+        else if (open)
+            navDialog(open.menu, k);
+    }
+    /**
+     * AN INTENT WITH NO KEY (ADR-0218 erratum of 2026-09-26): one-button scanning offers a menu's own steps and takes one with a
+     * press that is not a menu key — so it asks here, and the step goes the way a key's would, under the same guards.
+     * The controller-mapping panel on top takes only «back», which cancels it, as Escape does.
+     */
+    function navIntent(pi, k) {
+        if (ctx.isCapturing())
+            return false;
+        if (padWizOpen()) {
+            if (k.no)
+                ctx.closePadWiz(false);
+            return true;
+        }
+        if (!hasIntent(k) || !menusTake(pi))
+            return false;
+        steerMenus(pi, k);
+        return true;
     }
     /** Whose key this is — a key no player owns is Player 1's — and what it asks of a menu. */
     function intentOf(code) {
@@ -320,26 +370,60 @@ export function initMenuNav(ctx) {
         const player = owner < 0 ? 0 : owner;
         return { player, keys: menuKeyIntent(code, owner >= 0 ? ctx.actionOf(code, player) : null) };
     }
-    /** The key moves the dialog on top if there is one, else the player's own pause card if it is open, else nothing. */
-    function navOpenMenu(e, pi, k) {
-        // THE KEY IS CONSUMED ONLY IF THERE IS SOMETHING TO NAVIGATE. A game whose settings are always open answers
-        // `isNavigable(): true`, and consuming before knowing would swallow every key with a menu intent — the arrows that
-        // choose an answer in the quiz, for one.
-        //
-        // DEFECT 2's safety net stays: with a dialog open the key IS consumed, so one Escape closes the dialog and no later
-        // listener sees it.
+    /**
+     * The menu a key of player `pi` moves: the dialog on top if there is one, else that player's OWN open pause card — and none for
+     * a player who does not lead this screen (ADR-0144 erratum): the dialog on top is the screen's, not every seat's.
+     */
+    function menuUnderKeys(pi) {
+        if (ctx.leadsTheScreen && !ctx.leadsTheScreen(pi))
+            return null;
         const dlg = sharedDialogOpen();
-        if (dlg) {
-            consume(e);
-            navDialog(dlg, k);
-            return;
-        } // an accessibility dialog is open: it is the one navigated
-        const menu = ctx.getPauseMenu(pi); // otherwise: the player's OWN pause card
-        if (menu && !menu.hidden) {
-            consume(e);
-            navPause(menu, pi, k);
+        if (dlg)
+            return { menu: dlg, inPause: false };
+        const menu = ctx.getPauseMenu(pi);
+        return menu && !menu.hidden ? { menu, inPause: true } : null;
+    }
+    /* ===================== an item said by name (ADR-0194) ===================== */
+    /**
+     * The stops of the menu a key of `pi` would move NOW, under the same guards `menuNavKey` applies before moving one: a name is
+     * sayable exactly where confirming would reach it, so the confirm that follows `pointAt` lands on the named item.
+     *
+     * 🔴 LOCKED STOPS INCLUDED (ADR-0194 §5, ADR-0161): the cursor stops on a locked item, so its name is sayable too — and what
+     * saying it does is what confirming it does, because it IS a confirm: the item's own press says its reason and acts on nothing
+     * (`ui/pause-icons.pressPauseItem`, a panel's refusal). No second, voice-only «say the reason» exists to drift from that one.
+     */
+    function sayableItems(pi) {
+        if (ctx.isCapturing() || padWizOpen() || ctx.onBar(pi) || !ctx.isNavigable())
+            return null;
+        const open = menuUnderKeys(pi);
+        if (!open)
+            return null;
+        return { ...open, items: open.inPause ? [...open.menu.querySelectorAll(PM_VISIBLE_ITEMS)] : menuItems(open.menu) };
+    }
+    function itemNames(pi) {
+        return (sayableItems(pi)?.items ?? []).map((el) => accessibleLabel(el)).filter(Boolean);
+    }
+    /** A panel's control under the cursor — where `navDialog` would put a step: the focused item, else the first (`cursorIn`). */
+    function underCursor(pi) {
+        const open = sayableItems(pi);
+        if (!open || open.inPause)
+            return 'item';
+        const at = open.items.indexOf(ctx.getActiveElement());
+        const el = open.items[at >= 0 ? at : 0];
+        return el ? cursorKind(el) : 'item';
+    }
+    function pointAt(name, pi) {
+        const open = sayableItems(pi);
+        const el = open?.items.find((it) => accessibleLabel(it) === name);
+        if (!open || !el)
+            return false;
+        if (open.inPause) {
+            pauseSetSel(open.menu, el);
+            ctx.explainItem?.(null);
         }
-        // No dialog and no card: the key is NOT ours. It goes on to whoever owns it.
+        else
+            el.focus();
+        return true;
     }
     /* ===================== holding on an item ===================== */
     /*
@@ -413,5 +497,6 @@ export function initMenuNav(ctx) {
         ctx.win.addEventListener('pointercancel', onRelease, true);
         ctx.win.addEventListener('click', onClick, true);
     }
-    return { sharedDialogOpen, menuItems, menuFocus, dialogBack, navDialog, pauseSetSel, navPause, menuNavKey, attach };
+    const consumed = (e) => consumedKeys.has(e);
+    return { sharedDialogOpen, menuItems, menuFocus, dialogBack, navDialog, pauseSetSel, navPause, menuNavKey, consumed, navIntent, underCursor, itemNames, pointAt, attach };
 }

package/dist-pkg/ui/panel-widgets.d.ts

@@ -112,5 +112,39 @@ export declare function nextStep(from: number, total: number, delta: number): nu
  * controller's left and right emit it through `ui/menu-nav`. The user listens to a single event.
  */
 export declare function mountSteps(ctx: PanelShellCtx, spec: StepsSpec): HTMLElement;
+/**
+ * How many positions still CYCLE. The Dev's number (ADR-0130 erratum, 2026-09-12): «Acima de cinco itens deve ser dropdown».
+ * Five or fewer are one row «◀ Label: value ▶» — every position is one step away and the row always says where it is;
+ * more than five, a dropdown, because a cycle that long is walked more than it is chosen.
+ */
+export declare const MAX_CYCLE_POSITIONS = 5;
+/** One position of an exclusive choice: what is stored, and what is shown and heard (already translated). */
+export interface ChoicePosition {
+    readonly value: string;
+    readonly label: string;
+}
+/** An exclusive choice: its spoken name, its positions in order, and the value in use. */
+export interface ChoiceSpec {
+    readonly label: string;
+    readonly values: readonly ChoicePosition[];
+    readonly current: string;
+}
+/**
+ * Builds the control for ONE EXCLUSIVE CHOICE, and its SIZE picks the control, not the panel's author (ADR-0130 rule 3):
+ * up to `MAX_CYCLE_POSITIONS` a steps control (`mountSteps`), more a `<select>`. A choice whose size depends on the moment —
+ * the game's named positions, the audio outputs plugged in — takes the control its size asks for NOW, drawn again when it
+ * changes.
+ *
+ * Both shapes answer the same way, so whoever builds a row does not branch: `pick(value)` runs when the child chooses, the
+ * value in use is in `data-value`, and a bubbling `change` follows the pick — a list that listens for `change` hears either.
+ * A value not among the positions shows the first, as a `<select>` does.
+ */
+export declare function mountChoice(ctx: PanelShellCtx, spec: ChoiceSpec, pick: (value: string) => void): HTMLElement;
+/**
+ * REWRITES a choice built by `mountChoice`: its name, its positions' words and the value in use — the redraw a panel does
+ * on every open, after a language change or when the value moved elsewhere. The SHAPE stays: a choice whose size can
+ * cross five is built again, not updated.
+ */
+export declare function updateChoice(el: HTMLElement, spec: ChoiceSpec): void;
 /** Reflects the current position: the written value, what is heard, and the ends that no longer move. */
 export declare function updateSteps(el: HTMLElement, spec: StepsSpec): void;

package/dist-pkg/ui/panel-widgets.js

@@ -187,6 +187,92 @@ export function mountSteps(ctx, spec) {
     updateSteps(el, spec);
     return el;
 }
+/* ===================== ONE EXCLUSIVE CHOICE, DRAWN BY ITS SIZE (ADR-0130 rule 3 and erratum) ===================== */
+/**
+ * How many positions still CYCLE. The Dev's number (ADR-0130 erratum, 2026-09-12): «Acima de cinco itens deve ser dropdown».
+ * Five or fewer are one row «◀ Label: value ▶» — every position is one step away and the row always says where it is;
+ * more than five, a dropdown, because a cycle that long is walked more than it is chosen.
+ */
+export const MAX_CYCLE_POSITIONS = 5;
+/**
+ * Builds the control for ONE EXCLUSIVE CHOICE, and its SIZE picks the control, not the panel's author (ADR-0130 rule 3):
+ * up to `MAX_CYCLE_POSITIONS` a steps control (`mountSteps`), more a `<select>`. A choice whose size depends on the moment —
+ * the game's named positions, the audio outputs plugged in — takes the control its size asks for NOW, drawn again when it
+ * changes.
+ *
+ * Both shapes answer the same way, so whoever builds a row does not branch: `pick(value)` runs when the child chooses, the
+ * value in use is in `data-value`, and a bubbling `change` follows the pick — a list that listens for `change` hears either.
+ * A value not among the positions shows the first, as a `<select>` does.
+ */
+export function mountChoice(ctx, spec, pick) {
+    if (spec.values.length <= MAX_CYCLE_POSITIONS) {
+        const steps = mountSteps(ctx, stepsOf(spec));
+        writeCycle(steps, spec);
+        steps.addEventListener('passo', (ev) => {
+            // read back from the element, never from this closure: an `updateChoice` since may have brought other words
+            const live = readCycle(steps);
+            const from = indexOfValue(live);
+            const to = nextStep(from, live.values.length, ev.detail);
+            if (to === from)
+                return; // at the wall nothing moved, and nothing is picked
+            const value = live.values[to].value;
+            writeCycle(steps, { ...live, current: value });
+            pick(value);
+            steps.dispatchEvent(new Event('change', { bubbles: true }));
+        });
+        return steps;
+    }
+    const list = ctx.create('select');
+    list.className = 'vol';
+    fillList(list, spec);
+    list.addEventListener('change', () => { list.dataset.value = list.value; pick(list.value); });
+    return list;
+}
+/** Where the current value sits among the positions; one not among them shows the first, as a `<select>` does. */
+const indexOfValue = (s) => Math.max(0, s.values.findIndex((v) => v.value === s.current));
+const stepsOf = (s) => ({ label: s.label, values: s.values.map((v) => v.label), current: indexOfValue(s) });
+/**
+ * A cycle row keeps its whole choice ON THE ELEMENT — the positions in `data-positions`, the value in `data-value`, the
+ * name in `aria-label` — so the control carries no state of its own that a redraw could leave behind.
+ */
+function writeCycle(el, s) {
+    el.dataset.positions = JSON.stringify(s.values);
+    el.dataset.value = s.current;
+    updateSteps(el, stepsOf(s));
+}
+function readCycle(el) {
+    return {
+        label: el.getAttribute('aria-label') ?? '',
+        values: JSON.parse(el.dataset.positions ?? '[]'),
+        current: el.dataset.value ?? '',
+    };
+}
+function fillList(list, s) {
+    // a `<select>` whose label is a sibling is announced as «combo box» and nothing else without its own name
+    list.setAttribute('aria-label', s.label);
+    while (list.firstChild)
+        list.removeChild(list.firstChild);
+    for (const v of s.values) {
+        const option = list.ownerDocument.createElement('option');
+        option.value = v.value;
+        option.textContent = v.label; // text, never markup: a game's word goes through here
+        list.appendChild(option);
+    }
+    list.value = s.current;
+    list.dataset.value = list.value;
+}
+/**
+ * REWRITES a choice built by `mountChoice`: its name, its positions' words and the value in use — the redraw a panel does
+ * on every open, after a language change or when the value moved elsewhere. The SHAPE stays: a choice whose size can
+ * cross five is built again, not updated.
+ */
+export function updateChoice(el, spec) {
+    if (el.tagName === 'SELECT')
+        fillList(el, spec);
+    // read by the attribute `writeCycle` always writes, and not by `hasAttribute`: a host's minimal document may lack it
+    else if (el.dataset?.positions !== undefined)
+        writeCycle(el, spec);
+}
 /** Reflects the current position: the written value, what is heard, and the ends that no longer move. */
 export function updateSteps(el, spec) {
     const lastIndex = Math.max(0, spec.values.length - 1);