@the-inclusionist/engine 10.0.0 → 11.0.0

package/dist-pkg/ui/pause-icons.d.ts

@@ -25,7 +25,7 @@ export declare function inputModeOf(s: {
     readonly toggleMove?: boolean;
     readonly switchScan?: boolean;
 }): InputMode;
-export declare function nextInputMode(m: InputMode, holdsKeys: boolean, latchRequired?: boolean): InputMode;
+export declare function nextInputMode(m: InputMode, holdsKeys: boolean): InputMode;
 import type { Store } from '../platform/storage.js';
 /**
  * Hover and focus on a bar's icons write its NAME in the bar's `.pause-icons-cap` and ask for its EXPLANATION.
@@ -88,15 +88,6 @@ export interface IconStateSnapshot {
     locale?: string;
     /** False disables the blind/TTS icons: those need an audio output nobody else is listening to. */
     privateOutput: boolean;
-    /**
-     * Does the device in use REQUIRE the latch? (ADR-0113 clause 3.) With the eyes, the face, gestures and speech the latch
-     * is what makes the input work, so there is no choice to offer: the ☝️ cycle then skips `standard` (see
-     * `inputModeOrder`).
-     *
-     * OPTIONAL because adding a required member to a published snapshot is a breaking change (the shape gate,
-     * `tests/public-surface-shrinks-by-declaration`, fails on it). Absent means «nobody told me», which degrades to «not required».
-     */
-    latchRequired?: boolean;
     /** No voice speaks the current language (ADR-0185): the narration icon is locked. Absent reads as a voice. */
     noVoice?: boolean;
 }
