@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/ui/mobility-choices.d.ts

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { toggleLabel } from './dom.js';
+import type { Translate } from '../core/i18n.js';
+/** Clamps the selected player back to 0 once it falls outside 0..numPlayers-1 (e.g. player count dropped). */
+export declare function clampSelPlayer(sel: number, numPlayers: number): number;
+/** Whether ANY player currently uses Easy Mode or a toggle — lights the #opt-movement bar button. */
+export declare function anyMobilityActive(players: readonly {
+    readonly easy?: boolean;
+    readonly toggleMove?: boolean;
+}[]): boolean;
+/** The on/off label for #opt-facil and #opt-altmove. A re-export of ui/dom's, which is the only one — a local body would
+ *  be a copy. */
+export declare const onOffLabel: typeof toggleLabel;
+/**
+ * Full innerHTML for #movement-players, given the player count and the active index. Pure string building —
+ * no DOM. NOTE: the panel keeps this list `hidden` — a single player edits only their own screen
+ * (scope = pauseActor) — but the tabs/buttons are still built and wired for >1 player.
+ */
+export declare function playerTabsHTML(numPlayers: number, selected: number): string;
+/**
+ * The player prefix that opens an announcement when there is more than one screen. A single screen gets no prefix —
+ * naming the player to whoever is alone is noise, and noise on a screen reader costs listening time.
+ */
+export declare function playerPrefix(t: Translate, i: number, numPlayers: number): string;
+/** srSay text for an Easy Mode change. The whole sentence comes from the dictionary — see `sr.motor.easyOn`. */
+export declare function easyAnnouncement(t: Translate, i: number, numPlayers: number, on: boolean): string;

package/dist-pkg/ui/mobility-choices.js

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/mobility-choices — what the mobility panel's choices ARE, with no panel: the selected player clamped to the players there
+// are, whether any of them uses easy mode or a toggle, the player tabs, and the easy-mode announcement with its player prefix
+// (ADR-0221; issue #203).
+//
+// It left `ui/settings-mobility` as the five `*-choices` modules before it did, and for the same reason: the node test drove
+// these names with no document — the seam was already drawn by the suite. The stored KEYS stay there, beside the writers that
+// use them. What stays is the panel: finding its controls, wiring them, writing the toggles, reflecting the choice.
+import { toggleLabel } from './dom.js';
+/** Clamps the selected player back to 0 once it falls outside 0..numPlayers-1 (e.g. player count dropped). */
+export function clampSelPlayer(sel, numPlayers) {
+    return sel >= numPlayers ? 0 : sel;
+}
+/** Whether ANY player currently uses Easy Mode or a toggle — lights the #opt-movement bar button. */
+export function anyMobilityActive(players) {
+    return players.some((p) => p.easy || p.toggleMove);
+}
+/** The on/off label for #opt-facil and #opt-altmove. A re-export of ui/dom's, which is the only one — a local body would
+ *  be a copy. */
+export const onOffLabel = toggleLabel;
+/**
+ * Full innerHTML for #movement-players, given the player count and the active index. Pure string building —
+ * no DOM. NOTE: the panel keeps this list `hidden` — a single player edits only their own screen
+ * (scope = pauseActor) — but the tabs/buttons are still built and wired for >1 player.
+ */
+export function playerTabsHTML(numPlayers, selected) {
+    if (numPlayers <= 1)
+        return '';
+    return Array.from({ length: numPlayers }, (_, p) => `<button class="mode-btn${p === selected ? ' is-on' : ''}" data-mp="${p}" type="button">Jogador ${p + 1}</button>`).join('');
+}
+/**
+ * The player prefix that opens an announcement when there is more than one screen. A single screen gets no prefix —
+ * naming the player to whoever is alone is noise, and noise on a screen reader costs listening time.
+ */
+export function playerPrefix(t, i, numPlayers) {
+    return numPlayers > 1 ? t('sr.player.prefix', { n: i + 1 }) : '';
+}
+/** srSay text for an Easy Mode change. The whole sentence comes from the dictionary — see `sr.motor.easyOn`. */
+export function easyAnnouncement(t, i, numPlayers, on) {
+    return playerPrefix(t, i, numPlayers) + t(on ? 'sr.motor.easyOn' : 'sr.motor.easyOff');
+}

