@the-inclusionist/engine 10.0.0 → 11.0.0

package/dist-pkg/input/switch-scan.d.ts

@@ -2,7 +2,8 @@
 import type { Action } from '../core/actions.js';
 /** The safe item: taking it commands nothing. Same word the gaze cycle uses, and the same job. */
 export declare const SCAN_CANCEL = "cancel";
-export type ScanItem = Action | typeof SCAN_CANCEL;
+/** What a scan offers: the items it was given — positions in play, a menu's steps in a menu — and «cancel» in front. */
+export type ScanItem<T extends string = Action> = T | typeof SCAN_CANCEL;
 export interface SwitchScanOptions {
     /** How long each item is offered. 1 s is the gaze cycle's step, which the Dev ran for a day (ADR-0213). */
     readonly stepMs?: number;
@@ -13,30 +14,46 @@ export declare const SWITCH_SCAN_DEFAULTS: {
     readonly stepMs: 1000;
     readonly pulseMs: 400;
 };
+/**
+ * THE ENGINE'S OWN DOORS, and whether each has something behind it (ADR-0218 §3). A door with nothing behind it is not offered:
+ * a cycle never stops on a position that does nothing (ADR-0155).
+ */
+export interface ScanDoors {
+    /** The card SELECT opens is mounted. */
+    readonly menus: boolean;
+    /** The quick pause START opens has its bar — the menu the scan steps there, and «back» is how it is left. */
+    readonly quickPause: boolean;
+}
+/**
+ * What the scan offers IN PLAY after «cancel»: the game's named positions, then the doors in the order ADR-0218 §3 names them —
+ * the menus (SELECT), then the quick pause (START). Taking a door presses it on the virtual controller, which hands it to the
+ * engine as its keys are.
+ */
+export declare function playScanList(game: readonly Action[], doors: ScanDoors): readonly Action[];
 export interface ScanFrame {
     /** Her switch went down on this frame. Whatever sends it — a key, a touch, a gesture, a word. */
     readonly press?: boolean;
 }
-export interface ScanOutput {
-    /** The action being pressed, for `pulseMs` after it was taken. */
-    readonly pressed: Action | null;
-    /** The action taken on THIS frame — what a caller turns into a press. */
-    readonly commanded: Action | null;
+export interface ScanOutput<T extends string = Action> {
+    /** The item being pressed, for `pulseMs` after it was taken. */
+    readonly pressed: T | null;
+    /** The item taken on THIS frame — what a caller turns into a press. */
+    readonly commanded: T | null;
     /** What is being offered right now, and where it sits in the list. Never `null`: something is always showing. */
     readonly showing: {
-        readonly item: ScanItem;
+        readonly item: ScanItem<T>;
         readonly index: number;
     };
 }
-export interface SwitchScan {
-    (nowMs: number, frame?: ScanFrame): ScanOutput;
+export interface SwitchScan<T extends string = Action> {
+    (nowMs: number, frame?: ScanFrame): ScanOutput<T>;
 }
 /**
- * The scanner. `actions` is what THIS game offers — its declared positions and the engine's own doors — and `cancel` is put in
- * front of them.
+ * The scanner. `actions` is what is offered now — in play this game's declared positions and the engine's own doors, in a menu
+ * that menu's steps — and `cancel` is put in front of them.
  *
  * ⚠️ An empty list is not an error: a game that declared nothing leaves a scan of one item, `cancel`, and a press takes nothing.
  * The alternative — offering the whole controller to a game that reads none of it — is the dead button ADR-0106 §5 refuses, and
  * here it would cost a child a full pass of fourteen items to reach the one thing that works.
  */
-export declare function createSwitchScan(actions: readonly Action[], options?: SwitchScanOptions): SwitchScan;
+export declare function createSwitchScan<T extends string = Action>(actions: readonly T[], options?: SwitchScanOptions): SwitchScan<T>;

package/dist-pkg/input/switch-scan.js

@@ -19,8 +19,21 @@
 export const SCAN_CANCEL = 'cancel';
 export const SWITCH_SCAN_DEFAULTS = { stepMs: 1000, pulseMs: 400 };
 /**
- * The scanner. `actions` is what THIS game offers — its declared positions and the engine's own doors — and `cancel` is put in
- * front of them.
+ * What the scan offers IN PLAY after «cancel»: the game's named positions, then the doors in the order ADR-0218 §3 names them —
+ * the menus (SELECT), then the quick pause (START). Taking a door presses it on the virtual controller, which hands it to the
+ * engine as its keys are.
+ */
+export function playScanList(game, doors) {
+    const list = [...game];
+    if (doors.menus)
+        list.push('select');
+    if (doors.quickPause)
+        list.push('start');
+    return list;
+}
+/**
+ * The scanner. `actions` is what is offered now — in play this game's declared positions and the engine's own doors, in a menu
+ * that menu's steps — and `cancel` is put in front of them.
  *
  * ⚠️ An empty list is not an error: a game that declared nothing leaves a scan of one item, `cancel`, and a press takes nothing.
  * The alternative — offering the whole controller to a game that reads none of it — is the dead button ADR-0106 §5 refuses, and

package/dist-pkg/input/touch-bindings.d.ts

@@ -5,9 +5,6 @@ import type { PlayerView } from '../core/entity.js';
 import type { DomQuery } from '../core/dom-query.js';
 import type { KeyScheme } from '../core/entity.js';
 import { type Action } from '../core/actions.js';
-export type { DomQuery } from '../core/dom-query.js';
-/** action -> list of physical codes. */
-export type { KeyScheme } from '../core/entity.js';
 /** The six input edges touch raises on the player (consumed and cleared by the game's physics). */
 export type EdgeFlag = 'jumpEdge' | 'runEdge' | 'leftEdge' | 'rightEdge' | 'swapEdge' | 'specialEdge';
 /** An edge to raise: which player (POSITION in the array) and which flag. */
@@ -29,8 +26,6 @@ export interface TouchBindSnapshot {
     /** `input/state.ts`'s `keys`: the keys held NOW (every transport's, mixed). */
     heldKeys: ReadonlySet<string>;
 }
-/** Re-exported: the definition lives in `input/pointer-space`, with the arithmetic that uses it (issue #105). */
-export type { RectLike } from './pointer-space.js';
 /** The d-pad's four physical directions, on or off. */
 export interface DirSet {
     left: boolean;
@@ -188,7 +183,9 @@ export interface TouchBindingsCtx {
      *
      * 🔴 REQUIRED, and it is where the device switch becomes VISIBLE: touch is the transport the child uses beside the
      * keyboard, and without this line the automaton answers `teclado` even with the finger on the screen — so the latch
-     * read would be the keyboard's, on the wrong device.
+     * read would be the keyboard's, on the wrong device. 📌 In the root the press has already recorded this edge and resolved
+     * touch's latch at the virtual controller's `pressedBy` (ADR-0109 rule 3); a host without that door passes the latched edge
+     * of `input/latch-edge` here.
      */
     playerEdge: (player: number, source: TransportName) => void;
     /**

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

@@ -1,8 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import type { Translate } from '../core/i18n.js';
 import type { DomQuery } from '../core/dom-query.js';
-/** Minimal DOM-selector shape (matches ui/dom.ts's `$`). */
-export type { DomQuery } from '../core/dom-query.js';
 /** Minimal platform/storage.ts shape this module needs. */
 export interface TouchStore {
     get(key: string, fallback?: string | null): string | null;
@@ -78,6 +76,22 @@ export interface TouchCtx {
      * root never handed in, which is what took down every boot in a fake document once this was wired to `createGame`.
      */
     win: Pick<Window, 'addEventListener'> | null;
+    /**
+     * Draws ONE slot's choice by its size (ADR-0130 rule 3): five named positions or fewer are a cycle row, more a dropdown.
+     * Injected because the drawing lives in `ui/panel-widgets.mountChoice` and this module is a layer below it (ADR-0173);
+     * `createGame` hands it in. ABSENT, each slot stays a hand-built `<select>`, whatever its size — a host that builds its
+     * own touch panel keeps the control it always had.
+     */
+    drawChoice?: (spec: TouchSlotChoice, pick: (action: string) => void) => HTMLElement;
+}
+/** What a slot's choice is drawn from: the slot's name, the game's positions in its words, and the one it carries now. */
+export interface TouchSlotChoice {
+    readonly label: string;
+    readonly values: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    readonly current: string;
 }
 export declare const IPHONE16_LONG_MM = 141.1;
 export declare const IPHONE16_LONG_PX = 852;
@@ -194,6 +208,7 @@ export interface TouchMarkupSpec {
     /** The d-pad's drawing: `cruz` (cross) or `analogico` (stick). It comes from the pad's persisted setting (`padDir`). */
     readonly dpad?: 'cruz' | 'analogico';
 }
+export declare function buttonName(t: Translate, slotAction: string): string | null;
 /**
  * Builds (or reuses) `#touch-controls` and returns it.
  *

package/dist-pkg/input/touch.js

@@ -107,10 +107,31 @@ export function initTouch(ctx) {
     let padDir = ctx.store.get(KEYS.padDir, 'stick') || 'stick';
     let _stickTravelPx = 42, _stickDeadPx = 12; // boot values; applyPadPhysical() sets the real ones
     const touchMap = normalizeTouchMap(ctx.store.getJSON(KEYS.touchmap, null));
+    /** A slot's choice landed: store it, and say it in the game's word — never the abstract name. */
+    function slotChosen(slot, slotLabel, action) {
+        touchMap[slot] = action;
+        ctx.store.setJSON(KEYS.touchmap, touchMap);
+        // ⚠️ The spoken word is the SAME as the one read: it comes from the list that just built the control, so nothing has
+        // to make two tables agree.
+        const chosen = ctx.gameActions().find((x) => x.action === action);
+        const slotName = slotLabel || t('touch.slot.fallback');
+        // ⚠️ WITHOUT THE GAME'S WORD, THE ANNOUNCEMENT DROPS THE POSITION — IT DOES NOT FALL BACK TO THE ID. `action` is the
+        // ABSTRACT name (`action3`), and ADR-0074 says it never reaches a person; `7742ac0` already paid for this defect on the
+        // remapping screen and the way out is the same: a key of its own that says what matters.
+        // 📌 The fallback is reachable because `gameActions()` is a FUNCTION of the cartridge, reread on every choice: in an
+        // activity hub the list changes underneath and the control drawn before is orphaned.
+        ctx.srSay(chosen
+            ? t('sr.touch.slotSet', { slot: slotName, acao: chosen.label })
+            : t('sr.touch.slotSetUnnamed', { slot: slotName }));
+    }
     function renderTouchMap() {
         const el = ctx.$('#touchmap-list');
         if (!el)
             return;
+        if (ctx.drawChoice) {
+            drawSlotChoices(el, ctx.drawChoice);
+            return;
+        }
         el.innerHTML = TOUCH_SLOTS.map((s) => `<div class="ctrl-row"><label for="tm-${s.k}">${t(s.lbl)}</label><select id="tm-${s.k}" class="vol" data-slot="${s.k}">` +
             // ⚠️ THE OPTION IS BORN EMPTY and the `label` goes in just below through `textContent` (issue #106). It is the
             // game's WORD — `gameActions()` comes from the preset —, and a game lives in another repository (ADR-0083), so
@@ -127,25 +148,41 @@ export function initTouch(ctx) {
         }
         el.querySelectorAll('select[data-slot]').forEach((sel) => {
             sel.addEventListener('change', () => {
-                const slot = sel.dataset.slot || '';
-                touchMap[slot] = sel.value;
-                ctx.store.setJSON(KEYS.touchmap, touchMap);
                 const label = sel.previousElementSibling ? sel.previousElementSibling.textContent : null;
-                // ⚠️ The spoken word is the SAME as the one read: it comes from the list that just built the `<option>`, so
-                // nothing has to make two tables agree.
-                const chosen = ctx.gameActions().find((x) => x.action === sel.value);
-                const slotName = label || t('touch.slot.fallback');
-                // ⚠️ WITHOUT THE GAME'S WORD, THE ANNOUNCEMENT DROPS THE POSITION — IT DOES NOT FALL BACK TO THE ID. `sel.value`
-                // is the ABSTRACT name (`action3`), and ADR-0074 says it never reaches a person; `7742ac0` already paid for
-                // this defect on the remapping screen and the way out is the same: a key of its own that says what matters.
-                // 📌 The fallback is reachable because `gameActions()` is a FUNCTION of the cartridge, reread on every
-                // `change`: in an activity hub the list changes underneath and the `<option>` drawn before is orphaned.
-                ctx.srSay(chosen
-                    ? t('sr.touch.slotSet', { slot: slotName, acao: chosen.label })
-                    : t('sr.touch.slotSetUnnamed', { slot: slotName }));
+                slotChosen(sel.dataset.slot || '', label, sel.value);
             });
         });
     }
+    /**
+     * THE SLOTS DRAWN BY THEIR SIZE (ADR-0130 rule 3), node by node: each slot is a choice among the game's named positions,
+     * so a game naming five or fewer gets cycle rows «◀ Botão 0: Confirmar ▶», and one naming more gets dropdowns. The id
+     * (`#tm-<slot>`) and `data-slot` stay on the control in both shapes — they are how the root finds the slots it hides.
+     */
+    function drawSlotChoices(el, draw) {
+        while (el.firstChild)
+            el.removeChild(el.firstChild);
+        const doc = el.ownerDocument;
+        const positions = ctx.gameActions().map(({ action, label }) => ({ value: action, label }));
+        for (const s of TOUCH_SLOTS) {
+            const slotName = t(s.lbl);
+            const control = draw({ label: slotName, values: positions, current: touchMap[s.k] ?? '' }, (action) => slotChosen(s.k, slotName, action));
+            control.id = `tm-${s.k}`;
+            control.dataset.slot = s.k;
+            const row = doc.createElement('div');
+            row.className = 'ctrl-row';
+            if (control.tagName === 'SELECT') {
+                // a dropdown keeps its name beside it; a cycle row already carries it in its own text
+                const name = doc.createElement('label');
+                name.htmlFor = control.id;
+                name.textContent = slotName;
+                row.appendChild(name);
+            }
+            else
+                row.classList.add('ctrl-row--passos');
+            row.appendChild(control);
+            el.appendChild(row);
+        }
+    }
     function openTouchCfg() {
         const ov = ctx.$('#touchcfg');
         if (!ov)
@@ -310,14 +347,15 @@ export function initTouch(ctx) {
 }
 /**
  * A BUTTON'S NAME, from the position it fires (ADR-0165): the same in every game — 1 to 4, L1/L2/R1/R2, SELECT, START,
- * and the four directions by their spoken name. The cartridge's word is the FUNCTION, and it never reaches the face.
+ * and the four directions by their spoken name. The cartridge's word is the FUNCTION, and it never reaches the face. The pad
+ * wizard asks by these names where the game names no position (`input/pad-wizard`, ADR-0144 erratum of 2026-09-26).
  */
 const SLOT_NAME = {
     action1: '1', action2: '2', action3: '3', action4: '4',
     leftShoulder: 'L1', leftTrigger: 'L2', rightShoulder: 'R1', rightTrigger: 'R2',
     select: 'SELECT', start: 'START',
 };
-function buttonName(t, slotAction) {
+export function buttonName(t, slotAction) {
     if (SLOT_NAME[slotAction])
         return SLOT_NAME[slotAction];
     return slotAction === 'up' || slotAction === 'down' || slotAction === 'left' || slotAction === 'right' ? t(`touch.nome.${slotAction}`) : null;

package/dist-pkg/input/transport-in-use.d.ts

@@ -32,9 +32,9 @@ export declare function isTransportName(v: unknown): v is TransportName;
  * THE FOUR THAT REQUIRE EXPLICIT ENABLING and, once enabled, rule over all the others (rule 4).
  *
  * ⚠️ It is the same list as `ONE_COMMAND_AT_A_TIME` in `input/latch-scope`, and the match is no accident: these
- * are the transports of whoever CANNOT HOLD ANYTHING. What ADR-0109 adds is that they do not turn latching on
- * only for themselves — they turn it on for the rest, because whoever uses the webcam may also touch the screen,
- * and a latch that turns off when the device changes is a trap for exactly that person.
+ * are the transports that send one command at a time. What ADR-0109 added — that enabling them turns latching on
+ * for the rest — is the model of `latchNow`, which ADR-0113 superseded; since ADR-0249 their own latch starts as
+ * the game's `holdsKeys()` and the child may change it.
  */
 export declare const NEED_ENABLING: ReadonlySet<TransportName>;
 /** The transport that turns latching on by itself, with no priority involved (rule 2). */
@@ -78,8 +78,8 @@ export declare const DEFAULT_INPUT_STATE: InputState;
  * `latch-scope.latchOf` returns `true`, because it reads what they saved.
  *
  * ⚠️ AND THE TOUCH CLAUSE FELL TOO: under ADR-0113 touch is a transport like the others — its value is a choice
- * and is stored. Only eyes, face, gestures and speech may refuse to turn OFF, and that half lives in
- * `latch-scope.latchAlwaysOn`, with a different set from this one and answering a different question.
+ * and is stored. Eyes, face, gestures and speech differ only in where their DEFAULT comes from — the game's
+ * `holdsKeys()` (ADR-0249, `latch-scope.latchDefaultFromGame`) — and their value is a choice too.
  *
  * **The right answer is `latch-scope.latchOf(inputState.inUse, reading)`.** The role left to this module is
  * what its name says: WHICH transport is in use — which is what feeds that first argument.

package/dist-pkg/input/transport-in-use.js

@@ -53,9 +53,9 @@ export function isTransportName(v) {
  * THE FOUR THAT REQUIRE EXPLICIT ENABLING and, once enabled, rule over all the others (rule 4).
  *
  * ⚠️ It is the same list as `ONE_COMMAND_AT_A_TIME` in `input/latch-scope`, and the match is no accident: these
- * are the transports of whoever CANNOT HOLD ANYTHING. What ADR-0109 adds is that they do not turn latching on
- * only for themselves — they turn it on for the rest, because whoever uses the webcam may also touch the screen,
- * and a latch that turns off when the device changes is a trap for exactly that person.
+ * are the transports that send one command at a time. What ADR-0109 added — that enabling them turns latching on
+ * for the rest — is the model of `latchNow`, which ADR-0113 superseded; since ADR-0249 their own latch starts as
+ * the game's `holdsKeys()` and the child may change it.
  */
 export const NEED_ENABLING = new Set(['olhos', 'rosto', 'gestos', 'fala']);
 /** The transport that turns latching on by itself, with no priority involved (rule 2). */
@@ -89,8 +89,8 @@ export const DEFAULT_INPUT_STATE = Object.freeze({ inUse: 'teclado', assistedOn:
  * `latch-scope.latchOf` returns `true`, because it reads what they saved.
  *
  * ⚠️ AND THE TOUCH CLAUSE FELL TOO: under ADR-0113 touch is a transport like the others — its value is a choice
- * and is stored. Only eyes, face, gestures and speech may refuse to turn OFF, and that half lives in
- * `latch-scope.latchAlwaysOn`, with a different set from this one and answering a different question.
+ * and is stored. Eyes, face, gestures and speech differ only in where their DEFAULT comes from — the game's
+ * `holdsKeys()` (ADR-0249, `latch-scope.latchDefaultFromGame`) — and their value is a choice too.
  *
  * **The right answer is `latch-scope.latchOf(inputState.inUse, reading)`.** The role left to this module is
  * what its name says: WHICH transport is in use — which is what feeds that first argument.

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

@@ -81,15 +81,6 @@ export interface Transport {
 }
 /** Does this transport carry this set of actions? Arithmetic, as ADR-0079 §3 describes it. */
 export declare function carries(t: Transport, actions: readonly Action[]): boolean;
-/**
- * Does this transport HOLD as many as the game asks at once? (ADR-0104 §A.)
- *
- * ⚠️ A TRANSPORT WITH NO DECLARED CEILING ANSWERS YES, and the choice is deliberate: an absent `holds` means "we did
- * not measure this", and refusing for lack of a measure would turn ignorance into an accusation — keyboard and pad
- * would fail every game for having no number at all. Where there is no decision, the model stays silent; touch is
- * the one with a decision, and it alone can fail here.
- */
-export declare function holds(t: Transport, asked: number): boolean;
 /**
  * The AVAILABLE transports that carry this set.
  *

package/dist-pkg/input/transports.js

@@ -91,7 +91,7 @@ export function carries(t, actions) {
  * would fail every game for having no number at all. Where there is no decision, the model stays silent; touch is
  * the one with a decision, and it alone can fail here.
  */
-export function holds(t, asked) {
+function holds(t, asked) {
     return t.holds === undefined || t.holds >= asked;
 }
 /**

package/dist-pkg/input/virtual-controller.d.ts

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import type { Action } from '../core/actions.js';
+import { type Action } from '../core/actions.js';
 import type { KeyScheme } from '../core/entity.js';
 import type { TransportName } from './transport-in-use.js';
 export interface VirtualCommand {
@@ -30,17 +30,53 @@ export interface VirtualControllerDeps {
      */
     readonly menuKey: (code: string, source: TransportName | undefined) => void;
     readonly deliver: (command: VirtualCommand) => void;
+    /**
+     * A position the ENGINE answers itself while a menu is open, before it becomes a menu key: the sonar reads the menu in
+     * front (ADR-0234, `ui/screen-text.menuSonarPress`). Answers whether it took the press. Absent: every position is a key.
+     */
+    readonly menuAnswers?: (action: Action, player: number) => boolean;
+    /**
+     * A SYSTEM position pressed, in play or with a menu open: the engine answers it for that seat as its keys do — `start` the
+     * quick pause (again: leaves it), `select` the menus (ADR-0144 §1 and its erratum of 2026-09-26, ADR-0155). Absent: it does
+     * nothing.
+     *
+     * ⚠️ The keyboard does not come here: its key is already in the world, and the engine's own key listeners answer it even for
+     * a cartridge with no `onCommand` — the host's keyboard conductor does not press these two, or one key would pause twice.
+     */
+    readonly systemPress?: (action: Action, player: number) => void;
+    /**
+     * ONE BUTTON ONLY (ADR-0218 §4): asked FIRST, for every press from every transport that presses here — the eyes, the face,
+     * the hands, the voice, the on-screen pad, the gamepad. `true` means one-button scanning took the press as «take the one
+     * shown»: the position reaches nothing else — not play, not a menu, not the engine — and no release is owed for it. A press
+     * that lands on the scan's «cancel» is taken too, and means nothing. Absent: every press is itself.
+     */
+    readonly takeShown?: (source: TransportName | undefined) => boolean;
+    /**
+     * A PRESS FROM A NAMED TRANSPORT, told FIRST — before one button only, a menu or play decides where it goes. This is the one
+     * place every position-pressing transport shares, so it is where «the child is using this device» can be heard for all of
+     * them (ADR-0109 rule 3), and where the root records that device's edge and resolves its latch before the press reaches the
+     * game (ADR-0113, ADR-0249). Not told for a press with no source: a key nobody stamped is nobody's edge — the real keyboard
+     * arrives here as `teclado`, read off the event by `input/synthetic-source.sourceOfEvent`. Absent: nothing is told.
+     */
+    readonly pressedBy?: (source: TransportName, player: number) => void;
 }
 export interface VirtualController {
     /**
-     * Presses a position. Answers whether it reached PLAY — `false` means a menu took it.
+     * Presses a position. Answers whether it reached PLAY — `false` means a menu took it, or it was held back (`toPlay`).
      *
      * 🔴 THE ANSWER EXISTS BECAUSE EVERY TRANSPORT NEEDS IT AND EACH WAS GUESSING IT (ADR-0223). The touch pad asked its own
      * `emMenu()` before deciding what to do, which is the same question this function has just answered — and two answers to
      * one question is how the two doors came to disagree about what happens with a menu open. A transport that raises an edge,
      * or hides its tips, or announces something, does it only when the press reached the game; now it is told.
+     *
+     * `toPlay` false: in play the press belongs to something else — the keyboard knows what has the focus, a field being typed
+     * into or the engine's own control being pressed (`input/key-default`) — so it reaches nobody: nothing held, nothing delivered.
+     * With a menu open it is the menu's all the same, as every press is (ADR-0111 erratum of 2026-09-26: one press, one action).
+     *
+     * A system position (`start`, `select`) never reaches play and never becomes a menu key: it is the engine's (ADR-0144 §4), and
+     * it goes to `systemPress` — unless, in play, `toPlay` is false, when the press belongs to something else and reaches nobody.
      */
-    press(action: Action, source: TransportName | undefined, player?: number): boolean;
+    press(action: Action, source: TransportName | undefined, player?: number, toPlay?: boolean): boolean;
     release(action: Action, source: TransportName | undefined, player?: number): void;
 }
 export declare function createVirtualController(d: VirtualControllerDeps): VirtualController;

package/dist-pkg/input/virtual-controller.js

@@ -4,22 +4,50 @@
 // The Dev: «a engine lida com o hardware e passa para o jogo o nome virtual do botão, o jogo por sua vez devolve o nome do que é executado
 // ao apertar cada botão… a engine leva o evento para o jogo». A transport that reads positions (the eyes, and later the face and the
 // hands) presses and releases a position here, with its source; this decides what that reaches:
-// · with a menu open, the position is the menu's key — the way the touch pad already moves menus (ADR-0157), since menus read keys;
+// · with a menu open, the position is the menu's key — the way the touch pad already moves menus (ADR-0157), since menus read keys —
+//   unless the engine answers it there itself (`menuAnswers`: the sonar reads the menu, ADR-0234);
 // · in play, the child's key for that position is held (games that ask what is held keep answering), and the command is delivered to the
 //   cartridge: the position, pressed or released, the source, the seat. The cartridge's map (its `preset`) says what it executes.
 // A position the child's scheme gives no key is still delivered: the map belongs to the game, not to the keyboard.
+// 🔴 EXCEPT THE TWO SYSTEM POSITIONS, which never reach play (ADR-0144 §4, ADR-0155 §4): `start` is the quick pause and `select`
+// opens the menus, a cartridge may not declare either, so the game has no word for them and nothing to do with them. 📏 Before
+// this, Enter in play opened the quick pause AND the quiz's `onCommand` heard `start`; F opened the card AND it heard `select`.
+// They go to the ENGINE instead (`systemPress`), so START and SELECT open the pause «from any transport» (ADR-0144 §1): the eyes,
+// the face, the hands, the voice and the scan press here and have no key in the world for the engine to hear.
+// 🔴 AND WITH A MENU OPEN TOO, never as a key (ADR-0144 erratum of 2026-09-26). The first key of `start` is whatever the child put
+// first: with `start` remapped to `Enter`, a camera's START on the quick pause's bar was the bar's «confirm» and not the way out.
+// The engine answers the POSITION the same way its key listeners do — START again leaves the quick pause, SELECT goes on to the
+// card, and an open card or panel refuses both.
+// 🔴 AND WITH ONE BUTTON ONLY ON, NONE OF THE ABOVE (ADR-0218 §4): every press here is the child's one switch, and it takes the
+// item the scan shows (`takeShown`, asked before anything else). This is the one place every position-pressing transport shares.
+import { SYSTEM } from '../core/actions.js';
+/** The positions that are the engine's and never the game's (`core/actions.SYSTEM`). */
+const ENGINE_POSITIONS = new Set(SYSTEM);
 export function createVirtualController(d) {
     // `${player}:${action}` → the key held for a press the game received (or null when the scheme has none), so the release lets go of the
     // same key, and only a press the game heard is released to it
     const held = new Map();
     return {
-        press(action, source, player = 0) {
+        press(action, source, player = 0, toPlay = true) {
+            if (source)
+                d.pressedBy?.(source, player);
+            if (d.takeShown?.(source))
+                return false; // one button only: whatever was pressed, it was the switch (ADR-0218 §4)
+            const menu = d.menuOpen();
+            // the POSITION, not its first key: a key means what the child bound to it, and `Enter` on a menu is «confirm»
+            if (ENGINE_POSITIONS.has(action)) {
+                if (menu || toPlay)
+                    d.systemPress?.(action, player);
+                return false;
+            }
             const code = d.scheme(player)[action]?.[0];
-            if (d.menuOpen()) {
-                if (code)
+            if (menu) {
+                if (!d.menuAnswers?.(action, player) && code)
                     d.menuKey(code, source);
                 return false;
             }
+            if (!toPlay)
+                return false;
             if (code)
                 d.holdKey(code, source);
             held.set(`${player}:${action}`, code ?? null);

package/dist-pkg/input/voice-map.d.ts

@@ -5,7 +5,7 @@ import type { Action } from '../core/actions.js';
  *
  * ⚠️ WRITTEN AS THE RECOGNISER'S VOCABULARY SPELLS THEM — lowercase, with their accents (the Dev's words are «ação» and
  * «Acción»): a grammar word the model does not know is dropped and its position goes mute (measured below). Comparing ignores
- * accents, because a heard sentence and a table entry both pass through `wordsOf` before they meet.
+ * accents: the reader (`platform/speech-recognition`) matches a heard sentence and a table entry by a key without them.
  */
 export type VoiceWords = {
     readonly [A in Action]?: readonly string[];
@@ -19,25 +19,41 @@ export declare function voiceWordsFor(language: string): VoiceWords;
  * says something that is not a command: the lab measured free speech being pushed to the nearest word («configurações de
  * inclusão» → «quatro»). That is the cost of the closed list and the reason the words are short and unlike each other.
  * ⚠️ `extra` is what the MENU is showing right now (ADR-0194): saying the name of an item activates it, so those words join the
- * grammar while that menu is open and leave with it.
+ * grammar while that menu is open and leave with it — AS THE LANGUAGE WRITES THEM (§1, «as shown»), accents kept: stripped,
+ * «configurações» is not in the model's vocabulary and the name goes mute, the same defect «acao» was.
  */
 export declare function voiceGrammar(language: string, extra?: readonly string[]): readonly string[];
+/** What a heard phrase asks for: a position of the controller, or the item of the open menu that has this name (ADR-0194). */
+export type VoiceCommand = {
+    readonly kind: 'position';
+    readonly action: Action;
+}
+/** `name` is the item's name exactly as it was handed to `items` — the name on screen, to find the item by. */
+ | {
+    readonly kind: 'item';
+    readonly name: string;
+};
 export interface VoiceCommands {
     /**
-     * What the recogniser has heard SO FAR in this utterance, and the position it presses — or `null` when nothing new was said.
+     * The names the open menu is showing, as shown (ADR-0194 §2): from now on, saying one is a command — until the next call.
+     * An empty list is a menu closed.
+     */
+    items(names: readonly string[]): void;
+    /**
+     * What the recogniser has heard SO FAR in this utterance → the commands it completes that were not answered before.
      * ⚠️ It answers on the PARTIAL and not at the end of the sentence (ADR-0193 erratum, the Dev's choice after running both):
-     * 0.25–0.45 s against 1.3–1.4 s, which is the difference between a command and a delay a child gives up on.
+     * 0.25–0.45 s against 1.3–1.4 s, which is the difference between a command and a delay a child gives up on — except for a
+     * name another item's name continues, which waits for `final` (ADR-0194 §3).
      */
-    partial(text: string): Action | null;
-    /** The utterance ended (or the microphone was let go): the next partial starts a new sentence. */
-    reset(): void;
+    partial(text: string): readonly VoiceCommand[];
+    /** The utterance ended with this text: what it completes that the partials held back. The next partial starts afresh. */
+    final(text: string): readonly VoiceCommand[];
 }
 /**
- * The rule that turns a growing partial into presses.
+ * The Dev's words and the open menu's names, READ BY `platform/speech-recognition.createCommandReader` — the one reader of what
+ * was heard (ADR-0194 §2–§3); this adds only what a word MEANS here, the position it presses.
  *
  * 🎯 A PARTIAL GROWS, AND ONLY WHAT IS NEW FIRES. «acima» then «acima abaixo» is a child who said two words, and the second
- * press must be `down`, not `up` all over again — so the words already answered for are counted, never re-read.
- * 📌 The tail is matched LONGEST FIRST because a position may answer to a phrase: «pick up» is one command in English, and
- * reading only the last word would make it `null` after having fired nothing.
+ * press must be `down`, not `up` all over again — the reader counts what it already answered for in each utterance.
  */
 export declare function createVoiceCommands(language: string): VoiceCommands;