@@ -136,8 +127,8 @@ export interface ActionableIcons {
      * DOES THIS GAME HOLD ANY KEY? — `GameDeclaration.holdsKeys`, the field of ADR-0115.
      *
      * The latch exists for whoever cannot keep a key pressed; in a game where nothing is held it has nothing to hold, and a
-     * control that does nothing teaches a child that the setting she depends on is broken. (A different absence from
-     * ADR-0113 clause 3's, where the device REQUIRES the latch: see `latchRequired`.)
+     * control that does nothing teaches a child that the setting she depends on is broken. On eyes, face, gestures and
+     * speech it is also the latch's default (ADR-0249) — read by the root at every command, not here.
      *
      * A FUNCTION, not a value (as in ADR-0084): an answer read once goes stale silently, and with one `createGame` serving
      * several cartridges (ADR-0142) the icon would describe the game that booted first.
@@ -188,6 +179,11 @@ export declare function rootThatActs(rootEl: readonly PauseMenuButton[], options
  * counted in «N de M» (a locked one is not hidden — it is reached, and says why).
  */
 export declare const PM_VISIBLE_ITEMS = ".pause-menu:not([hidden]) .pm-btn:not([hidden])";
+/**
+ * The other direction of the same table: the item of the root that opens each list. It is where «back» puts the cursor
+ * (ADR-0130 rule 1), and the name a list is announced by (`ui/where-the-child-is`). The root has no door.
+ */
+export declare const LIST_DOOR: Readonly<Record<PauseSub, string | null>>;
 /**
  * Switches the visible list of ONE pause card, and puts the cursor on the FIRST item of the list that came in.
  *
@@ -195,6 +191,23 @@ export declare const PM_VISIBLE_ITEMS = ".pause-menu:not([hidden]) .pm-btn:not([
  * access to the button tables. Every list already exists in the markup, so the switch is DOM only.
  */
 export declare function showPauseOptions(sp: HTMLElement, sub: PauseSub): HTMLElement | null;
+/**
+ * PUTS THE CARD'S CURSOR ON `el` — the one place every move of it goes through, whatever moved it: the arrows and the pad
+ * (`ui/menu-nav`), a finger, a held press, a door between lists, «back». The card selects by class, not by browser focus,
+ * so nothing scrolls it by itself: an item past the visible part of a long list would be marked where the child cannot see
+ * it. So the list is scrolled HERE, inside the card, until the item is wholly in view (issue #134, `keepInView`).
+ */
+export declare function markPauseItem(sp: HTMLElement, el: HTMLElement | null | undefined): void;
+/**
+ * «BACK» FROM A LIST OF THE CARD: the root comes in with the cursor on THE ITEM THAT OPENED the list being left, not on
+ * the root's first item (ADR-0130 rule 1). A child who went into «Opções», looked, and came back is where she was; landing
+ * on «Voltar» would send her walking the root again to find her place, and a child who cannot see the mark would not even
+ * know she had been moved.
+ *
+ * Opening the card is another question and keeps `showPauseOptions(sp, 'raiz')`: a card opens on item 1 (ADR-0158).
+ * A door that is gone or hidden leaves the cursor on the first item, which is all there is to return to.
+ */
+export declare function backToRoot(sp: HTMLElement): HTMLElement | null;
 /**
  * WHAT AN INTENT MEANS INSIDE THE `accessibility` MODE (ADR-0044 item 7).
  *
@@ -230,7 +243,7 @@ export interface PauseIconsCtx {
     getPlayers: () => readonly unknown[];
     /** aria-live "polite" — every successful toggle announces its NEW state. */
     srSay: (text: string) => void;
-    /** aria-live "assertive" — the refusals (a shared audio output, a device that always latches). */
+    /** aria-live "assertive" — the refusals (a shared audio output, no voice for the language). */
     srAlert: (text: string) => void;
     /**
      * Called after EVERY exit from the bar mode, with the screen and whether it was silent. Absent, nothing happens. It lets
@@ -277,7 +290,10 @@ export interface PauseIconsCtx {
     setCatGain: (k: string) => void;
     /** Repaints the TTS row of the auditory panel after the icon changes it. */
     reflectTtsPanel: () => void;
-    /** Whether the TTS icon also calls `reflectTtsPanel`. `createGame` passes `true`; `false` leaves the panel as it was. */
+    /**
+     * Whether the TTS icon also calls `reflectTtsPanel`. `createGame` passes `false`: it repaints the panel from the mixer's
+     * `onCatChange`, which hears this icon's write like any other (ADR-0247). A host without that listener passes `true`.
+     */
     reflectTtsPanelEnabled: boolean;
     isLibrasOn: () => boolean;
     toggleLibras: () => void;

package/dist-pkg/ui/pause-icons.js

@@ -43,6 +43,7 @@ import { quickBarMarkup, screenPauseMarkup, } from './pause-markup.js';
 import { PAUSE_ICONS, pauseIcon } from '../core/pause-icon-catalogue.js';
 import { nextTheme, nextCorrection, hasHighContrast, DEFAULT_VISUAL, } from '../render/viz-axes.js';
 import { announceItem } from './item-announcement.js';
+import { keepInView } from './menu-items.js';
 import { accessibleLabel } from '../core/accessible-label.js';
 import { stepInRing } from '../core/ring.js'; // from the LEAF, not from ui/menu-nav: see the note there
 // A LIVE BINDING (ESM): the index can be turned off in the menu, and the value here follows without a subscription.
@@ -64,22 +65,18 @@ export function inputModeOf(s) {
     return s.switchScan ? 'scan' : s.toggleMove ? 'sticky' : 'standard';
 }
 /**
- * The next position. Two things take one away, and neither is an error to report — a cycle simply never stops where nothing
- * would happen (ADR-0155), and a word that promised what this game cannot do would teach a child that her setting is broken
- * (ADR-0106 §5):
+ * The next position. A GAME THAT HOLDS NO KEY has nothing for the latch to hold, so the icon offers standard and one button:
+ * a cycle never stops where nothing would happen (ADR-0155), and a word that promised what this game cannot do would teach a
+ * child that her setting is broken (ADR-0106 §5).
  *
- * · A GAME THAT HOLDS NO KEY has nothing for the latch to hold, so the icon offers standard and one button.
- * · A DEVICE THAT SENDS ONE COMMAND AT A TIME always latches and cannot be asked not to (ADR-0113 clause 3, ADR-0211), so
- *   `standard` is unreachable there. 🔴 That used to grey the whole icon out, and with three positions that would have cost a
- *   child playing with her eyes the one-button scan as well — the lock is the latch's, not the scan's.
+ * 📌 THE DEVICE TAKES NOTHING AWAY (ADR-0249): on eyes, face, gestures and speech the latch starts as the game answers
+ * `holdsKeys()`, and the child may turn it on or off like on any other device — so all three positions are offered there too.
  */
-function inputModeOrder(holdsKeys, latchRequired = false) {
-    if (!holdsKeys)
-        return ['standard', 'scan'];
-    return latchRequired ? ['sticky', 'scan'] : ['standard', 'sticky', 'scan'];
+function inputModeOrder(holdsKeys) {
+    return holdsKeys ? ['standard', 'sticky', 'scan'] : ['standard', 'scan'];
 }
-export function nextInputMode(m, holdsKeys, latchRequired = false) {
-    const order = inputModeOrder(holdsKeys, latchRequired);
+export function nextInputMode(m, holdsKeys) {
+    const order = inputModeOrder(holdsKeys);
     const i = order.indexOf(m);
     return order[(i < 0 ? 0 : i + 1) % order.length];
 }
@@ -88,8 +85,8 @@ export function nextInputMode(m, holdsKeys, latchRequired = false) {
 import { nextGameSpeed } from '../core/game-speed.js';
 import { KEYS } from '../platform/storage-keys.js';
 import { setMoveLatch } from './settings-mobility.js';
-import { latchRefusal } from './latch-refusal.js';
 import { PM_BTNS, PM_OPTIONS_BTNS, PM_GAME_BTNS } from './pause-buttons.js';
+import { aacMenuLocked } from './aac-sets.js';
 import { SCENE_KEYS, CHARACTER_ANIMATIONS, readStoredScene, storeScene } from './motion-scene.js';
 /**
  * Hover and focus on a bar's icons write its NAME in the bar's `.pause-icons-cap` and ask for its EXPLANATION.
@@ -187,9 +184,8 @@ const ICON_VISUAL = Object.freeze({
     tts: (s) => ({ on: s.ttsOn, dis: !s.privateOutput || !!s.noVoice }),
     libras: (s) => ({ on: s.librasOn }),
     tea: (s) => ({ on: s.calmMode === 2, calm: s.calmMode === 1 }),
-    // ⚠️ AND IT IS NEVER GREYED OUT. `latchRequired` says the DEVICE in use sends one command at a time and the latch cannot be
-    // turned off (ADR-0113 clause 3) — which the CYCLE tells, since `standard` simply does not appear in it. Greying the icon
-    // would take the one-button scan away from the child playing with their eyes, who is the likeliest to need it.
+    // ⚠️ AND IT IS NEVER GREYED OUT: every device may be in any of its positions (ADR-0249), and what a game cannot hold the
+    // CYCLE tells by not offering it — greying the icon would take the one-button scan away with it.
     altmove: (s) => ({ on: inputModeOf(s) !== 'standard' }),
     contrast: (s) => ({ on: hasHighContrast(s.visual) }),
     velocidade: (s) => ({ on: (s.speed ?? 1) < 1 }),
@@ -252,17 +248,25 @@ const ENGINE_ITEMS = new Set(['options', 'opcoesdojogo', 'pmback', 'acessibilida
  * «Número de jogadores»: the GAME decides how many (ADR-0147) — and one general reason for the rest. Resolved at every
  * refresh, so it follows the language of the moment the card opens.
  */
-const OWN_REASONS = new Set(['ajuda', 'addplayer', 'opcoesdojogo']);
+const OWN_REASONS = new Set(['ajuda', 'addplayer', 'opcoesdojogo', 'caa']);
 function itemReason(t, act) {
     return t(OWN_REASONS.has(act) ? `pause.motivo.${act}` : 'pause.motivo');
 }
+/**
+ * A door the ENGINE keeps locked whatever the game hands over. Today one: `caa`, the AAC menu, disabled until a
+ * pictogram set is licensed (ADR-0233 erratum). Its reason is only «menu disabled» — no licence explanation reaches the
+ * child — and a game's own `caa` action does not unlock it.
+ */
+function lockedByEngine(act) {
+    return act === 'caa' && aacMenuLocked();
+}
 /**
  * THE MENU ITEMS THIS GAME CAN ACTUALLY ACTIVATE. The others are not hidden: they stay on the card, LOCKED with their
  * reason said (ADR-0161) — an item that does nothing when pressed, and says nothing, reads to a screen-reader user as an
  * item that does not exist.
  */
 function itemsThatAct(buttons, acts) {
-    return buttons.filter((b) => ENGINE_ITEMS.has(b.act) || typeof acts[b.act] === 'function');
+    return buttons.filter((b) => !lockedByEngine(b.act) && (ENGINE_ITEMS.has(b.act) || typeof acts[b.act] === 'function'));
 }
 /**
  * THE ROOT LIST, with one more rule: `options` is a DOOR, and a door to an empty room acts no more than a dead button.
@@ -299,6 +303,11 @@ export const PM_VISIBLE_ITEMS = '.pause-menu:not([hidden]) .pm-btn:not([hidden])
  * row, not one more branch.
  */
 const DOOR_TO_LIST = Object.freeze({ options: 'opcoes', opcoesdojogo: 'jogo', pmback: 'raiz' });
+/**
+ * The other direction of the same table: the item of the root that opens each list. It is where «back» puts the cursor
+ * (ADR-0130 rule 1), and the name a list is announced by (`ui/where-the-child-is`). The root has no door.
+ */
+export const LIST_DOOR = Object.freeze({ raiz: null, opcoes: 'options', jogo: 'opcoesdojogo' });
 /**
  * Switches the visible list of ONE pause card, and puts the cursor on the FIRST item of the list that came in.
  *
@@ -308,11 +317,42 @@ const DOOR_TO_LIST = Object.freeze({ options: 'opcoes', opcoesdojogo: 'jogo', pm
 export function showPauseOptions(sp, sub) {
     sp.querySelectorAll('.pause-menu').forEach((m) => { m.hidden = m.dataset.sub !== sub; });
     const first = sp.querySelector(PM_VISIBLE_ITEMS);
-    sp.querySelectorAll('.pm-sel,.pi-sel').forEach((b) => b.classList.remove('pm-sel', 'pi-sel'));
-    if (first)
-        first.classList.add('pm-sel');
+    sp.querySelectorAll('.pi-sel').forEach((b) => b.classList.remove('pi-sel'));
+    markPauseItem(sp, first);
     return first;
 }
+/**
+ * PUTS THE CARD'S CURSOR ON `el` — the one place every move of it goes through, whatever moved it: the arrows and the pad
+ * (`ui/menu-nav`), a finger, a held press, a door between lists, «back». The card selects by class, not by browser focus,
+ * so nothing scrolls it by itself: an item past the visible part of a long list would be marked where the child cannot see
+ * it. So the list is scrolled HERE, inside the card, until the item is wholly in view (issue #134, `keepInView`).
+ */
+export function markPauseItem(sp, el) {
+    if (!el)
+        return;
+    sp.querySelectorAll('.pm-sel').forEach((b) => b.classList.remove('pm-sel'));
+    el.classList.add('pm-sel');
+    keepInView(el);
+}
+/**
+ * «BACK» FROM A LIST OF THE CARD: the root comes in with the cursor on THE ITEM THAT OPENED the list being left, not on
+ * the root's first item (ADR-0130 rule 1). A child who went into «Opções», looked, and came back is where she was; landing
+ * on «Voltar» would send her walking the root again to find her place, and a child who cannot see the mark would not even
+ * know she had been moved.
+ *
+ * Opening the card is another question and keeps `showPauseOptions(sp, 'raiz')`: a card opens on item 1 (ADR-0158).
+ * A door that is gone or hidden leaves the cursor on the first item, which is all there is to return to.
+ */
+export function backToRoot(sp) {
+    const left = sp.querySelector('.pause-menu:not([hidden])')?.dataset.sub;
+    const first = showPauseOptions(sp, 'raiz');
+    const door = left ? LIST_DOOR[left] : null;
+    const opener = door ? [...sp.querySelectorAll(PM_VISIBLE_ITEMS)].find((b) => b.dataset.act === door) : undefined;
+    if (!opener || opener === first)
+        return first;
+    markPauseItem(sp, opener);
+    return opener;
+}
 export function barAction(k, hasStart) {
     if (hasStart || k.no)
         return 'sair';
@@ -395,8 +435,6 @@ export function initPauseIcons(ctx) {
     const setPauseActor = (i) => { if (ctx.setPauseActor)
         ctx.setPauseActor(i); };
     function hasPrivateOutput(i) { return hasPrivateOutputIn(P(), ctx.getNumPlayers(), i); }
-    /** The latch refusal for this player now, or `null`. Recomputed: the device in use changes. */
-    function refusalNow(i) { return ctx.transportInUse ? latchRefusal(ctx.transportInUse(i)) : null; }
     function iconState(i) {
         const p = P()[i] || {};
         const cat = ctx.getAudioCat();
@@ -415,7 +453,6 @@ export function initPauseIcons(ctx) {
             camera: ctx.settings.cameraControl,
             locale: ctx.translator.locale(),
             privateOutput: hasPrivateOutput(i),
-            latchRequired: refusalNow(i) !== null,
             noVoice: !!ctx.noVoice?.(),
         };
     }
@@ -478,21 +515,15 @@ export function initPauseIcons(ctx) {
         altmove: (i) => {
             // verbatim: `players[i].toggleMove` with no `||{}` guard (unlike contrast/cvd below).
             const latched = !!P()[i].toggleMove;
-            const next = nextInputMode(inputModeOf({ toggleMove: latched, switchScan: ctx.settings.switchScan }), ctx.holdsKeys(), refusalNow(i) !== null);
+            const next = nextInputMode(inputModeOf({ toggleMove: latched, switchScan: ctx.settings.switchScan }), ctx.holdsKeys());
             ctx.settings.setSwitchScanValue(next === 'scan');
             // 📌 ENTERING THE SCAN LEAVES THE LATCH WHERE SHE PUT IT — the scan wins in `inputModeOf`, so the position shown is never
             // ambiguous and coming back out returns her to the choice she had made. Leaving it writes the position she walked to.
             // ⚠️ And the latch writer ANNOUNCES BY ITSELF, so it is called only where it changes something: otherwise the child would
             // hear «não precisa segurar, desligado» when what ended was the scan.
+            // 📌 On every device, eyes and voice included (ADR-0249): the write goes under the transport in use, and that stored
+            // choice is what wins over the game's default the next time that transport presses.
             if (next !== 'scan' && latched !== (next === 'sticky')) {
-                // ⚠️ THE REFUSAL, over the WRITE, which is the only thing it ever meant. The cycle above already skips `standard` on a
-                // device that always latches, so this should be unreachable — and it stays because `iconAct` is exported and the two
-                // rules could drift apart, which is the same reason the guards below give for not being belt and braces.
-                const refusal = refusalNow(i);
-                if (refusal) {
-                    ctx.srAlert(t(refusal.key));
-                    return;
-                }
                 setToggleMove(i, next === 'sticky');
                 return;
             }
@@ -523,18 +554,26 @@ export function initPauseIcons(ctx) {
             if (face)
                 ctx.srSay(t('sr.typo.font', { fam: face }));
         },
-        // PLAYING THROUGH THE WEBCAM (ADR-0215): off → hands → face → eyes → off; stored in one key, so one mode at a time.
+        /*
+         * PLAYING THROUGH THE WEBCAM (ADR-0215) and BY SPEAKING (ADR-0189, issue #184): each writes the child's answer, one stored key.
+         *
+         * 🔴 A POSITION THAT STARTS A CONTROL IS ANNOUNCED BY THE CONTROL, NOT HERE. At this line nothing has started: the control
+         * starts after the write, asynchronously, and answers either way — «Pronto: já pode jogar…» when it is really on, or the
+         * reason assertively when it cannot start (and the answer goes back to off). Saying the position here told the child
+         * «Comando de voz: ligado» over a button that read «desligado», on every press where the microphone or the runtime failed.
+         * Off is true the moment it is written, so off is still said here.
+         */
         camera: () => {
             const v = nextCameraControl(ctx.settings.cameraControl);
             ctx.settings.setCameraControlValue(v);
-            ctx.srSay(t('sr.icon.camera', { v: t(CAMERA_MODE_NAME[v]) }));
+            if (v === 'off')
+                ctx.srSay(t('sr.icon.camera', { v: t('state.off') }));
         },
-        // PLAYING BY SPEAKING (ADR-0189, issue #184): on or off, one stored key. What cannot start puts it back to off and says why,
-        // which is the control's own job (`ui/voice-control`) — this only writes the child's answer.
         voice: () => {
             const v = !ctx.settings.voiceControl;
             ctx.settings.setVoiceControlValue(v);
-            ctx.srSay(t('sr.icon.voice', { v: t(v ? 'state.on' : 'state.off') }));
+            if (!v)
+                ctx.srSay(t('sr.icon.voice', { v: t('state.off') }));
         },
         // THE LANGUAGE (the Dev, 2026-09-16): the next flag; `setLocale` stores it and every surface redraws on `i18n:change`. Said in the NEW
         // language, once it has loaded.
@@ -566,9 +605,7 @@ export function initPauseIcons(ctx) {
             ctx.srAlert(t('sr.icon.needsPrivateOutput'));
             return;
         }
-        // No blanket refusal for `altmove` here (ADR-0218): refusing the whole icon on a device that always latches would also
-        // lock «one button only» away from the child playing with their eyes. The lock lives in the CYCLE, which skips
-        // `standard` on that device, and the refusal lives inside the action, over the latch write only.
+        // No refusal for `altmove` (ADR-0249): no device locks the latch, and what a game cannot hold the CYCLE leaves out.
         const act = ICON_ACTS[k];
         if (act)
             act(i);
@@ -614,6 +651,25 @@ export function initPauseIcons(ctx) {
         // corrects it. 📌 Measured in a browser back when a guard skipped some of them: five icons in English and three still in
         // Portuguese, on the same bar.
         b.setAttribute('aria-label', computeIconLabel(t, k, st));
+        refreshCursorCaption(b);
+    }
+    /**
+     * THE NAME UNDER THE ROW FOLLOWS THE LABEL OF THE ICON UNDER THE CURSOR (ADR-0159 rule 10, ADR-0167). The caption is the
+     * visible half of what the cursor says, and the reflection is how a state changed ELSEWHERE reaches the icon — the 🦯, 📷
+     * and 👄 through the root's `stateOn`, the 🗣 through the mixer's `onCatChange` (ADR-0247). Written only on a move or a press,
+     * the caption kept the state the child had left while the label spoke the new one.
+     *
+     * Only the CURSOR's icon (`.pi-sel`, which lives only on the bars `getA11yBars` hands over): another icon's name under the
+     * row would move the cursor's only visible mark. And only when the text CHANGED: the per-screen bar's caption is a live
+     * region, and the same words rewritten are said again.
+     */
+    function refreshCursorCaption(b) {
+        if (!b.classList.contains('pi-sel'))
+            return;
+        const cap = ctx.getA11yBars().find((bar) => bar.contains(b))?.querySelector('.pause-icons-cap');
+        const text = accessibleLabel(b); // name and state only: «N de M» is spoken, never written (ADR-0167)
+        if (cap && cap.textContent !== text)
+            cap.textContent = text;
     }
     function reflectIconsIn(root, i) {
         if (!root)
@@ -694,11 +750,12 @@ export function initPauseIcons(ctx) {
      * with it (ADR-0044 item 3) and says how many items the new list has.
      */
     function announceList(sp, sub) {
-        const first = showPauseOptions(sp, sub);
-        if (!first)
+        // «back» lands on the door that opened the list being left (ADR-0130 rule 1); any other door, on the first item
+        const cursor = sub === 'raiz' ? backToRoot(sp) : showPauseOptions(sp, sub);
+        if (!cursor)
             return;
         const items = [...sp.querySelectorAll(PM_VISIBLE_ITEMS)];
-        ctx.srSay(announceItem(t, { label: first.textContent || '', position: 1, total: items.length }, ctx.settings.menuIndexOn));
+        ctx.srSay(announceItem(t, { label: cursor.textContent || '', position: items.indexOf(cursor) + 1, total: items.length }, ctx.settings.menuIndexOn));
     }
     /* ===================== THE `accessibility` MODE (ADR-0044 item 7) ===================== */
     /**
@@ -824,6 +881,10 @@ export function initPauseIcons(ctx) {
     }
     /** One item of screen `i`'s pause card pressed — a locked one, a door between its lists, the quick bar, or an action. */
     function pressPauseItem(i, sp, b) {
+        // 🔴 THE CURSOR GOES WHERE THE CHILD PRESSED (ADR-0130 rule 1). A finger or a mouse opens a panel without walking the
+        // arrows, and the mark stayed on the item the arrows had last reached — so «back» from the panel returned her to an
+        // item she never chose. The keyboard's press is already on its item; this is the pointer's half.
+        markPauseItem(sp, b);
         // LOCKED (ADR-0161): pressing it SAYS the reason and does nothing — neither door nor action.
         if (b.getAttribute('aria-disabled') === 'true') {
             const reason = b.dataset.motivo ?? '';

package/dist-pkg/ui/scan-overlay.d.ts

@@ -1,8 +1,8 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import type { Action } from '../core/actions.js';
-import { type ScanItem } from '../input/switch-scan.js';
-/** What the chip reads for one item. Pure: the caller brings the game's labeller and the word for «take nothing». */
-export declare function scanItemText(item: ScanItem, label: (a: Action) => string | null, cancelWord: string): string;
+import type { Translate } from '../core/i18n.js';
+/** What the chip reads for one item. Pure: the engine's word where the item is the engine's, else the game's own word. */
+export declare function scanItemText(item: string, label: (a: Action) => string | null, t: Translate): string;
 export interface ScanOverlay {
     /**
      * Puts the item on screen, and answers whether the words CHANGED. The same item twice does not rewrite the node — a live

package/dist-pkg/ui/scan-overlay.js

@@ -9,9 +9,17 @@
 // «Confirmar» or «Dizer a resposta», never `action2` (ADR-0074). A position the game did not name is not offered at all — the
 // list is built from the named ones — because a scan that stopped on a word nobody wrote would cost the child a full pass.
 import { SCAN_CANCEL } from '../input/switch-scan.js';
-/** What the chip reads for one item. Pure: the caller brings the game's labeller and the word for «take nothing». */
-export function scanItemText(item, label, cancelWord) {
-    return item === SCAN_CANCEL ? cancelWord : (label(item) ?? '');
+/** The ENGINE's words, by dictionary key — the wording is an interface choice (interface log 2026-09-26). */
+const ENGINE_WORDS = new Map([
+    [SCAN_CANCEL, 'scan.nothing'],
+    ['select', 'scan.door.menus'], ['start', 'scan.door.pause'],
+    ['next', 'scan.menu.next'], ['confirm', 'scan.menu.confirm'], ['back', 'scan.menu.back'], ['previous', 'scan.menu.previous'],
+    ['increase', 'scan.menu.increase'], ['decrease', 'scan.menu.decrease'],
+]);
+/** What the chip reads for one item. Pure: the engine's word where the item is the engine's, else the game's own word. */
+export function scanItemText(item, label, t) {
+    const key = ENGINE_WORDS.get(item);
+    return key ? t(key) : (label(item) ?? '');
 }
 /**
  * Mounts the chip inside the game's region, under the quick bar's band.

package/dist-pkg/ui/screen-text.d.ts

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Action } from '../core/actions.js';
+import type { WorldScope } from '../core/contract.js';
+/** What the reader is built over. Both are read at every call: a `mount()` swaps the cartridge, a panel opens. */
+export interface ScreenTextCtx {
+    /** The root's document. */
+    readonly doc: Document;
+    /** The world the mounted game declares (`GameDeclaration.world`). */
+    readonly world: () => WorldScope;
+}
+/**
+ * WHAT IS ON THE SCREEN NOW, as the sonar reads it — `''` when there is nothing the engine can read: no world, an empty one,
+ * or a world drawn on a canvas.
+ */
+export declare function screenText(ctx: ScreenTextCtx): string;
+/**
+ * The `problems` line for a world the sonar cannot read — none, or one (ADR-0169: the subject, the child's cost, the fix).
+ * Measured at every read of `problems`: a canvas is often drawn after the boot.
+ */
+export declare function unreadableWorldProblems(ctx: ScreenTextCtx): string[];
+/**
+ * A press made WITH A MENU OPEN: the menu sonar's position reads what is in front (`read`) and takes the press. Any other
+ * position is left to the menus — answers whether this one was taken.
+ */
+export declare function menuSonarPress(action: Action, ctx: ScreenTextCtx, read: (text: string) => void): boolean;

package/dist-pkg/ui/screen-text.js

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * THE SONAR'S POSITION WHILE A MENU IS OPEN. In play the position is the game's (its `preset`); with a menu open the positions
+ * are the engine's, and there R1 reads the menu — the Dev's default for the sonar («Tecla padrão para o sonar deve ser R1»).
+ */
+const MENU_SONAR = 'rightShoulder';
+/** The engine's chrome the child did not ask about (see the header). */
+const NOT_ASKED_ABOUT = [
+    '.pause-icons', '.screen-a11y', '.rodape-da-tela', '.scan-now', '#touch-controls', '.touch', '.sr-only',
+    '.gaze-overlay', '.face-overlay', '.hand-overlay', '.hud-row-clock',
+].join(', ');
+/** What is open in front of the world. */
+const DIALOG = '[role="dialog"], [role="alertdialog"], [aria-modal="true"]';
+/** Elements whose content is not words on the screen (a `<select>` shows its chosen option only — see `spokenAs`). */
+const NOT_WORDS = /^(script|style|template|noscript|svg|canvas|video|audio|iframe|object|option|optgroup)$/i;
+/** A line that already ends a sentence is not given a full stop. */
+const ENDS_A_SENTENCE = /[.!?…:;]$/u;
+/**
+ * Is this one element drawn for the eye, and meant for everyone? Its ancestors are asked by whoever walks down to it.
+ * 📌 The RENDERING decides, not the `hidden` attribute: `hidden` hides by `display: none`, which is read here, and a stylesheet
+ * that shows a `[hidden]` element puts it on the screen.
+ */
+function isShown(el) {
+    if (el.hasAttribute('inert') || el.getAttribute('aria-hidden') === 'true')
+        return false;
+    const style = el.ownerDocument?.defaultView?.getComputedStyle(el);
+    return !style || (style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0');
+}
+/** Is it drawn, with every ancestor drawn too? For an element found by a query rather than walked down to. */
+function isOnScreen(el) {
+    for (let node = el; node; node = node.parentElement)
+        if (!isShown(node))
+            return false;
+    return true;
+}
+/**
+ * Can this node be walked and asked? A host double may hand elements without the DOM's questions; then there is nothing the
+ * engine can read, and it says nothing rather than throwing into the sonar (a capability of the environment, ADR-0169).
+ */
+function canBeRead(el) {
+    return !!el && typeof el.matches === 'function' && typeof el.querySelectorAll === 'function' && typeof el.hasAttribute === 'function';
+}
+/** The dialog in front, or `null`: the one holding the focus, else the last one open in the document. */
+function dialogInFront(doc) {
+    if (typeof doc.querySelectorAll !== 'function')
+        return null;
+    const open = [...doc.querySelectorAll(DIALOG)].filter((d) => canBeRead(d) && isOnScreen(d) && !d.matches(NOT_ASKED_ABOUT));
+    const focused = doc.activeElement;
+    return open.find((d) => !!focused && d.contains(focused)) ?? open[open.length - 1] ?? null;
+}
+/** The world's element, or `null` when the game declared none, its selector matches nothing, or it cannot be read. */
+function worldElement(ctx) {
+    const scope = ctx.world();
+    const el = scope.kind === 'element' && typeof ctx.doc.querySelector === 'function' ? ctx.doc.querySelector(scope.selector) : null;
+    return canBeRead(el) ? el : null;
+}
+/** Does the world draw on a canvas the engine did not put there? Then its words are pixels. */
+function drawsOnCanvas(world) {
+    const canvases = world.matches('canvas') ? [world] : [...world.querySelectorAll('canvas')];
+    return canvases.some((c) => !c.closest(NOT_ASKED_ABOUT) && isOnScreen(c));
+}
+/** The words an element stands for instead of its children, or `null` to read its children. */
+function spokenAs(el) {
+    if (el.getAttribute('role') === 'img')
+        return el.getAttribute('aria-label') ?? '';
+    if (el.localName === 'img')
+        return el.getAttribute('alt') ?? '';
+    if (el.localName === 'select')
+        return el.selectedOptions[0]?.textContent ?? '';
+    return null;
+}
+/** Does the element start a line of its own? Everything that is not inline does — a button, a heading, a row. */
+function breaksTheLine(el) {
+    const display = el.ownerDocument?.defaultView?.getComputedStyle(el).display ?? 'block';
+    return el.localName === 'br' || (display !== 'inline' && display !== 'contents');
+}
+/**
+ * The text under `root`, in DOM order, one line per block. Lines are joined as sentences, so the voice pauses between the
+ * statement and each option and the interpreter receives them apart.
+ */
+function textOf(root) {
+    const lines = [];
+    let line = '';
+    const endLine = () => {
+        const words = line.replace(/\s+/gu, ' ').trim();
+        if (words)
+            lines.push(words);
+        line = '';
+    };
+    const readChildren = (el) => {
+        for (const child of el.childNodes ?? []) {
+            if (child.nodeType === 3)
+                line += child.textContent ?? '';
+            else if (child.nodeType === 1)
+                visit(child);
+        }
+    };
+    const visit = (el) => {
+        if (!isShown(el) || el.matches(NOT_ASKED_ABOUT) || NOT_WORDS.test(el.localName))
+            return;
+        const own = breaksTheLine(el);
+        if (own)
+            endLine();
+        const said = spokenAs(el);
+        if (said === null)
+            readChildren(el);
+        else
+            line += ` ${said} `;
+        if (own)
+            endLine();
+    };
+    visit(root);
+    endLine();
+    return lines.map((l) => (ENDS_A_SENTENCE.test(l) ? l : `${l}.`)).join(' ');
+}
+/**
+ * WHAT IS ON THE SCREEN NOW, as the sonar reads it — `''` when there is nothing the engine can read: no world, an empty one,
+ * or a world drawn on a canvas.
+ */
+export function screenText(ctx) {
+    const front = dialogInFront(ctx.doc);
+    if (front)
+        return textOf(front);
+    const world = worldElement(ctx);
+    return world && !drawsOnCanvas(world) ? textOf(world) : '';
+}
+/**
+ * The `problems` line for a world the sonar cannot read — none, or one (ADR-0169: the subject, the child's cost, the fix).
+ * Measured at every read of `problems`: a canvas is often drawn after the boot.
+ */
+export function unreadableWorldProblems(ctx) {
+    const world = worldElement(ctx);
+    if (!world || !drawsOnCanvas(world))
+        return [];
+    return ['the sonar cannot read this game\'s screen: its world draws on a <canvas>, whose words are pixels to the engine, so '
+            + 'a child who presses the sonar hears only the nearest target\'s name and side instead of what is written on screen — '
+            + 'and in deaf mode the interpreter signs that, not the screen (ADR-0234). Write the words the child must read as text '
+            + 'in the page, inside the world; a contract field for a game to hand the engine its screen\'s text is a decision the '
+            + 'Dev has not taken'];
+}
+/**
+ * A press made WITH A MENU OPEN: the menu sonar's position reads what is in front (`read`) and takes the press. Any other
+ * position is left to the menus — answers whether this one was taken.
+ */
+export function menuSonarPress(action, ctx, read) {
+    if (action !== MENU_SONAR)
+        return false;
+    const text = screenText(ctx);
+    if (text)
+        read(text);
+    return true;
+}

package/dist-pkg/ui/session-clock.d.ts

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+/**
+ * What the clock needs, all lent by the root. The three host ports are REQUIRED and may carry `undefined` — a host without
+ * them is answered here, not with a branch in the root (ADR-0232 erratum of 2026-09-25): with no clock or no tick there is no
+ * session to measure, and nothing is mounted, silently, as a capability of the environment (ADR-0169).
+ */
+export interface SessionClockCtx {
+    readonly doc: Document;
+    /** Where the clock goes: the HUD row's centre cell. Absent, or a node that takes no children, and nothing is mounted. */
+    readonly slot: HTMLElement | null;
+    readonly t: Translate;
+    /** The host's `performance`, milliseconds and monotonic. The session starts at the mount. */
+    readonly performance: {
+        now(): number;
+    } | undefined;
+    readonly setInterval: ((fn: () => void, ms: number) => number) | undefined;
+    readonly clearInterval: ((handle: number) => void) | undefined;
+    /** The polite announcer: said once, when the hour runs out. */
+    readonly announce: (text: string) => void;
+    /** Called after every redraw, so the root can measure the row again when the clock's size changed. */
+    readonly drawn: () => void;
+}
+export interface SessionClockMounted {
+    readonly el: HTMLElement;
+    /** Reads the time again and redraws what changed (the tick calls it; a language change too). */
+    refresh(): void;
+    /** Stops the tick and takes the clock off the page. */
+    remove(): void;
+}
+/** Mounts the clock in its slot, draws it now, and redraws it every second until `remove()`; `null` where it cannot. */
+export declare function mountSessionClock(ctx: SessionClockCtx): SessionClockMounted | null;