package/dist-pkg/ui/motion-choices.d.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+import type { MotionSceneKey, MotionCharDef, MotionPlayer, MotionSceneFlags } from './motion-scene.js';
+/**
+ * Target → i18n KEY of the label. KEYS, and not text, for the usual reason: a `const` table of text resolves ONCE, on
+ * import, and stays frozen in the boot language.
+ *
+ * And it is ONE table: `rmChar[].lbl` holds a key of THIS table rather than a copy of the label, because copies of the
+ * same labels with nothing linking them make changing one label a multi-file edit where forgetting one is silent.
+ */
+export declare const RM_LABEL: Record<string, string>;
+/** i18n KEYS of the three CRT effects (see `RM_LABEL`). */
+export declare const CRT_LBL: Record<'scan' | 'vig' | 'round', string>;
+export declare const CRT_ROUND_LEVELS: readonly string[];
+/** The selected player never points outside the current number of screens. */
+export declare function clampSelectedPlayer(selected: number, total: number): number;
+/** true when EVERYTHING (scene + selected character) already has reduced motion ON, that is, frozen — the name follows
+ *  `rm[k]`/`player[prop]`, which mean "reduced", not "animated". Decides whether the master button offers "Resume"
+ *  (true) or "Stop" (false). */
+export declare function allMotionFrozen(rmKeys: readonly MotionSceneKey[], rm: MotionSceneFlags, rmChar: readonly MotionCharDef[], player: MotionPlayer | undefined): boolean;
+/** allFrozen=true (everything already frozen) → offers "Resume"; otherwise → offers "Stop". */
+export declare function motionMasterLabel(t: Translate, allFrozen: boolean): string;
+/** `label` arrives ALREADY TRANSLATED, and the state is a frame with `{alvo}` rather than a concatenated suffix — which
+ *  lets a language put the state BEFORE the target, something a concatenation does not allow. */
+export declare function sceneMotionAnnouncement(t: Translate, label: string, frozen: boolean): string;
+export declare function crtToggleAnnouncement(t: Translate, label: string, on: boolean): string;
+export declare function crtLevelLabel(t: Translate, level: number): string;
+export declare function crtRoundAnnouncement(t: Translate, label: string, level: number): string;
+/** `nowFrozen` = the NEW value of rm[k]/player[prop] applied by the master button (true = everything was just frozen;
+ *  false = everything was just resumed). */
+export declare function stopResumeAllAnnouncement(t: Translate, nowFrozen: boolean): string;

package/dist-pkg/ui/motion-choices.js

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/motion-choices — WHAT A MOVEMENT CHOICE IS, with no document anywhere near it.
+//
+// 📌 THE SUITE HAD ALREADY DRAWN THIS SEAM, which is what makes the cut a reading and not an opinion:
+// `tests/settings-motion.node.test.js` exercises exactly these names, and the node project mounts no document — so
+// whoever wrote those cases had to know where the panel stops being a panel. It is the fifth module to come out this
+// way, after `ui/audio-choices`, `ui/typo-choices`, `ui/control-choices` and `ui/visual-choices`.
+//
+// What lives here answers «what is each target called, is everything already frozen, and what does the screen reader
+// hear»; what stays in `ui/settings-motion` is the work its name never mentioned — mounting the rows, reconciling
+// them with the cartridge, wiring them and reflecting the choice.
+/**
+ * Target → i18n KEY of the label. KEYS, and not text, for the usual reason: a `const` table of text resolves ONCE, on
+ * import, and stays frozen in the boot language.
+ *
+ * And it is ONE table: `rmChar[].lbl` holds a key of THIS table rather than a copy of the label, because copies of the
+ * same labels with nothing linking them make changing one label a multi-file edit where forgetting one is silent.
+ */
+export const RM_LABEL = {
+    parallax: 'rm.parallax', decor: 'rm.decor', items: 'rm.items',
+    walk: 'rm.walk', breath: 'rm.breath', flavor: 'rm.flavor', particles: 'rm.particles',
+};
+/** i18n KEYS of the three CRT effects (see `RM_LABEL`). */
+export const CRT_LBL = { scan: 'rm.crt.scan', vig: 'rm.crt.vig', round: 'rm.crt.round' };
+// ⚠️ KEYS, because the levels are words the child hears: a raw word here would announce a level in one language inside a
+// game running in another (ADR-0151 made the corners steps ⯇ ⯈).
+export const CRT_ROUND_LEVELS = ['crt.round.off', 'crt.round.small', 'crt.round.large'];
+/** The selected player never points outside the current number of screens. */
+export function clampSelectedPlayer(selected, total) {
+    return selected >= total ? 0 : selected;
+}
+/** true when EVERYTHING (scene + selected character) already has reduced motion ON, that is, frozen — the name follows
+ *  `rm[k]`/`player[prop]`, which mean "reduced", not "animated". Decides whether the master button offers "Resume"
+ *  (true) or "Stop" (false). */
+export function allMotionFrozen(rmKeys, rm, rmChar, player) {
+    // 🔴 WITH NO CHARACTER, THE CHARACTER HALF DOES NOT COUNT. Requiring `player && player[c.prop]` for every target is
+    // ALWAYS FALSE when there is no player: in a game that declares no `players` — a quiz, a puzzle — `allFrozen` would
+    // stay `false`, the master button would compute `next = true` on EVERY click, and a child who stopped all the
+    // animations would have no way to bring them back. That costs most to whoever froze them because they needed to:
+    // that person does not press the button out of curiosity, they press it feeling sick.
+    //
+    // 📌 With a player nothing changes: `!player` is false and the count is target by target.
+    return rmKeys.every((k) => rm[k]) && (!player || rmChar.every((c) => !!player[c.prop]));
+}
+/** allFrozen=true (everything already frozen) → offers "Resume"; otherwise → offers "Stop". */
+export function motionMasterLabel(t, allFrozen) {
+    return t(allFrozen ? 'a11y.resumeAll' : 'a11y.stopAll'); // no glyph in the name (ADR-0159 rule 12), in the page's language
+}
+/** `label` arrives ALREADY TRANSLATED, and the state is a frame with `{alvo}` rather than a concatenated suffix — which
+ *  lets a language put the state BEFORE the target, something a concatenation does not allow. */
+export function sceneMotionAnnouncement(t, label, frozen) {
+    return t(frozen ? 'sr.rm.frozen' : 'sr.rm.animated', { alvo: label });
+}
+export function crtToggleAnnouncement(t, label, on) {
+    return t(on ? 'sr.crt.on' : 'sr.crt.off', { efeito: label });
+}
+export function crtLevelLabel(t, level) {
+    const key = CRT_ROUND_LEVELS[level];
+    return key ? t(key) : '';
+}
+export function crtRoundAnnouncement(t, label, level) {
+    return t('sr.crt.round', { efeito: label, nivel: crtLevelLabel(t, level) });
+}
+/** `nowFrozen` = the NEW value of rm[k]/player[prop] applied by the master button (true = everything was just frozen;
+ *  false = everything was just resumed). */
+export function stopResumeAllAnnouncement(t, nowFrozen) {
+    return t(nowFrozen ? 'sr.rm.allStopped' : 'sr.rm.allResumed');
+}

