@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/ui/simulation-list.d.ts

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+export interface SimulationListCtx {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    /** The host's DOM query — this module never reaches a global (ADR-0221 step 7d). */
+    readonly find: <T extends Element>(selector: string) => T | null;
+    /** Makes an element. Injected for the same reason: no `document` in here. */
+    readonly make: <K extends keyof HTMLElementTagNameMap>(tag: K) => HTMLElementTagNameMap[K];
+    /**
+     * The simulations offered, in the order the child reads them.
+     *
+     * 📌 DATA AND NOT A CONSTANT OF THIS MODULE: which simulations an engine offers is a decision of whoever composes it, and
+     * a key this module cannot resolve is then something a caller can actually do — which is what lets the guard below be
+     * driven by a case instead of only protecting a future edit of a private list.
+     */
+    readonly keys: readonly string[];
+    /** What is running on the world right now. The list always shows IT, so a refused choice (ADR-0076) comes back by itself. */
+    readonly running: () => string | null;
+    /** The child picked one. */
+    readonly picked: (key: string) => void;
+}
+export interface SimulationList {
+    /** Builds the row if it is not there yet, and writes every word of it in the language of now. */
+    render(listSelector: string): void;
+}
+export declare function createSimulationList(ctx: SimulationListCtx): SimulationList;

package/dist-pkg/ui/simulation-list.js

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/simulation-list — THE ONE LIST OF SIMULATIONS THE EMPATHY PANEL OFFERS (ADR-0159 rule 7; ADR-0074; ADR-0129).
+//
+// More than five positions means a dropdown and not a row of buttons (ADR-0159 rule 7), and there are ten of these. The row
+// is built ONCE AND KEPT, which is the decision the whole shape follows from: the child opens this panel to try a
+// simulation, look at the game, come back and try another, and a row rebuilt at every opening would take the focus off the
+// list every time she did.
+//
+// 🎯 AND THAT IS WHY EVERYTHING A READER TAKES FROM IT IS WRITTEN AT EACH OPENING instead of at build time: the row's short
+// label, the list's own accessible name, and the name of every option. What is built once is the SHAPE; what is rewritten is
+// the TEXT. Two of them freeze the language otherwise, and a list that says «Simulações» to a child playing in English is a
+// list she cannot use.
+//
+// ⚠️ PROBED BEFORE IT MOVED, and five of nine decisions were blind — the list could lose its accessible name, pile a second
+// set of options on every opening, and name each option by its KEY. They have cases now
+// (`tests/the-simulation-list-is-read-in-the-language-of-now.browser.test.js`).
+//
+// 📌 THE EXPLANATION IS A WORD OF THIS ROW LIKE THE OTHERS, and it is written by `render` for the same reason. It used to be
+// written at build time and stayed in the language it was built in — not this list's fault alone, since 14 of the 28
+// explanation-bearing rows of the engine's panels did the same: `ui/settings-panel.fillExplain` DESTROYED the `.opt-hint` on
+// the way to the footer, so every producer's rewrite landed on a node that was no longer there. It now hides it instead.
+import { VIZ_BY_KEY } from '../render/viz-modes.js';
+export function createSimulationList(ctx) {
+    const { t } = ctx;
+    /** The row, once. Everything after this writes into it. */
+    function build(list) {
+        const row = ctx.make('div');
+        row.className = 'ctrl-row';
+        const envelope = ctx.make('span');
+        envelope.appendChild(ctx.make('strong'));
+        const hint = ctx.make('span');
+        hint.className = 'opt-hint'; // CLAUDE.md §4: the prose belongs to the footer, and this is how it gets there
+        envelope.appendChild(hint); // the TEXT is written by `render`, like every other word of this row
+        row.appendChild(envelope);
+        const choice = ctx.make('select');
+        choice.id = 'opt-simulacao';
+        choice.className = 'vol';
+        row.appendChild(choice);
+        list.textContent = '';
+        list.appendChild(row);
+        // the render below writes the list back from the world, so a refused choice returns to what runs
+        choice.addEventListener('change', () => { ctx.picked(choice.value); });
+        return choice;
+    }
+    return {
+        render(listSelector) {
+            const list = ctx.find(listSelector);
+            if (!list)
+                return;
+            const choice = list.querySelector('#opt-simulacao') ?? build(list);
+            const label = t('empathy.grupo.rotulo');
+            const row = choice.closest('.ctrl-row');
+            const strong = row?.querySelector('strong');
+            if (strong)
+                strong.textContent = label;
+            // the explanation is a word of this row like the others, so it is rewritten here and not left at build time —
+            // `ui/settings-panel.fillExplain` hides this node rather than destroying it, so the write reaches the footer
+            const hint = row?.querySelector('.opt-hint');
+            if (hint)
+                hint.textContent = t('empathy.simulacao.dica');
+            // a `<select>` whose label is a sibling is announced as «combo box» and nothing else without this
+            choice.setAttribute('aria-label', label);
+            choice.textContent = ''; // rewritten, never appended: twice open would be twice the options
+            for (const key of ctx.keys) {
+                const mode = VIZ_BY_KEY[key];
+                if (!mode)
+                    continue; // a key no mode answers for would become a blank option the child can choose
+                const option = ctx.make('option');
+                option.value = key;
+                option.textContent = t(mode.name); // what it DOES, never the key that stores it (ADR-0074)
+                choice.appendChild(option);
+            }
+            choice.value = ctx.running() ?? 'normal';
+        },
+    };
+}