package/dist-pkg/ui/motion-scene.d.ts

@@ -1,22 +1,25 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Store } from '../platform/storage.js';
 import type { PlayerView } from '../core/entity.js';
-/** As quatro animações de CENA, como vocabulário fechado. */
+/** What the scene flags are read and written through: the page's store, built by the root (ADR-0232, issue #207). */
+export type SceneStore = Pick<Store, 'getJSON' | 'setJSON'>;
+/** The four SCENE animations, as a closed vocabulary. */
 export type MotionSceneKey = 'parallax' | 'decor' | 'items' | 'particles';
-/** As três do PERSONAGEM, que são campos do jogador. */
+/** The three CHARACTER ones, which are player fields. */
 export type MotionCharProp = 'rmWalk' | 'rmBreath' | 'rmFlavor';
-/** Uma animação do personagem e a chave i18n do seu rótulo. */
+/** A character animation and the i18n key of its label. */
 export interface MotionCharDef {
     readonly prop: MotionCharProp;
     readonly lbl: string;
 }
-/** ⚠️ `PlayerView` e não `Record`: um `Record` aceita qualquer objecto com essas chaves, jogador ou não. */
+/** ⚠️ `PlayerView` and not `Record`: a `Record` accepts any object with those keys, player or not. */
 export type MotionPlayer = PlayerView<'rmWalk' | 'rmBreath' | 'rmFlavor'>;
-/** Os quatro interruptores de cena. Objecto VIVO — ver a nota sobre partilha por referência no topo. */
+/** The four scene switches. A LIVE object — see the note on sharing by reference at the top. */
 export type MotionSceneFlags = Record<MotionSceneKey, boolean>;
-/** As quatro animações de CENA. São a união inteira, e o compilador prova-o logo abaixo. */
-export declare const CHAVES_DE_CENA: readonly ["parallax", "decor", "items", "particles"];
-/** As três animações do PERSONAGEM, com as chaves que o `RM_LABEL` desta mesma camada já traduz. */
-export declare const ANIMACOES_DO_PERSONAGEM: readonly [{
+/** The four SCENE animations. They are the whole union, and the compiler proves it just below. */
+export declare const SCENE_KEYS: readonly ["parallax", "decor", "items", "particles"];
+/** The three CHARACTER animations, with the keys `RM_LABEL` in this same layer already translates. */
+export declare const CHARACTER_ANIMATIONS: readonly [{
     readonly prop: "rmWalk";
     readonly lbl: "rm.walk";
 }, {
@@ -26,16 +29,18 @@ export declare const ANIMACOES_DO_PERSONAGEM: readonly [{
     readonly prop: "rmFlavor";
     readonly lbl: "rm.flavor";
 }];
-/** Os quatro interruptores no padrão do sistema — `prefers-reduced-motion`, por `defaultReducedMotion()`. */
-export declare function padraoDeCena(): MotionSceneFlags;
 /**
- * O estado guardado, ou o padrão do sistema quando não há nada guardado.
+ * The four switches at the system default. `reducedByDefault` is what `prefers-reduced-motion` answers — the caller asks
+ * through `defaultReducedMotion(matchMedia)`.
+ */
+export declare function sceneDefault(reducedByDefault: boolean): MotionSceneFlags;
+/**
+ * The stored state, or the system default (`reducedByDefault`, as in `sceneDefault`) when nothing is stored.
  *
- * ⚠️ CADA CHAVE É LIDA UMA A UMA, e não `{...guardado}`. O que está no armazenamento veio do navegador de uma
- * criança e pode estar truncado ou de uma versão anterior: espalhar o objecto traria chaves a mais e deixaria
- * chaves a menos por preencher, e uma chave em falta lê-se como `undefined` — que é «não reduzido» para quem
- * pediu redução. O laço garante exactamente as quatro.
+ * ⚠️ EACH KEY IS READ ONE BY ONE, not spread. What is in storage came from a child's browser and may be truncated or
+ * from an earlier version: spreading the object would bring extra keys and leave missing ones unfilled, and a missing
+ * key reads as `undefined` — which is "not reduced" for whoever asked for reduction. The loop guarantees exactly four.
  */
-export declare function lerCenaGuardada(): MotionSceneFlags;
-/** Guarda os quatro interruptores. Chamada depois de cada mudança, como o `saveRM` do cartucho fazia. */
-export declare function guardarCena(rm: MotionSceneFlags): void;
+export declare function readStoredScene(store: SceneStore, reducedByDefault: boolean): MotionSceneFlags;
+/** Stores the four switches. Called after each change. */
+export declare function storeScene(store: SceneStore, rm: MotionSceneFlags): void;

package/dist-pkg/ui/motion-scene.js

@@ -1,76 +1,44 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/motion-scene — O MOVIMENTO REDUZIDO DE CENA VOLTA PARA A ENGINE (ADR-0106 §4, etapa 1).
-//
-// ========================= O QUE ESTAVA ERRADO, MEDIDO E NÃO SUPOSTO =========================
-// O `PauseIconsCtx` e o `SettingsMotionCtx` pediam ao JOGO quatro coisas — `rm`, `rmKeys`, `rmChar`,
-// `saveRM` — e o ADR-0106 chamou-lhes «do jogo POR ACIDENTE». A medição de 2026-09-08 no `game-platformer`
-// mostra que a palavra é exacta, porque nenhuma das quatro contém uma escolha do jogo:
-//
-//   · `RM_KEYS` era `['parallax','decor','items','particles']` escrito à mão — que é a união `MotionSceneKey`
-//     INTEIRA, declarada na engine. Não é «quais destes este jogo tem»: são os quatro, sempre;
-//   · `RM_CHAR` era as três propriedades de `MotionCharProp` com as chaves i18n `rm.walk`/`rm.breath`/
-//     `rm.flavor` — e o `RM_LABEL` da engine já traduz essas mesmas chaves;
-//   · `rm` era lido de `store.KEYS.reducedMotion` (chave da engine) com `defaultReducedMotion()` (padrão da
-//     engine);
-//   · `saveRM` era `store.setJSON` para a mesma chave da engine.
-//
-// ⚠️ ERA UMA CÓPIA, NÃO UMA DECISÃO. E o custo não é elegância: **cinco jogos não têm nada disto**, porque
-// cada cartucho tinha de se lembrar de escrever as quatro linhas. Uma criança que precisa de parar o
-// movimento da cena abre esses cinco e não tem por onde.
-//
-// ⚠️ O QUE CONTINUA A SER DO JOGO, e por natureza: o EFEITO. Quem lê `rm.decor` para congelar as nuvens é o
-// jogo — a engine possui o interruptor, não o que ele apaga. É a mesma divisão do ADR-0106: o valor é da
-// engine, o efeito colateral é do cartucho.
-//
-// ⚠️ E O OBJECTO É PARTILHADO POR REFERÊNCIA, de propósito. No cartucho ele entra em oito módulos
-// (`weather`, `life`, `fx`, …) que leem `rm.decor`/`rm.particles` a cada quadro. Devolver uma cópia faria
-// cada leitor ver um valor congelado no arranque, e o interruptor deixaria de fazer nada — em silêncio.
-// ⚠️ O VOCABULÁRIO DESCEU PARA CÁ, e foi um gate que o mandou. Escrito ao contrário — os tipos no
-// `settings-motion` e este módulo a importá-los —, o `tests/lotes-passo5` reprovou por CICLO: o painel importa
-// os valores daqui e este importava os tipos de lá. O analisador conta o `import type` como aresta, e tem
-// razão para o que mede (ordem de extração). A saída certa não era calar o gate: o vocabulário pertence a quem
-// possui os VALORES, e o painel é consumidor dele. O `settings-motion` mantém os nomes publicados por alias,
-// então nenhuma linha de importação de nenhum consumidor muda.
-import * as store from '../platform/storage.js';
-import { defaultReducedMotion } from '../core/state.js';
-/** As quatro animações de CENA. São a união inteira, e o compilador prova-o logo abaixo. */
-export const CHAVES_DE_CENA = ['parallax', 'decor', 'items', 'particles'];
-const _COBRE_A_UNIAO = true;
-void _COBRE_A_UNIAO;
-/** As três animações do PERSONAGEM, com as chaves que o `RM_LABEL` desta mesma camada já traduz. */
-export const ANIMACOES_DO_PERSONAGEM = Object.freeze([
+import { KEYS } from '../platform/storage-keys.js';
+/** The four SCENE animations. They are the whole union, and the compiler proves it just below. */
+export const SCENE_KEYS = ['parallax', 'decor', 'items', 'particles'];
+const _COVERS_THE_UNION = true;
+void _COVERS_THE_UNION;
+/** The three CHARACTER animations, with the keys `RM_LABEL` in this same layer already translates. */
+export const CHARACTER_ANIMATIONS = Object.freeze([
     { prop: 'rmWalk', lbl: 'rm.walk' },
     { prop: 'rmBreath', lbl: 'rm.breath' },
     { prop: 'rmFlavor', lbl: 'rm.flavor' },
 ]);
-const _COBRE_O_PERSONAGEM = true;
-void _COBRE_O_PERSONAGEM;
-/** Os quatro interruptores no padrão do sistema — `prefers-reduced-motion`, por `defaultReducedMotion()`. */
-export function padraoDeCena() {
+const _COVERS_THE_CHARACTER = true;
+void _COVERS_THE_CHARACTER;
+/**
+ * The four switches at the system default. `reducedByDefault` is what `prefers-reduced-motion` answers — the caller asks
+ * through `defaultReducedMotion(matchMedia)`.
+ */
+export function sceneDefault(reducedByDefault) {
     const o = {};
-    const padrao = defaultReducedMotion();
-    for (const k of CHAVES_DE_CENA)
-        o[k] = padrao;
+    for (const k of SCENE_KEYS)
+        o[k] = reducedByDefault;
     return o;
 }
 /**
- * O estado guardado, ou o padrão do sistema quando não há nada guardado.
+ * The stored state, or the system default (`reducedByDefault`, as in `sceneDefault`) when nothing is stored.
  *
- * ⚠️ CADA CHAVE É LIDA UMA A UMA, e não `{...guardado}`. O que está no armazenamento veio do navegador de uma
- * criança e pode estar truncado ou de uma versão anterior: espalhar o objecto traria chaves a mais e deixaria
- * chaves a menos por preencher, e uma chave em falta lê-se como `undefined` — que é «não reduzido» para quem
- * pediu redução. O laço garante exactamente as quatro.
+ * ⚠️ EACH KEY IS READ ONE BY ONE, not spread. What is in storage came from a child's browser and may be truncated or
+ * from an earlier version: spreading the object would bring extra keys and leave missing ones unfilled, and a missing
+ * key reads as `undefined` — which is "not reduced" for whoever asked for reduction. The loop guarantees exactly four.
  */
-export function lerCenaGuardada() {
-    const guardado = store.getJSON(store.KEYS.reducedMotion, null);
-    if (!guardado || typeof guardado !== 'object')
-        return padraoDeCena();
+export function readStoredScene(store, reducedByDefault) {
+    const stored = store.getJSON(KEYS.reducedMotion, null);
+    if (!stored || typeof stored !== 'object')
+        return sceneDefault(reducedByDefault);
     const o = {};
-    for (const k of CHAVES_DE_CENA)
-        o[k] = !!guardado[k];
+    for (const k of SCENE_KEYS)
+        o[k] = !!stored[k];
     return o;
 }
-/** Guarda os quatro interruptores. Chamada depois de cada mudança, como o `saveRM` do cartucho fazia. */
-export function guardarCena(rm) {
-    store.setJSON(store.KEYS.reducedMotion, rm);
+/** Stores the four switches. Called after each change. */
+export function storeScene(store, rm) {
+    store.setJSON(KEYS.reducedMotion, rm);
 }

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

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { PanelLabels, PanelShell, PanelShellCtx } from './panel-shell.js';
+/** The slice of the overlay stack a panel needs. Narrow on purpose: this file never opens a second panel. */
+export interface PanelStack {
+    /** Brings the overlay to the front of the z-order, as `ui/settings-panel` computes it. */
+    readonly frontOverlay: (el: HTMLElement) => void;
+    /** Joins the Escape chain. Without it, Escape walks an empty registry and the panel traps the child. */
+    readonly register: (id: string, entry: {
+        close: () => void;
+        inEscapeChain: boolean;
+    }) => void;
+    /** Returns focus to whatever opened the panel (WCAG 2.4.3). */
+    readonly restoreFocus?: (id: string) => void;
+}
+export interface MountPanelCtx extends PanelShellCtx {
+    /** Where the overlay lives. The composition root resolves it; this file does not guess at `#game-region`. */
+    readonly host: HTMLElement;
+    readonly overlays: PanelStack;
+    /**
+     * HEARS A LANGUAGE CHANGE, and returns its release — the root's `localeOn` (ADR-0232 D3 erratum point 4), which hands
+     * that release to the root's disposing door, so a panel of an ended root stops redrawing (ADR-0220). REQUIRED (ADR-0232
+     * D4): the panel used to listen for `i18n:change` on the window, a listener nothing ever took off.
+     */
+    readonly localeOn: (react: (locale: string) => void) => () => void;
+}
+export interface MountPanelSpec {
+    /** The panel's id: `typo`, `audio`, `visual`… Identity, resolved once — unlike the words below. */
+    readonly id: string;
+    /** The list's id when it is not `${id}-list`. One of the eight needs it — see `PanelShellSpec.idDaLista`. */
+    readonly listId?: string;
+    /**
+     * The panel's WORDS, already translated — and resolved AT EVERY OPEN rather than once at mount.
+     *
+     * 🔴 A function and not four strings, because the panel is born hidden and the boot has a gap. `initI18n`
+     * applies the fallback language synchronously — so the page is never blank — and then ASKS for en/es, which
+     * is asynchronous. Anything the JavaScript builds inside that gap captures the fallback text and nothing
+     * rebuilds it; 📏 measured in a browser on 2026-09-08, the icon bar served five labels in English and three
+     * still in the fallback, on the same line.
+     *
+     * 🎯 AND THE PANEL IS THE ONE PLACE WHERE THAT COSTS NOTHING TO FIX. Nobody reads a hidden dialog, so its
+     * words only have to be right when it opens — no `localeReady()` wiring per panel, and a language changed
+     * mid-game is right on the next open too.
+     */
+    readonly labels: () => PanelLabels;
+    /**
+     * The panel's own `render()`.
+     *
+     * ⚠️ CALLED ON EVERY OPEN, not once at mount. Two reasons, both measured in this tree: a panel that renders
+     * once shows a stale state after the child changes the same setting from the quick bar; and
+     * `ui/settings-panel.fillExplain` has to run after every render or the prose climbs back inside the rows
+     * on the first click — the defect ADR-0129 measured in `settings-visual` and `settings-empathy`.
+     */
+    readonly render: () => void;
+    /**
+     * THIS PANEL ALREADY WIRES ITS OWN `#X-close`, so pass its `close()` here instead of letting this file wire
+     * a second listener onto the same button.
+     *
+     * 📏 Measured across the eight on 2026-09-11, and the three-way split is why this field is a function rather
+     * than a flag: `settings-typo`, `-motor`, `-controls`, `-visual` and `-audio` have no `close()` at all and
+     * need the whole five lines; `settings-aac` and `-empathy` have one AND bind the button themselves at init;
+     * `settings-motion` has one and does NOT bind the button, so it takes the default path and its `close()`
+     * simply goes unused.
+     *
+     * ⚠️ AND IT IS THE ESCAPE CHAIN THAT MAKES THIS MATTER, not tidiness. If this file wired its own closer and
+     * registered it while the panel's button ran the panel's closer, one control would take two paths to the
+     * same job — and the day one of them learns to do something extra, only half the ways out learn it.
+     */
+    readonly closeOwn?: () => void;
+}
+export interface MountedPanel {
+    readonly shell: PanelShell;
+    readonly open: () => void;
+    readonly close: () => void;
+}
+/**
+ * Builds a panel's shell, puts it in the document, and wires open/close/Escape.
+ *
+ * Idempotent through `mountShell`, which reuses an overlay that already carries the id — so mounting twice
+ * leaves one panel, which is what ADR-0139's third gate asks of two cartridges on one page.
+ */
+export declare function mountPanel(ctx: MountPanelCtx, spec: MountPanelSpec): MountedPanel;

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

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { applyLabels, mountShell } from './panel-shell.js';
+import { navigableItems } from './menu-items.js';
+/**
+ * Builds a panel's shell, puts it in the document, and wires open/close/Escape.
+ *
+ * Idempotent through `mountShell`, which reuses an overlay that already carries the id — so mounting twice
+ * leaves one panel, which is what ADR-0139's third gate asks of two cartridges on one page.
+ */
+export function mountPanel(ctx, spec) {
+    const panelShell = mountShell(ctx, { id: spec.id, listId: spec.listId, ...spec.labels() });
+    // Appending an element that is already a child moves it; it never duplicates. Guarding on `parentNode`
+    // would be the same operation written twice.
+    ctx.host.appendChild(panelShell.overlay);
+    const closePanel = spec.closeOwn ?? (() => {
+        panelShell.overlay.hidden = true;
+        ctx.overlays.restoreFocus?.(spec.id);
+    });
+    // 🔴 NO NUMBERING (ADR-0167): the stops drew their index here, renumbered by an observer on every render; the place is
+    // now only spoken, after the name, by the navigation.
+    const openPanel = () => {
+        // ⚠️ THE LABELS BEFORE `render()`, and the order has a consequence: `ui/settings-panel.fillExplain` reads the card's
+        // `data-explain-idle` to build the footer, and each panel's render is what calls it.
+        applyLabels(panelShell, spec.labels());
+        spec.render();
+        panelShell.overlay.hidden = false;
+        ctx.overlays.frontOverlay(panelShell.overlay);
+        panelShell.close.focus?.();
+    };
+    /*
+     * A LANGUAGE CHANGED WITH THE PANEL OPEN REDRAWS IT, AND THE CHILD STAYS WHERE THEY WERE (ADR-0031). 📏 Measured: with
+     * the panel open, `setLocale` left every word of it in the old language until it was closed and reopened.
+     * 📌 Focus is kept by PLACE: the control itself when the render left it in the document, else the stop at the same
+     * position — `render()` rebuilds rows by `innerHTML`, and a redraw that drops focus on «Voltar» loses the child's place.
+     * A hidden panel does nothing: its words are resolved when it opens.
+     */
+    ctx.localeOn(() => {
+        if (panelShell.overlay.hidden)
+            return;
+        const doc = panelShell.card.ownerDocument;
+        const focused = doc.activeElement;
+        const focusedIndex = focused && panelShell.card.contains(focused) ? navigableItems(panelShell.card).indexOf(focused) : -1;
+        applyLabels(panelShell, spec.labels());
+        spec.render();
+        if (focusedIndex < 0 || !focused)
+            return;
+        const destino = focused.isConnected ? focused : navigableItems(panelShell.card)[focusedIndex];
+        if (destino && destino !== doc.activeElement)
+            destino.focus();
+    });
+    // Only when the panel does NOT wire its own button. See `closeOwn`: two listeners on the same control are two owners of
+    // the same exit, and that is how exits drift.
+    if (!spec.closeOwn)
+        panelShell.close.addEventListener('click', closePanel);
+    // ⚠️ THE ESCAPE CHAIN IS NOT DECORATION. `ui/settings-panel.escapeTarget()` walks the registry, and under
+    // `createGame` that registry was EMPTY — nothing had ever registered. A modal dialog no key closes is the
+    // trap ADR-0044 §2 names about the pause itself: «a menu you cannot leave is a trap, and the trap costs
+    // most to whoever cannot see it».
+    ctx.overlays.register(spec.id, { close: closePanel, inEscapeChain: true });
+    return { shell: panelShell, open: openPanel, close: closePanel };
+}

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

@@ -1,53 +1,87 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** As três coisas do `document` de que a casca precisa. Mesma forma de `ui/loop-crash`. */
+/** The things from `document` the shell needs. The same shape as `ui/loop-crash`. */
 export interface PanelShellCtx {
-    /** `document.querySelector`, injetado — a casca nunca alcança o `document` global. */
-    procurar: (sel: string) => HTMLElement | null;
-    /** `document.createElement`, injetado. */
-    criar: (tag: string) => HTMLElement;
+    /** `document.querySelector`, injected — the shell never reaches the global `document`. */
+    find: (sel: string) => HTMLElement | null;
+    /** `document.createElement`, injected. */
+    create: (tag: string) => HTMLElement;
 }
 export interface PanelShellSpec {
-    /** O id do painel: `typo`, `audio`, `visual`… Gera `#X`, `#X-title`, `#X-list`, `#X-reset`, `#X-close`. */
+    /** The panel's id: `typo`, `audio`, `visual`… It produces `#X`, `#X-title`, `#X-list`, `#X-reset`, `#X-close`. */
     id: string;
-    /** O título, JÁ TRADUZIDO. Vai por `textContent`. */
-    titulo: string;
-    /** O `aria-label` da lista, já traduzido — o nome do grupo que a criança ouve ao entrar nele. */
-    rotuloDaLista: string;
-    /** Os rótulos dos dois botões, já traduzidos. */
-    rotuloReset: string;
-    rotuloFechar: string;
     /**
-     * A introdução do painel, já traduzida. Vira o texto de REPOUSO do rodapé, via `data-explain-idle`.
+     * The LIST's id, when it is not `${id}-list`.
      *
-     * ⚠️ É O ÚNICO CAMINHO QUE ESTA CASCA OFERECE PARA UMA INTRODUÇÃO, e é o ponto da issue #62: não há por
-     * onde passar um parágrafo de prosa para o topo do cartão. Ausente = o painel não tem introdução, que é
-     * uma resposta legítima e não uma omissão.
+     * 📏 Exactly one panel diverges: `settings-motion` lives in the `#animation` overlay — with `#animation-reset` and
+     * `#animation-close`, which match — and reads its list at **`#motion-list`**.
+     *
+     * ⚠️ AND THE ANSWER IS NOT TO RENAME. The id a `settings-*` reads is a contract with the markup of whoever already uses
+     * it. An optional field costs one line and breaks no one; the rename would cost the motion panel to whoever already has
+     * markup.
+     */
+    listId?: string;
+    /** The title, ALREADY TRANSLATED. It goes in through `textContent`. */
+    title: string;
+    /** The list's `aria-label`, already translated — the group name the child hears on entering it. */
+    listLabel: string;
+    /** The two buttons' labels, already translated. `closeLabel` is the word for BACK (item 1, ADR-0158). */
+    resetLabel: string;
+    closeLabel: string;
+    /**
+     * The panel's introduction, already translated. It becomes the footer's RESTING text, via `data-explain-idle`.
+     *
+     * ⚠️ IT IS THE ONLY PATH THIS SHELL OFFERS FOR AN INTRODUCTION, which is the point of issue #62: there is no way to
+     * pass a paragraph of prose to the top of the card. Absent = the panel has no introduction, which is a legitimate
+     * answer and not an omission.
      */
-    introducao?: string;
+    intro?: string;
 }
-/** O que a casca devolve: o nó e os ids que ela criou, para o painel não os adivinhar. */
+/**
+ * THE SHELL'S WORDS, without the id — everything that changes when the language changes, and nothing that does not.
+ *
+ * ⚠️ SEPARATE FROM THE `id` ON PURPOSE, the separation `ui/mount-panel` needs: the id is identity and resolves once; the
+ * labels are TRANSLATED TEXT and resolve on every open. A type joining them would make whoever retranslates repeat the
+ * id, and repeating an identity is how it drifts.
+ */
+export type PanelLabels = Omit<PanelShellSpec, 'id'>;
+/** What the shell returns: the node and the ids it created, so the panel does not guess them. */
 export interface PanelShell {
     overlay: HTMLElement;
     card: HTMLElement;
-    lista: HTMLElement;
+    /** The card's `<h2>`. Exposed because whoever retranslates the panel writes into it — see `applyLabels`. */
+    title: HTMLElement;
+    list: HTMLElement;
     reset: HTMLElement;
-    fechar: HTMLElement;
-    /** Os cinco selectores que este painel passa a garantir. É o contrato, agora dito em vez de descoberto. */
+    close: HTMLElement;
+    /** The five selectors this panel guarantees. It is the contract, stated instead of discovered. */
     ids: {
         overlay: string;
         title: string;
-        lista: string;
+        list: string;
         reset: string;
-        fechar: string;
+        close: string;
     };
 }
-/** Os ids que um painel de `id` ocupa. Exportado porque um gate e um consumidor precisam de os nomear. */
-export declare function idsDaCasca(id: string): PanelShell['ids'];
+/** The ids a panel of `id` occupies. Exported because a gate and a consumer need to name them. */
+export declare function shellIds(id: string, customListId?: string): PanelShell['ids'];
+/**
+ * Mounts (or reuses) the shell of panel `spec.id` and returns its parts.
+ *
+ * IDEMPOTENT: if a `#id` already exists, it is reused and the card's content is rebuilt. A panel mounted twice cannot
+ * end up with two veils — and it can be mounted more than once (two cartridges on one page, ADR-0139).
+ */
+export declare function mountShell(ctx: PanelShellCtx, spec: PanelShellSpec): PanelShell;
 /**
- * Monta (ou reaproveita) a casca do painel `spec.id` e devolve as suas partes.
+ * WRITES THE SHELL'S WORDS — separate from construction because they change AFTER it exists.
+ *
+ * 🔴 `initI18n` applies the fallback language synchronously — so the page is never blank — and, if the preferred
+ * language is another, REQUESTS the switch, which is asynchronous. Anything JavaScript builds in that gap captures the
+ * fallback text and nothing rebuilds it; and the language can also change mid-game.
+ *
+ * ⚠️ AND REBUILDING THE SHELL TO FIX THE TITLE DOES NOT WORK. `mountShell` empties the card, and each `ui/settings-*`
+ * wires its `#X-reset` ONCE, at `init` — remounting leaves the reset button in the document with no listener, a dead
+ * button that looks alive (ADR-0106 §5). Writing only the words touches no listener.
  *
- * IDEMPOTENTE: se já existir um `#id`, ele é reutilizado e o conteúdo do cartão é reconstruído. Um painel que
- * a raiz monte duas vezes não pode acabar com dois véus — e a raiz monta mais do que uma vez, porque a
- * contagem de jogadores muda a grade de telas.
+ * IDEMPOTENT: writing the same labels twice is writing the same labels.
  */
-export declare function montarCasca(ctx: PanelShellCtx, spec: PanelShellSpec): PanelShell;
+export declare function applyLabels(shell: PanelShell, r: PanelLabels): void;