package/dist-pkg/ui/simulation-over-the-world.d.ts

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { WorldScope } from '../core/contract.js';
+export interface SimulationOverTheWorldCtx {
+    /** What this cartridge declared as its world (`GameDeclaration.world`). */
+    readonly world: () => WorldScope;
+    /** The host's DOM query — this module never reaches a global. */
+    readonly find: <T extends Element>(selector: string) => T | null;
+    /** Makes the drawing layer. Injected for the same reason: no `document` in here. */
+    readonly createCanvas: () => HTMLCanvasElement;
+}
+export interface SimulationOverTheWorld {
+    /**
+     * Puts `css` on the game and nowhere else, with `improvement` kept underneath it.
+     *
+     * ⚠️ `improvement` is what the child turned on to SEE — her colour correction, her contrast enhancement. It composes
+     * under the simulation on a world that holds no menu; dropping it would take her own setting away for as long as an
+     * adult is looking through her eyes.
+     */
+    onlyInPlay(css: string, improvement: string): void;
+    /** Shows, moves and draws the layer for a DRAWN simulation — and hides it for anything else. */
+    drawLayer(key: string | null): void;
+}
+export declare function createSimulationOverTheWorld(ctx: SimulationOverTheWorldCtx): SimulationOverTheWorld;

package/dist-pkg/ui/simulation-over-the-world.js

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/simulation-over-the-world — A SIMULATION RUNS IN THE GAME, NEVER IN A MENU (ADR-0187; ADR-0151 §2; issue #182).
+//
+// The Dev, 2026-09-13: «Simulação de deficiência não pode funcionar no menu! Só no jogo!» 📏 And the reason is measured,
+// not stylistic: a CSS filter reaches every descendant and clearing it on a child does NOT undo it, so a simulated
+// blindness put on an ancestor of a menu blacks out the panel where a child turns it off. That happened, in the quiz.
+//
+// TWO HALVES OF ONE SUBJECT, which is why they live together: the FILTER (what the eye of the simulated condition does
+// to colour and light) and the LAYER (what three of them draw over the world — a tunnel, a central scotoma, scattered
+// scotomas). Both answer «where does this go so that it covers the game and nothing else», and both have to know what
+// the world is and where its menus are.
+//
+// WHY IT IS NOT IN THE COMPOSITION ROOT
+// It was ~30 branches of `boot/create-game`, and none of them wiring: «descend into a box that holds a door», «a canvas
+// has no children, so the layer goes to its parent», «what HELPS stays under what SIMULATES» are rules with reasons.
+// ADR-0221's erratum measures a root's debt in BRANCHES.
+//
+// ⚠️ PROBED BEFORE IT MOVED, and five of eleven decisions were blind — three of them the whole canvas-world path, which
+// no case in the tree drove. They have cases now (`tests/a-canvas-world-is-simulated-too.browser.test.js`).
+import { drawLowVision } from '../render/low-vision-drawing.js';
+import { VIZ_BY_KEY } from '../render/viz-modes.js';
+import { LOGICAL_W, LOGICAL_H } from '../core/constants.js';
+/**
+ * WHAT COUNTS AS A MENU, and therefore never gets a simulation on it or above it.
+ *
+ * 📌 `[data-incl-menu]` is the CARTRIDGE's own door (ADR-0187): the engine cannot tell which of a game's buttons opens
+ * the pause card, and a simulation over that door is the one a child playing by touch cannot turn off.
+ */
+const ENGINE_MENUS = '.overlay, .screen-pause, .screen-a11y, #title-icons, .rodape-da-tela, .pausa-rapida, .touch, #viz-overlay, [data-incl-menu]';
+/**
+ * The three simulations that are DRAWN rather than filtered: a colour filter can only blur for them.
+ *
+ * 📌 By the `lv` of the mode and not by its key, because the key is what a panel stores and the `lv` is what the
+ * drawing understands — the two have drifted apart before.
+ */
+const DRAWN = new Set(['tunnel', 'macular', 'diabetic']);
+export function createSimulationOverTheWorld(ctx) {
+    /** The elements this module filtered last time, so the next call can clear exactly those and no others. */
+    let filtered = [];
+    /** The declared world, when it is an element that is actually in the page. */
+    const worldElement = () => {
+        const world = ctx.world();
+        if (world.kind !== 'element')
+            return null;
+        return ctx.find(world.selector); // `null` is already a line of `problems`
+    };
+    const holdsNoMenu = (n) => typeof n.querySelector !== 'function' || !n.querySelector(ENGINE_MENUS);
+    /** Down through the world, filtering what is ordinary and stepping over — and into — what is or holds a menu. */
+    const parts = (parent, css) => {
+        for (const child of Array.from(parent.children)) {
+            if (child.matches(ENGINE_MENUS))
+                continue;
+            // 🔴 A BOX THAT HOLDS A DOOR IS WALKED INTO, not filtered: filtering it would reach the door inside, and clearing
+            // the filter on the door does not undo it. This is the defect of ADR-0187, one level down.
+            if (holdsNoMenu(child)) {
+                child.style.filter = css;
+                filtered.push(child);
+            }
+            else
+                parts(child, css);
+        }
+    };
+    return {
+        onlyInPlay(css, improvement) {
+            for (const n of filtered)
+                n.style.filter = '';
+            filtered = [];
+            const el = worldElement();
+            if (!css || !el)
+                return;
+            if (holdsNoMenu(el)) {
+                el.style.filter = [improvement, css].filter(Boolean).join(' '); // the world itself, over what helps
+                return; // recomposed from `improvement` on the next call, so it is not tracked here
+            }
+            parts(el, css);
+        },
+        drawLayer(key) {
+            const lv = key ? VIZ_BY_KEY[key]?.lv : undefined;
+            const existing = ctx.find('#viz-overlay');
+            if (!lv || !DRAWN.has(lv)) {
+                if (existing)
+                    existing.hidden = true;
+                return;
+            }
+            const el = worldElement();
+            if (!el)
+                return;
+            const host = hostFor(el);
+            if (!host)
+                return;
+            const layer = existing ?? newLayer(ctx);
+            if (layer.parentElement !== host)
+                host.appendChild(layer);
+            placeOver(layer, el);
+            const c = layer.getContext('2d');
+            if (!c)
+                return;
+            c.clearRect(0, 0, layer.width, layer.height);
+            drawLowVision(c, lv, layer.width, layer.height);
+            layer.hidden = false;
+        },
+    };
+}
+/**
+ * WHERE THE LAYER LIVES. ⚠️ A canvas HAS NO CHILDREN, so its layer is a sibling — putting it inside means it never
+ * appears at all, and nothing on screen says why.
+ */
+const hostFor = (el) => (el.tagName === 'CANVAS' ? el.parentElement : el);
+/** A fresh layer, at the world's logical size. */
+function newLayer(ctx) {
+    const layer = ctx.createCanvas();
+    layer.id = 'viz-overlay';
+    layer.setAttribute('aria-hidden', 'true');
+    // inline and not only in style.css: a page without the stylesheet must still let the clicks through to the game
+    // z 4: over the game, under the quick bar (5), the pause card (6) and the panels (60) — a simulation is never over a menu
+    Object.assign(layer.style, { position: 'absolute', inset: '0', pointerEvents: 'none', zIndex: '4' });
+    layer.width = LOGICAL_W;
+    layer.height = LOGICAL_H;
+    return layer;
+}
+/**
+ * Over the world and not over its host: a canvas world may sit anywhere inside its parent, and a layer that took the
+ * parent's box would cover the wrong pixels — and, where the parent is bigger, the menus beside it.
+ */
+function placeOver(layer, el) {
+    if (el.tagName !== 'CANVAS') {
+        Object.assign(layer.style, { width: '100%', height: '100%' });
+        return;
+    }
+    Object.assign(layer.style, { inset: 'auto', left: `${el.offsetLeft}px`, top: `${el.offsetTop}px`, width: `${el.offsetWidth}px`, height: `${el.offsetHeight}px` });
+}

package/dist-pkg/ui/simulation-refusal.d.ts

@@ -1,32 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import { type MotivoIndisponivel, type VisualState } from '../render/viz-axes.js';
-/** Uma linha pronta a traduzir: a chave e o que ela precisa. `null` = não há nada a dizer. */
-export interface Recusa {
-    readonly chave: string;
-    /** O que a criança tem de desfazer para a demonstração ser honesta. Entra na frase por `{eixo}`. */
-    readonly eixo: MotivoIndisponivel;
-}
-/**
- * A chave i18n do motivo, por eixo fora do padrão.
- *
- * ⚠️ TRÊS CHAVES E NÃO UMA COM PARÂMETRO, e a diferença é de tradução e não de estilo: em português «o tema»
- * e «a correção de cor» levam artigos diferentes, e «os dois» não é o plural de nenhum dos dois. Uma frase
- * com `{eixo}` obrigaria cada idioma a montar concordância a partir de um substantivo solto — que é
- * exactamente o defeito que o `sr.nav.clockOne` já registou para «às 1 horas».
- */
-export declare const CHAVE_DO_MOTIVO: Readonly<Record<MotivoIndisponivel, string>>;
-/**
- * Esta simulação pode ser oferecida? E se não, o que dizer.
- *
- * `null` = pode; a interface não mostra nada, porque um aviso que aparece sempre deixa de ser lido.
- */
-export declare function recusaDaSimulacao(v: VisualState): Recusa | null;
-/**
- * A simulação deve aparecer DESABILITADA em vez de sumir?
- *
- * ⚠️ SEMPRE, E É A METADE «never silently removed» DO ADR-0076. Existe como função com nome próprio, e não
- * como um `!recusa` no ponto de uso, porque ela responde a uma pergunta diferente: `recusaDaSimulacao` diz
- * *por que* não dá; esta diz *que a linha continua na tela*. Quem desenha precisa das duas, e juntá-las numa
- * só faria a resposta «não há motivo» parecer «não desenhe a linha».
- */
-export declare function mostraMesmoIndisponivel(): boolean;
+import { simulationRefusal as recusaDaSimulacaoDeRender, showsEvenWhenUnavailable as mostraMesmoIndisponivelDeRender, type Refusal as RecusaDeRender } from '../render/viz-refusal.js';
+export declare const REASON_KEY: Readonly<Record<import("../render/viz-axes.js").UnavailableReason, string>>;
+export declare const simulationRefusal: typeof recusaDaSimulacaoDeRender;
+export declare const showsEvenWhenUnavailable: typeof mostraMesmoIndisponivelDeRender;
+export type Refusal = RecusaDeRender;

package/dist-pkg/ui/simulation-refusal.js

@@ -1,57 +1,9 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/simulation-refusal — POR QUE A SIMULAÇÃO NÃO ESTÁ DISPONÍVEL, dito à criança (ADR-0076, issue #104).
-//
-// ========================= O QUE A RECUSA TEM DE FAZER, E O QUE ELA NÃO PODE FAZER =========================
-// O ADR-0076 exige que uma simulação indisponível apareça **VISÍVEL e explicada** — «never silently removed,
-// never accepted then ignored». As duas metades dessa frase descrevem dois defeitos diferentes:
-//
-//   · REMOVER EM SILÊNCIO ensina que a coisa não existe. Um adulto que ontem mostrou a simulação a uma turma
-//     e hoje não a acha conclui que ela foi tirada, e não que ele próprio ligou o alto contraste.
-//   · ACEITAR E IGNORAR é pior: a demonstração PARECE estar a correr. Sobre uma tela já corrigida, ela não
-//     mostra nem a deficiência nem a correção; sobre um tema de alto contraste, mostra o que o TEMA faz e não
-//     o que a deuteranopia faz. ⚠️ Não é uma demonstração mais fraca — **ela ensina uma coisa falsa**.
-//
-// ⚠️ E O MOTIVO É UM FACTO SOBRE A DEMONSTRAÇÃO, NUNCA UMA REPREENSÃO A QUEM ESCOLHEU. Quem ligou o alto
-// contraste ligou-o porque precisa; quem ligou a correção de cor vê melhor com ela. A frase diz o que a
-// demonstração precisa para ser honesta, e diz como voltar — nunca «desligue isso».
-//
-// ========================= POR QUE ISTO É UM MÓDULO PURO =========================
-// Mesma forma do `ui/reach-notice`: devolve DADO (chave i18n + parâmetros), não texto pronto. A frase é da
-// interface e tem de passar por `t()`; devolver português daqui repetiria o defeito que o `PADWIZ_STEPS` já
-// deixou de cometer. E, sendo puro, o desenho da recusa é conferível no project `node`, sem documento.
-//
-// Módulo-folha: importa só os tipos e o predicado do modelo de dois eixos.
-import { simulacaoIndisponivel } from '../render/viz-axes.js';
-/**
- * A chave i18n do motivo, por eixo fora do padrão.
- *
- * ⚠️ TRÊS CHAVES E NÃO UMA COM PARÂMETRO, e a diferença é de tradução e não de estilo: em português «o tema»
- * e «a correção de cor» levam artigos diferentes, e «os dois» não é o plural de nenhum dos dois. Uma frase
- * com `{eixo}` obrigaria cada idioma a montar concordância a partir de um substantivo solto — que é
- * exactamente o defeito que o `sr.nav.clockOne` já registou para «às 1 horas».
- */
-export const CHAVE_DO_MOTIVO = Object.freeze({
-    tema: 'sim.indisponivel.tema',
-    correcao: 'sim.indisponivel.correcao',
-    ambos: 'sim.indisponivel.ambos',
-});
-/**
- * Esta simulação pode ser oferecida? E se não, o que dizer.
- *
- * `null` = pode; a interface não mostra nada, porque um aviso que aparece sempre deixa de ser lido.
- */
-export function recusaDaSimulacao(v) {
-    const motivo = simulacaoIndisponivel(v);
-    return motivo === null ? null : { chave: CHAVE_DO_MOTIVO[motivo], eixo: motivo };
-}
-/**
- * A simulação deve aparecer DESABILITADA em vez de sumir?
- *
- * ⚠️ SEMPRE, E É A METADE «never silently removed» DO ADR-0076. Existe como função com nome próprio, e não
- * como um `!recusa` no ponto de uso, porque ela responde a uma pergunta diferente: `recusaDaSimulacao` diz
- * *por que* não dá; esta diz *que a linha continua na tela*. Quem desenha precisa das duas, e juntá-las numa
- * só faria a resposta «não há motivo» parecer «não desenhe a linha».
- */
-export function mostraMesmoIndisponivel() {
-    return true;
-}
+// ui/simulation-refusal — the refusal of a simulation that would teach something false (ADR-0076): the names cartridges import from ui.
+//
+// The module lives in `render/viz-refusal` since issue #167: `render/viz-setters` uses it, and render may not import ui
+// (ADR-0173). These names stay, bound to the same values and types.
+import { REASON_KEY as CHAVE_DO_MOTIVODeRender, simulationRefusal as recusaDaSimulacaoDeRender, showsEvenWhenUnavailable as mostraMesmoIndisponivelDeRender, } from '../render/viz-refusal.js';
+export const REASON_KEY = CHAVE_DO_MOTIVODeRender;
+export const simulationRefusal = recusaDaSimulacaoDeRender;
+export const showsEvenWhenUnavailable = mostraMesmoIndisponivelDeRender;

package/dist-pkg/ui/switchable-control.d.ts

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Something the accessibility bar turns on and off, and that lets go of everything it holds when turned off.
+ *
+ * ⚠️ `apply(false)` MUST release the device — the camera, the microphone — and not merely stop reading it. One camera mode at
+ * a time holds by construction only because the one going off is told first (ADR-0197, ADR-0215), and a control that keeps
+ * the camera open after being switched off breaks the next mode instead of itself.
+ */
+export interface SwitchableControl {
+    apply(on: boolean): Promise<void>;
+}

package/dist-pkg/ui/switchable-control.js

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/switchable-control — WHAT A WAY OF PLAYING WITH THE BODY IS, as one line the compiler can check (ADR-0221 step 7f).
+//
+// 🔴 WHY IT EXISTS. The eyes, the face, the hands and the voice are four ways into the same virtual controller, and they had
+// the same shape without ever saying so: four modules, four interfaces, one method each. 📏 Measured on 2026-09-22 while the
+// Dev weighed the three family interfaces: they already exported `XControlDeps` · `XControl` · `createX`, and `XControl` was
+// `apply(on: boolean): Promise<void>` in all four. The abstraction was not missing — it was unnamed, which is worse, because
+// only the co-change of the four files said it existed.
+//
+// 🎯 WHAT DECLARING IT BUYS, and it is not tidiness: `ui/camera-control.followCameraMode` takes a record of these and turns
+// the others off before turning one on. Today the compiler checks that record structurally; with the family named, a member
+// that drifts — an `apply` that stops returning a promise, one that takes no argument — fails where it is WRITTEN instead of
+// where it is combined. The Dev's own words for the choice: «custa pouco, é nativo do TypeScript, e transforma a abstração em
+// falta em algo que o compilador vê».
+//
+// ⚠️ THE VOICE IS IN THE FAMILY AND NOT IN THE CAMERA CYCLE. It answers to the 👄, not to the 📷, and it has one method more
+// (`refreshGrammar`). That is why this interface is not called «camera» anything: the family is «what the bar can switch on
+// and off», and the camera cycle is one USER of it.
+export {};

package/dist-pkg/ui/title.d.ts

@@ -1,16 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 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';
 export type TitleMenuId = 'tm-main' | 'tm-alf' | 'tm-mat' | 'tm-tab' | 'tm-fr' | 'tm-cen';
-/**
- * The 6 submenus of the title screen, in the order game.js has always hidden/shown them.
- *
- * The ORDERED array is the source and the Set is derived from it, not the other way round. A Set carries no
- * order in its type, so ui/activities-menu - which has to scan the submenus in order to find the visible one -
- * had declared its own array of the same six ids, kept in step by discipline alone. One list now.
- */
-export declare const TITLE_MENU_IDS_ORDERED: readonly TitleMenuId[];
 export declare const TITLE_MENU_IDS: ReadonlySet<TitleMenuId>;
 export declare function isTitleMenuId(v: string): v is TitleMenuId;
 export interface TitleCtx {
@@ -18,7 +8,8 @@ export interface TitleCtx {
     $: DomQuery;
 }
 export interface TitleApi {
-    /** Shows `which` and hides the other 5 submenus; toggles legend/title-block; focuses the first button. */
+    /** Shows `which` and hides the other 5 submenus; toggles legend/title-block. Focus: going IN, the first button; coming
+     *  BACK to a menu left on the way in, the item that opened the next one (ADR-0130 rule 1). */
     show: (which: TitleMenuId) => void;
 }
 export interface TitleMenuView {
@@ -31,6 +22,6 @@ export interface TitleMenuView {
     /** .title-block (the game's title art) shows only on tm-main; submenus render their own `.tm-title` heading. */
     titleBlockDisplay: '' | 'none';
 }
-/** Pure view-model for showTitleMenu(which). Verbatim port of the old function's branching. */
+/** Pure view-model for show(which). */
 export declare function computeTitleMenuView(which: TitleMenuId): TitleMenuView;
 export declare function initTitle(ctx: TitleCtx): TitleApi;

package/dist-pkg/ui/title.js

@@ -1,28 +1,27 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/title — title-screen submenu NAVIGATION (Estágio 4): extracted from game.js's showTitleMenu(). Shows one
-// submenu (`tm-main`/`tm-alf`/`tm-mat`/`tm-tab`/`tm-fr`/`tm-cen`) and hides the rest, toggles the footer legend
-// (only on `tm-main`) and the game-title block (only on `tm-main` — submenus show their own `.tm-title` instead),
-// then focuses the first button of the now-visible submenu. DI via initTitle(ctx): only `$` (DOM selector,
-// ui/dom.ts shape) is needed — the transition carries no message of its own (callers picked the srSay text
-// per-transition in game.js; duplicating an announcement here would double-speak). Everything else that used to
-// live under "menu inicial" in game.js — building the submenu markup (buildTitleMenus), the footer legend
-// (updateTitleLegend), arrow-key focus traversal (navTitle/titleButtons) and the click/keydown wiring — belongs to
-// other Estágio-4 slices and stays in game.js for now.
+// ui/title — title-screen submenu NAVIGATION. Shows one submenu (`tm-main`/`tm-alf`/`tm-mat`/`tm-tab`/`tm-fr`/`tm-cen`)
+// and hides the rest, toggles the footer legend (only on `tm-main`) and the game-title block (only on `tm-main` —
+// submenus show their own `.tm-title` instead), then focuses the first button of the now-visible submenu — or, coming
+// back to a menu left on the way in, the item that opened the next one (ADR-0130 rule 1). DI via
+// initTitle(ctx): only `$` (DOM selector, ui/dom.ts shape) is needed — the transition carries no message of its own
+// (the caller picks what to announce per transition; announcing here too would double-speak). Building the submenu
+// markup, the footer legend, arrow-key traversal and the click/keydown wiring belong to the game that owns the title
+// screen, not to this module.
 /**
- * The 6 submenus of the title screen, in the order game.js has always hidden/shown them.
+ * The 6 submenus of the title screen, in the order they are hidden/shown.
  *
  * The ORDERED array is the source and the Set is derived from it, not the other way round. A Set carries no
- * order in its type, so ui/activities-menu - which has to scan the submenus in order to find the visible one -
- * had declared its own array of the same six ids, kept in step by discipline alone. One list now.
+ * order in its type, so a reader that has to scan the submenus in order to find the visible one would otherwise
+ * declare its own array of the same six ids, kept in step by discipline alone. One list.
  */
-export const TITLE_MENU_IDS_ORDERED = [
+const TITLE_MENU_IDS_ORDERED = [
     'tm-main', 'tm-alf', 'tm-mat', 'tm-tab', 'tm-fr', 'tm-cen',
 ];
 export const TITLE_MENU_IDS = new Set(TITLE_MENU_IDS_ORDERED);
 export function isTitleMenuId(v) {
     return TITLE_MENU_IDS.has(v);
 }
-/** Pure view-model for showTitleMenu(which). Verbatim port of the old function's branching. */
+/** Pure view-model for show(which). */
 export function computeTitleMenuView(which) {
     const hidden = new Map();
     for (const id of TITLE_MENU_IDS)
@@ -34,11 +33,41 @@ export function computeTitleMenuView(which) {
         titleBlockDisplay: which === 'tm-main' ? '' : 'none',
     };
 }
-// ---------------------------------------------------------------------------------------------
-// DOM-facing (thin) — requires `document`/injected ctx
-// ---------------------------------------------------------------------------------------------
 export function initTitle(ctx) {
+    /*
+     * THE WAY IN, so the way out lands where the child was (ADR-0130 rule 1). `show` stays a «goto» — a game calls
+     * `show('tm-main')` for its «Voltar» and nothing else — and the trail tells the two apart: a menu already on the trail is
+     * a way BACK, which pops to it and returns the cursor to the item that opened the next menu; any other is a way IN,
+     * which records the item that opened it. The menus stay one at a time on screen: whether the cards behind stay visible
+     * is left open by the record.
+     */
+    const trail = [];
+    /** The menu on screen now, and the item inside it that has focus — the opener, if the next `show` goes in. */
+    function where() {
+        for (const id of TITLE_MENU_IDS_ORDERED) {
+            const el = ctx.$('#' + id);
+            if (!el || el.hidden)
+                continue;
+            const focused = el.ownerDocument.activeElement;
+            return { menu: id, opener: focused && focused !== el && el.contains(focused) ? focused : null };
+        }
+        return null;
+    }
+    /** Where the cursor lands: the recorded opener when coming back to a menu on the trail, else `null` (item 1). */
+    function walk(which) {
+        const back = trail.findIndex((step) => step.menu === which);
+        if (back >= 0) {
+            const { opener } = trail[back];
+            trail.length = back;
+            return opener;
+        }
+        const here = where();
+        if (here && here.menu !== which)
+            trail.push(here);
+        return null;
+    }
     function show(which) {
+        const opener = walk(which);
         const view = computeTitleMenuView(which);
         for (const [id, hide] of view.hidden) {
             const el = ctx.$('#' + id);
@@ -52,7 +81,9 @@ export function initTitle(ctx) {
         if (tb)
             tb.style.display = view.titleBlockDisplay;
         const activeEl = ctx.$('#' + which);
-        const b = activeEl && activeEl.querySelector('button');
+        // the opener only while it is still an item of this menu: a game may have rebuilt the menu since
+        const cameFrom = opener && activeEl?.contains(opener) ? opener : null;
+        const b = cameFrom ?? (activeEl && activeEl.querySelector('button'));
         if (b)
             b.focus();
     }

package/dist-pkg/ui/top-band.d.ts

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** What this module needs to see in order to measure. All injected: the module reaches neither `document` nor `window`. */
+export interface TopBandCtx {
+    /** The game region, where the two variables are written. Absent: there is nowhere to write, and nothing is written. */
+    readonly region: HTMLElement | null;
+    /** The accessibility bar. ⚠️ Absent = a ZERO band: there is nothing to reserve, and reserving anyway would take the
+     *  first line of the screen from the game — 12% of the height at 640×360. */
+    readonly bar: HTMLElement | null;
+    /**
+     * The HUD column that sits at the TOP, when mounted: the mission's, centred under the bar (ADR-0239 erratum). The rest of
+     * the HUD is a row at the bottom (`ui/hud-row`), and counting it here would give the game's top to the bottom row.
+     */
+    readonly hud: {
+        readonly left: HTMLElement;
+    } | null;
+    /** `getComputedStyle`, injected. Absent in a document that lacks it, and then the name line is not measured. */
+    readonly computedStyle?: (el: HTMLElement) => CSSStyleDeclaration;
+}
+/**
+ * Measures the top and writes `--hud-mission-top`, `--scan-top` and `--barra-a11y-h` on the region.
+ *
+ * 🔴 THE SCAN CHIP TAKES ROOM FOR THE SAME REASON AS THE NAME LINE (ADR-0218): it is HUD, and HUD that does not reserve its
+ * space is the engine writing over the game. But it is PLACED by `--scan-top`, written BEFORE it widens the room; see
+ * the loop in the header.
+ */
+export declare function reserveTopBand(ctx: TopBandCtx): void;