@the-inclusionist/engine 9.0.0 → 10.0.0

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

@@ -0,0 +1,374 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/settings-mobility — the per-player MOBILITY panel: the thin DOM-touching render/reflect functions; what a choice IS
+// lives in ./mobility-choices.js. DI via initSettingsMobility(ctx): `$` (DOM selector), `srSay`, `store`
+// (platform/storage shape), `players`/`getNumPlayers` (the live round) and optionally `rebuildCoins` (the game's reaction
+// to Easy Mode).
+//
+// ⚠️ The movement latch setter is the ENGINE's (`setMoveLatch`, ADR-0106 §4, step 1b): being shared by two ENGINE
+// surfaces — this panel and the pause bar's `altmove` icon — is a reason for the engine to own it. The ctx field is
+// OPTIONAL, so whoever injects still rules and whoever does not still gets it.
+// Overlay open/close plumbing (frontOverlay, Escape handling) is the SHARED helper every settings panel uses.
+import { markChanged, markMenuChanged } from './changed-mark.js';
+import { DEFAULTS } from '../core/setting-defaults.js';
+// ⚠️ A DIRECT IMPORT, not one more `ctx` piece: an injected key name is a field a consumer may omit, and omitting it here
+// would make the panel write under a crooked name. The table is stateless (`platform/storage-keys`, ADR-0232), so the
+// import brings names and no storage.
+import { KEYS } from '../platform/storage-keys.js';
+import { writeLatch } from '../input/latch-store.js';
+import { applyLatch, BASE_DA_MARCHA, } from '../input/latch-sync.js';
+import { latchRefusal } from './latch-refusal.js';
+import { clampSelPlayer, anyMobilityActive, onOffLabel, playerTabsHTML, easyAnnouncement, playerPrefix } from './mobility-choices.js';
+import { controlRow, labelRow } from './panel-widgets.js';
+// ---------------------------------------------------------------------------------------------
+// Pure logic (no `document`, testable in node)
+// ---------------------------------------------------------------------------------------------
+/** localStorage key for a player's Modo Fácil flag (== platform/storage.ts's `easy_p{i}` pattern). */
+export function easyKey(i) {
+    // ⚠️ IT DELEGATES, like its siblings: two copies of a name change one at a time, and `platform/storage` makes the keys
+    // functions to stop anyone writing under a crooked name. A gate asserts the three agree with `KEYS`.
+    return KEYS.easyP(i);
+}
+/**
+ * localStorage key of the RUN button's latch, in the LEGACY form (no transport).
+ *
+ * ⚠️ IT DELEGATES to `platform/storage`, so there is one name only.
+ *
+ * ⚠️ AND IT IS THE LEGACY KEY. ADR-0104 §C put the TRANSPORT in the name, because the latch belongs to the device and not
+ * the person; this one is still read to inherit what the child already had, and is not written. The new key is
+ * `latchKey`, in `input/latch-scope`.
+ */
+export function toggleRunKey(i) {
+    return KEYS.toggleRunP(i);
+}
+/** localStorage key of the MOVEMENT latch, per player. It delegates, like the two siblings above. */
+export function toggleMoveKey(i) {
+    return KEYS.toggleMoveP(i);
+}
+/**
+ * SWITCHES A PLAYER'S MOVEMENT LATCH ON OR OFF — the engine does it (ADR-0106 §4).
+ *
+ * ⚠️ Being shared by TWO engine surfaces (this panel and the pause bar's `altmove` icon) is a reason for the engine to
+ * own it, not for the cartridge to keep it — and every step is the engine's: `toggleMove` and `walkDir` are
+ * `PlayerBase` fields, the key is `platform/storage`'s, and `sr.motor.toggleMove*` are engine i18n keys. There is no
+ * game effect left to inject.
+ */
+export function setMoveLatch(ctx, i, on) {
+    const p = ctx.players[i];
+    if (!p)
+        return;
+    // 📌 THE SWITCH-OFF RULE LIVES IN ONE PLACE (issue #127): `applyLatch` sets the value AND stops whoever walks by latch.
+    // It is shared with the edge sync (`input/latch-sync`), which answers the SAME question when the device changes — two
+    // copies of "otherwise the character walks by itself" would drift the day one of them changed.
+    applyLatch(p, on);
+    // ⚠️ BOTH KEYS, AND THE OLD ONE STAYS FOR NOW — the same shape as `p.visual` beside `p.viz` (#104 step 1a), for the same
+    // reason: a cartridge may still READ it through `KEYS.toggleMoveP(i)`. Stopping writing it now would make the child
+    // lose the choice at the next boot — the cost ADR-0113 names.
+    ctx.store.setBool(toggleMoveKey(i), on);
+    // 📌 And the NEW key, when the device is known. `writeLatch` refuses on the four assisted transports, where there is no
+    // choice to store (ADR-0113 clause 3) — and returns `false` so a caller can disable the control with the reason said.
+    // Here the refusal changes nothing else: the in-memory value is still what the rule resolves, and the rule answers
+    // `true` on those four.
+    const transport = ctx.transportInUse ? ctx.transportInUse(i) : null;
+    if (transport)
+        writeLatch((key, isOn) => ctx.store.setBool(key, isOn), BASE_DA_MARCHA, i, transport, on);
+    // 📌 THE ANNOUNCEMENT IS UNCONDITIONAL, unlike `applyLatch`, which returns "changed". The child pressed the icon:
+    // staying silent because the value already was that would leave the button with no answer for whoever listens.
+    const { t } = ctx;
+    ctx.srSay(playerPrefix(t, i, ctx.getNumPlayers()) + t(on ? 'sr.motor.toggleMoveOn' : 'sr.motor.toggleMoveOff'));
+}
+/**
+ * SWITCHES THE RUN LATCH ON OR OFF — `setMoveLatch`'s sibling, and simpler.
+ *
+ * 🎯 THE SAME REASON TO EXIST: every step is the engine's — `toggleRun` is a `PlayerBase` field, the key is
+ * `platform/storage`'s `KEYS.toggleRunP(i)`, and `sr.motor.toggleRun*` are engine i18n keys. **There is no game effect
+ * to inject**, which is why `SettingsMobilityCtx.setToggleRun` is optional: a game that does not supply it still gets a
+ * live run row instead of a dead one.
+ *
+ * ⚠️ AND IT DOES NOT CALL `applyLatch`, unlike its sibling. That one stops whoever walks by latch on switch-off, because
+ * the MOVEMENT latch leaves the character walking by itself; the run latch governs a speed lock, which cannot leave anyone
+ * moving. Copying the line "for symmetry" would touch `walkDir` because of a button that does not.
+ *
+ * 📌 The announcement is UNCONDITIONAL, like its sibling's: the child pressed the button, and staying silent because the
+ * value already was that leaves the control with no answer for whoever listens instead of looking.
+ */
+export function setRunLatch(ctx, i, on) {
+    const p = ctx.players[i];
+    if (!p)
+        return;
+    p.toggleRun = on;
+    ctx.store.setBool(toggleRunKey(i), on);
+    const { t } = ctx;
+    ctx.srSay(playerPrefix(t, i, ctx.getNumPlayers()) + t(on ? 'sr.motor.toggleRunOn' : 'sr.motor.toggleRunOff'));
+}
+/**
+ * MOUNTS THIS PANEL'S INSIDE — the per-seat tabs and the three rows it reaches.
+ *
+ * 🔴 THE CONTRACT WOULD OTHERWISE BE INVISIBLE (the shape `ui/panel-shell` names one level up): this module looks for
+ * `#movement-players`, `#opt-facil`, `#opt-altmove` and `#opt-togglerun`, and nothing in the type says so — so it builds
+ * them, instead of a panel that opens with nothing but a card, a title and a reset button.
+ *
+ * ⚠️ AND IT LIVES HERE, not in the composition root: whoever knows these four ids and each control's shape is this file,
+ * and nobody else. A root writing them would be a root guessing.
+ *
+ * ⚠️ THE THREE ROWS ARE ALWAYS CREATED, the latch row included. Whether it is SEEN is decided at init by `holdsKeys`
+ * (ADR-0115), with `hidden`, which takes the row off the screen AND out of the accessibility tree. Creating it only when
+ * it applies would put the same rule in two places, and the day they diverged the row would appear in a game where it
+ * does nothing.
+ *
+ * 📌 THE ORDER IS THE DECISION, as in every menu of this project (ADR-0044 §2): the tabs first, because they say WHOSE
+ * the next choices are; then Easy Mode, the most sought; and the two latches together, the same idea applied to two
+ * buttons.
+ *
+ * Idempotent: calling it twice reuses the list instead of duplicating it.
+ */
+export function mountMobilityInside(t, ctx, card, list) {
+    if (!ctx.find('#movement-players')) {
+        const abas = ctx.create('div');
+        abas.id = 'movement-players';
+        // Born hidden and empty: `renderMovPlayers()` draws them, because it knows how many seats there are NOW — and the
+        // number changes during the match.
+        abas.hidden = true;
+        card.insertBefore(abas, list);
+    }
+    const rows = [
+        { id: 'opt-facil', label: t('motor.facil'), hint: t('motor.facil.dica') },
+        { id: 'opt-altmove', label: t('motor.altmove'), hint: t('motor.altmove.dica') },
+        { id: 'opt-togglerun', label: t('motor.togglerun'), hint: t('motor.togglerun.dica') },
+    ];
+    for (const spec of rows) {
+        // ⚠️ IT RELABELS INSTEAD OF SKIPPING when the row exists, which is why this function is also called from every
+        // open's `render()`: text captured at boot may be in the fallback language, and the title and the rows would end
+        // up in different languages on the same screen. See `ui/panel-widgets.labelRow`.
+        const existingRow = ctx.find('#' + spec.id);
+        if (existingRow) {
+            const rowNode = existingRow.closest('.ctrl-row');
+            if (rowNode)
+                labelRow(rowNode, spec);
+            continue;
+        }
+        list.appendChild(controlRow(ctx, spec).row);
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// DOM-facing (thin) — requires `document`/injected ctx
+// ---------------------------------------------------------------------------------------------
+export function initSettingsMobility(ctx) {
+    const { t } = ctx;
+    // ⚠️ RESOLVED ONCE: whoever injects rules, whoever does not still gets it — the engine does it itself (`setMoveLatch`).
+    const setToggleMove = ctx.setToggleMove ?? ((i, on) => setMoveLatch(ctx, i, on));
+    // Its sibling, by the same rule and for the same reason — see `setRunLatch`.
+    const setToggleRun = ctx.setToggleRun ?? ((i, on) => setRunLatch(ctx, i, on));
+    // ⚠️ THE WORLD'S REACTION IS THE GAME'S, and its absence is not a dead button: `setEasy` has already written,
+    // persisted and announced before getting here.
+    const rebuildCoins = ctx.rebuildCoins ?? (() => { });
+    let selMovPlayer = 0; // the player selected in the mobility panel
+    const easyModeButton = ctx.$('#opt-facil');
+    const altMoveBtn = ctx.$('#opt-altmove');
+    /**
+     * THE ROW'S ORIGINAL HINT, kept once.
+     *
+     * ⚠️ HERE THE REFUSAL COMES AND GOES: this button is persistent, and the child may put the webcam down and go back to
+     * the keyboard — without keeping the original text, the reason would pile up on the row with every device change.
+     */
+    const altMoveRow = altMoveBtn?.closest('.ctrl-row') ?? null;
+    const altMoveHint = altMoveRow?.querySelector('.opt-hint') ?? null;
+    const originalHint = altMoveHint?.textContent ?? '';
+    /*
+     * ADR-0115 · THE ROW DISAPPEARS IN A GAME THAT HOLDS NOTHING — and disappears for EVERYONE.
+     *
+     * 🔴 `hidden` and not `aria-disabled`: the child who depends on the latch opens this panel to switch it on, and in a
+     * quiz there is nothing to switch on. A control disabled with a reason is still a control that does nothing — and it
+     * still takes a place in keyboard navigation, between two that work.
+     * 📌 Clause 3 of ADR-0113 is the opposite case and stays intact: there the device REQUIRES the latch, the control
+     * exists, and it is `aria-disabled` WITH the reason, reachable so it can be read.
+     * ⚠️ `hidden` and not removal: the row may be the page's own markup, and `hidden` is reversible and idempotent where
+     * removing someone else's markup is neither.
+     */
+    if (!ctx.holdsKeys && altMoveRow)
+        altMoveRow.hidden = true;
+    /** THIS player's refusal now, or `null`. Recomputed on every reflect: the device in use changes. */
+    function refusalFor(i) {
+        return ctx.transportInUse ? latchRefusal(ctx.transportInUse(i)) : null;
+    }
+    const toggleRunBtn = ctx.$('#opt-togglerun');
+    // the bar lights up if ANY player uses Easy Mode or a latch
+    function reflectMovementBtn() {
+        const b = ctx.$('#opt-movement');
+        if (b)
+            b.classList.toggle('is-on', anyMobilityActive(ctx.players));
+        refreshMarks();
+    }
+    /**
+     * The left-the-default mark (ADR-0029). Hung on the reflect that ALREADY runs on every change of the two controls,
+     * because a mark that needs its own call is a mark someone will forget — and a wrong mark sends the child to undo what
+     * they never touched.
+     *
+     * The scope follows this menu's reset: the PREFERENCES. The input methods (eyes, mapping) stay out here too — not
+     * because they cannot change, but because their default does not live in DEFAULTS, and marking without a single source
+     * of "default" would invent a second opinion on it.
+     */
+    function refreshMarks() {
+        const easy = ctx.players.some((p) => !!p.easy) !== DEFAULTS.easy;
+        const alt = ctx.players.some((p) => !!p.toggleMove) !== DEFAULTS.toggleMove;
+        // THE RUN LATCH ASKS DIFFERENTLY, because it SWITCHES ON BY ITSELF on the touch controls. Marking by STATE would
+        // light the mark for everyone playing on a tablet, with nobody touching anything — and a mark always lit means
+        // nothing.
+        //
+        // So what marks is the STORED CHOICE. A saved value means someone touched that control; the automatic switch-on
+        // saves nothing, so it does not mark.
+        const anyRunToggleChosen = ctx.players.some((p, i) => ctx.store.get(toggleRunKey(i)) != null && !!p.toggleRun !== DEFAULTS.toggleRun);
+        markChanged(t, easyModeButton?.closest('.ctrl-row') ?? null, easy);
+        markChanged(t, altMoveBtn?.closest('.ctrl-row') ?? null, alt);
+        markChanged(t, toggleRunBtn?.closest('.ctrl-row') ?? null, anyRunToggleChosen);
+        markMenuChanged(t, ctx.$('[data-act="motora"]'), [easy, alt, anyRunToggleChosen]);
+    }
+    function drawEasy() {
+        const p = ctx.players[selMovPlayer];
+        const on = !!(p && p.easy);
+        if (easyModeButton) {
+            easyModeButton.classList.toggle('is-on', on);
+            easyModeButton.setAttribute('aria-pressed', String(on));
+            easyModeButton.textContent = onOffLabel(t, on);
+        }
+        reflectMovementBtn();
+    }
+    function reflectToggleRun() {
+        const p = ctx.players[selMovPlayer];
+        const on = !!(p && p.toggleRun);
+        if (toggleRunBtn) {
+            toggleRunBtn.classList.toggle('is-on', on);
+            toggleRunBtn.setAttribute('aria-pressed', String(on));
+            toggleRunBtn.textContent = onOffLabel(t, on);
+        }
+        reflectMovementBtn();
+    }
+    function reflectAltMove() {
+        const p = ctx.players[selMovPlayer];
+        const on = !!(p && p.toggleMove);
+        if (altMoveBtn) {
+            altMoveBtn.classList.toggle('is-on', on);
+            altMoveBtn.setAttribute('aria-pressed', String(on));
+            altMoveBtn.textContent = onOffLabel(t, on);
+            /*
+             * ⚠️ CLAUSE 3 OF ADR-0113 ON SCREEN: where the latch is required, the control does NOT disappear — it is
+             * `aria-disabled` and the reason goes into the hint, which the shell (`ui/settings-panel.fillExplain`) moves to the
+             * footer. Disappearing would teach that the thing does not exist; leaving it active would make the child press it
+             * and not understand why nothing changed.
+             *
+             * 📌 And `aria-disabled`, not `disabled`: a really disabled button LEAVES the tab order, and a keyboard user could no
+             * longer reach it — so could no longer READ the reason. The same choice #128 names as a defect when made the other
+             * way (a CSS class only, no `aria`).
+             */
+            const refusal = refusalFor(selMovPlayer);
+            if (refusal)
+                altMoveBtn.setAttribute('aria-disabled', 'true');
+            else
+                altMoveBtn.removeAttribute('aria-disabled');
+            if (altMoveHint)
+                altMoveHint.textContent = refusal ? `${originalHint} ${t(refusal.key)}`.trim() : originalHint;
+        }
+        reflectMovementBtn();
+    }
+    function setEasy(i, on) {
+        const p = ctx.players[i];
+        if (!p)
+            return;
+        p.easy = on;
+        ctx.store.setBool(easyKey(i), on);
+        drawEasy();
+        rebuildCoins();
+        ctx.srSay(easyAnnouncement(t, i, ctx.getNumPlayers(), on));
+    }
+    function renderMovPlayers() {
+        const tabs = ctx.$('#movement-players');
+        if (!tabs)
+            return;
+        const numPlayers = ctx.getNumPlayers();
+        selMovPlayer = clampSelPlayer(selMovPlayer, numPlayers);
+        tabs.hidden = true; // no tabs — each player edits only their own (scope = the pause actor)
+        tabs.innerHTML = playerTabsHTML(numPlayers, selMovPlayer);
+        tabs.querySelectorAll('button[data-mp]').forEach((b) => {
+            b.addEventListener('click', () => {
+                selMovPlayer = Number(b.dataset.mp);
+                renderMovPlayers();
+                drawEasy();
+                reflectAltMove();
+            });
+        });
+        // The prose goes back to the footer after the rows are rebuilt (CLAUDE.md §4, #109).
+        ctx.fillExplain?.(ctx.$('#movement .overlay__card'));
+    }
+    /**
+     * The panel's four buttons — easy mode, the move toggle, the run toggle and the reset — wired where the page carries
+     * them. The engine builds none of them here; a page that lacks one simply has that row missing.
+     */
+    function wireButtons() {
+        if (easyModeButton) {
+            easyModeButton.addEventListener('click', () => setEasy(selMovPlayer, !ctx.players[selMovPlayer].easy));
+        }
+        if (altMoveBtn) {
+            altMoveBtn.addEventListener('click', () => {
+                /*
+                 * ⚠️ REFUSE BY SAYING, NOT IN SILENCE. The listener is wired once, and a mute `return` would accept the click and
+                 * ignore it — the other half of what ADR-0076 forbids. So the refusal SPEAKS: whoever pressed learns why, even
+                 * without seeing the hint.
+                 */
+                const refusal = refusalFor(selMovPlayer);
+                if (refusal) {
+                    ctx.srSay(t(refusal.key));
+                    return;
+                }
+                setToggleMove(selMovPlayer, !ctx.players[selMovPlayer].toggleMove);
+                reflectAltMove();
+            });
+        }
+        if (toggleRunBtn) {
+            toggleRunBtn.addEventListener('click', () => {
+                setToggleRun(selMovPlayer, !ctx.players[selMovPlayer].toggleRun);
+                reflectToggleRun();
+            });
+        }
+        // ---- reset THIS menu's defaults (ADR-0028) ----
+        //
+        // The reach here is SMALLER than the screen, on purpose. The mobility panel also hosts the input methods (key and
+        // controller mapping); the reset returns the PREFERENCES and does not touch the INPUT METHOD, for a reason worth more
+        // than symmetry:
+        //
+        //   A RESET MAY ONLY UNDO WHAT IT CAN ALSO REDO.
+        //
+        // Whoever remapped the keys did it because they reach only some: returning the factory map returns keys their hand
+        // does not reach. That mapping has its own reset (#ctrl-reset), where the choice is explicit and not a side effect.
+        //
+        // That is why the announcement SAYS what was left out: a button that restores less than its name promises has to say
+        // so aloud, or the child concludes it did not work.
+        const resetBtn = ctx.$('#movement-reset');
+        if (resetBtn)
+            resetBtn.addEventListener('click', () => {
+                ctx.players.forEach((p, i) => {
+                    if (p.easy)
+                        setEasy(i, false);
+                    if (p.toggleMove)
+                        setToggleMove(i, false);
+                    if (p.toggleRun)
+                        setToggleRun(i, false);
+                });
+                drawEasy();
+                reflectAltMove();
+                reflectToggleRun();
+                ctx.srSay(t('sr.motor.reset'));
+            });
+    }
+    wireButtons();
+    drawEasy();
+    reflectAltMove();
+    reflectToggleRun();
+    return {
+        renderMovPlayers,
+        reflectEasy: drawEasy,
+        reflectAltMove,
+        reflectToggleRun,
+        setEasy,
+        setSelPlayer: (i) => { selMovPlayer = i; },
+        getSelPlayer: () => selMovPlayer,
+    };
+}

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

@@ -1,4 +1,8 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import { type Crt } from '../render/crt.js';
+import { type MediaQuery } from '../core/setting-defaults.js';
+import type { Translate } from '../core/i18n.js';
+import type { Store } from '../platform/storage.js';
 import type { MotionSceneKey as ChaveDeCenaLeaf, MotionCharProp as PropDoPersonagemLeaf, MotionCharDef as DefDoPersonagemLeaf, MotionPlayer as JogadorDeMovimentoLeaf, MotionSceneFlags as BandeirasDeCenaLeaf } from './motion-scene.js';
 export type MotionSceneKey = ChaveDeCenaLeaf;
 export type MotionCharProp = PropDoPersonagemLeaf;
@@ -6,96 +10,113 @@ export type MotionCharDef = DefDoPersonagemLeaf;
 export type MotionPlayer = JogadorDeMovimentoLeaf;
 export type MotionSceneFlags = BandeirasDeCenaLeaf;
 export interface SettingsMotionCtx {
-    /** Quantos jogadores/telas. Estado de RODADA (ADR-0038): vem da instância que a raiz possui.
-     *  Era `numPlayers`, um `let` de `core/state` importado como binding vivo — e um `let` de módulo
-     *  é compartilhado por qualquer segundo jogo que a mesma página carregue (D13 do `demos`). */
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    /** How many players/screens. ROUND state (ADR-0038): it comes from the instance the root owns — a module `let` would
+     *  be shared by any second game the same page loads. */
     getNumPlayers: () => number;
-    /** Os jogadores. Estado de RODADA, pelo mesmo motivo. `readonly unknown[]` porque cada consumidor
-     *  estreita para a SUA fatia — o tipo real é do jogo, não da engine (ADR-0033). */
+    /** The players. ROUND state, for the same reason. `readonly unknown[]` because each consumer narrows to ITS slice —
+     *  the real type is the game's, not the engine's (ADR-0033). */
     getPlayers: () => readonly unknown[];
-    /** Seletor DOM (ui/dom.ts `$`). */
+    /** DOM selector (ui/dom.ts `$`). */
     $: <T extends Element = Element>(sel: string) => T | null;
-    /** Anúncio "polite" para leitor de tela (core/a11y-sr.ts). */
+    /** "Polite" screen-reader announcement (core/a11y-sr.ts). */
     srSay: (text: string) => void;
-    /** Persistência (platform/storage.ts) — só o necessário aqui: gravar as flags por jogador. */
-    store: {
-        setBool: (key: string, on: boolean) => void;
-    };
-    /** Empilha o overlay (z-index) + liga o rodapé de explicação — compartilhado por todos os painéis "Sensibilidade". */
+    /**
+     * The page's store (ADR-0232, issue #207) — only what is needed here: storing the per-player flags, and reading and
+     * writing the scene flags when the host does not share its own `rm`.
+     */
+    store: Pick<Store, 'setBool' | 'getJSON' | 'setJSON'>;
+    /**
+     * The browser's media query (`win.matchMedia`), asked for `prefers-reduced-motion` at every mark and every reset — the
+     * default follows the operating system NOW, not at boot. MANDATORY and injected (ADR-0232, ADR-0227): this module
+     * reaches no global, and an optional port would let a host forget it and turn the animation back on at the reset.
+     */
+    matchMedia: MediaQuery;
+    /**
+     * The root's CRT (`render/crt`'s `createCrt`, ADR-0232 D4): the live config the three CRT rows read and write, and its
+     * `apply`. REQUIRED: the panel used to reach the page's one CRT by import, and a second root would have toggled the
+     * first root's scanlines.
+     */
+    crt: Pick<Crt, 'cfg' | 'apply'>;
+    /** Stacks the overlay (z-index) + wires the explanation footer — shared by every settings panel. */
     frontOverlay: (el: HTMLElement | null) => void;
-    /** Devolve o foco a quem abriu o diálogo (ui/settings-panel `restoreFocus`). Injetado, e não um `#opt-*`
-     *  fixo: o id que este módulo focava não existe no documento, então fechar deixava o foco no `<body>`. */
+    /** Returns focus to whoever opened the dialog (ui/settings-panel `restoreFocus`). Injected, not a fixed `#opt-*`: that
+     *  id does not exist in the document, so closing would leave focus on `<body>`. */
     restoreFocus?: (id: string) => boolean;
-    /** Reflete on/off num botão (classe is-on + aria-pressed) — helper genérico usado por vários botões-mestre. */
+    /** Reflects on/off on a button (is-on class + aria-pressed) — a generic helper used by several master buttons. */
     toggleBtn: (el: HTMLElement, on: boolean) => void;
-    /** Movimento reduzido de CENA (parallax/decor/items/particles) — objeto VIVO, mutado in-place. */
+    /** SCENE reduced motion (parallax/decor/items/particles) — a LIVE object, mutated in place. */
     rm?: MotionSceneFlags;
-    /** Persiste `rm` (localStorage 'inclusionist.reducedmotion.v1'). */
+    /** Persists `rm` (localStorage 'inclusionist.reducedmotion.v1'). */
     saveRM?: () => void;
-    /** As 4 chaves de cena — a MESMA array que applyCalm() itera. */
+    /** The 4 scene keys. */
     rmKeys?: readonly MotionSceneKey[];
-    /** Os 3 alvos de movimento reduzido do PERSONAGEM — a MESMA array que applyCalm() itera. */
+    /** The 3 CHARACTER reduced-motion targets. */
     rmChar?: readonly MotionCharDef[];
     /**
-     * Move a prosa das linhas para o rodapé (`ui/settings-panel` → `fillExplain`). Chamado a CADA render.
+     * DOES THIS GAME HAVE A CHARACTER THAT WALKS, BREATHES OR PLAYS AROUND? (ADR-0153, `reducedCharacterMotion`.)
      *
-     * ⚠️ NÃO É OPCIONAL POR ELEGÂNCIA: `fillExplain` roda uma vez quando o overlay é frontalizado e move o
-     * `.opt-hint` de dentro de cada linha para o rodapé. Este painel RECONSTRÓI as linhas, e as linhas novas
-     * voltam com a prosa lá dentro — então a explicação aparece duas vezes, no rodapé e sob o rótulo, a
-     * partir do primeiro clique. O `CLAUDE.md` §4 regista exatamente isto, e a issue #109 já o consertou
-     * uma vez noutros painéis.
+     * 🔴 Without it the character section would mount in EVERY game — three switches to stop the walk, the breath and the
+     * flourishes of a character a board game does not have. It is ADR-0145's subjectless button. `false` removes the
+     * section, and its rows stop counting for the master button and the reset.
      *
-     * Opcional na assinatura porque um consumidor pode montar o painel sem a casca (um teste, o segundo
-     * consumidor): sem casca não há rodapé para duplicar.
+     * ⚠️ OPTIONAL, defaulting to `true`: whoever mounts this panel outside `createGame` is unchanged.
+     */
+    hasCharacter?: () => boolean;
+    /**
+     * The GAME's word for its character (ADR-0153: what applies carries the game's word), the section's title. Optional:
+     * absent, the section keeps the engine's own title, as for a panel mounted outside `createGame`.
+     */
+    characterLabel?: () => string | null;
+    /**
+     * Moves the rows' prose to the footer (`ui/settings-panel` → `fillExplain`). Called on EVERY render.
+     *
+     * ⚠️ Relabelling a row puts its `.opt-hint` back inside it — so without this call the explanation appears twice, in
+     * the footer and under the label, from the first click. `CLAUDE.md` §4 records exactly this (issue #109).
+     *
+     * Optional in the signature because a consumer can mount the panel without the shell (a test): without the shell
+     * there is no footer to duplicate.
      */
     fillExplain?: (card: HTMLElement | null) => void;
 }
-/**
- * Alvo → CHAVE i18n do rótulo. CHAVES, e não texto, pelo motivo de sempre: uma tabela de `const` com texto
- * resolve UMA vez, no import, e fica congelada no idioma do boot.
- *
- * E é UMA tabela onde eram DUAS. A nota anterior dizia que `walk/breath/flavor` ficavam "redundantes com
- * rmChar[].lbl" e que não haviam sido podados "por fidelidade de porte" — havia uma terceira cópia, morta, no
- * main.js. Três tabelas dos mesmos rótulos, sem nada ligando as três: mudar um rótulo pedia três edições e
- * esquecer uma era silencioso. Agora `rmChar[].lbl` guarda a chave DESTA tabela, e a do main.js foi apagada.
- */
-export declare const RM_LABEL: Record<string, string>;
-export declare const RM_SOON: ReadonlySet<MotionSceneKey>;
-/** selAnimPlayer nunca aponta pra fora do nº de telas atual. */
-export declare function clampSelectedPlayer(selected: number, total: number): number;
-/** Uma linha de switch "Animado/Congelado" (usada tanto para o personagem quanto para a cena). */
-export declare function motionRowHtml(label: string, frozen: boolean, attr: string, soon: boolean): string;
-/** Linhas "Personagem" (por jogador selecionado). */
-export declare function buildCharRowsHtml(rmChar: readonly MotionCharDef[], player: MotionPlayer | undefined): string;
-/** Linhas "Cena" (globais, valem para todos os jogadores). */
-export declare function buildSceneRowsHtml(rmKeys: readonly MotionSceneKey[], rm: MotionSceneFlags, labels: Record<string, string>, soon: ReadonlySet<MotionSceneKey>): string;
-/** Toggle liga/desliga da estética CRT (scanlines/vinheta). */
-export declare function crtToggleRowHtml(label: string, key: string, on: boolean): string;
-/** Cantos CRT: 3 níveis (0=quadrado · 1=pequeno · 2=grande). */
-export declare function crtRoundRowHtml(label: string, round: number): string;
-/** true quando TUDO (cena + personagem selecionado) já está com movimento reduzido LIGADO, isto é,
- *  congelado — nome fiel ao `rm[k]`/`player[prop]` que representam "reduzido", não "animado". Controla
- *  se o botão-mestre oferece "Retomar" (true) ou "Parar" (false) — mesma variável `allOn` do game.js
- *  original, aqui renomeada por clareza (o valor/comportamento não muda). */
-export declare function allMotionFrozen(rmKeys: readonly MotionSceneKey[], rm: MotionSceneFlags, rmChar: readonly MotionCharDef[], player: MotionPlayer | undefined): boolean;
-/** allFrozen=true (tudo já congelado) → oferece "Retomar"; caso contrário → oferece "Parar". */
-export declare function motionMasterLabel(allFrozen: boolean): string;
-/** `label` chega JÁ TRADUZIDO; o que era concatenação (' congelado.') virou moldura com `{alvo}` — é o que
- *  permite a uma língua pôr o estado ANTES do alvo, coisa que uma concatenação não deixa. */
-export declare function sceneMotionAnnouncement(label: string, frozen: boolean): string;
-export declare function crtToggleAnnouncement(label: string, on: boolean): string;
-export declare function crtLevelLabel(level: number): string;
-export declare function crtRoundAnnouncement(label: string, level: number): string;
-/** `nowFrozen` = o NOVO valor de rm[k]/player[prop] aplicado pelo botão-mestre (true = acabou de congelar
- *  tudo; false = acabou de descongelar/retomar tudo) — mesma variável `v` do game.js original. */
-export declare function stopResumeAllAnnouncement(nowFrozen: boolean): string;
-export declare function getSelectedPlayer(): number;
-/** Chamado de fora (ex.: o atalho "anim" do menu de pausa) antes de open(). */
-export declare function setSelectedPlayer(i: number): void;
-/** Espelha `animationOpen` do game.js — só LIDO por quem despacha Escape entre os diálogos abertos. */
+/** What mounting needs to know, already translated — the kit does not decide language, it builds shape. */
+export interface MotionInsideSpec {
+    /** The character section's title, or `null` when this game has no character (ADR-0153). */
+    readonly charTitle: string | null;
+    /** ⚠️ The character's tag is DIFFERENT, not by oversight: its rows hold per PLAYER, the other two sections' hold for
+     *  everyone. A single tag would say the same thing about different things. */
+    readonly charTag: string;
+    readonly charRows: readonly {
+        readonly prop: string;
+        readonly label: string;
+    }[];
+    readonly sceneTitle: string;
+    readonly sceneRows: readonly {
+        readonly key: string;
+        readonly label: string;
+    }[];
+    readonly crtTitle: string;
+    /** The for-everyone tag, shared by the scene and CRT sections. */
+    readonly allTag: string;
+    readonly crtToggles: readonly {
+        readonly key: string;
+        readonly label: string;
+    }[];
+    /** The corners' name and positions, for the steps control (ADR-0151). */
+    readonly roundSpec: () => {
+        readonly label: string;
+        readonly values: readonly string[];
+        readonly current: number;
+    };
+}
 export interface SettingsMotionApi {
     render: () => void;
     open: () => void;
     close: () => void;
+    /** The player whose character rows the panel edits. */
+    selectedPlayer: () => number;
+    /** Chooses that player — called from outside (e.g. the pause menu's "anim" entry) before `open()`. */
+    setSelectedPlayer: (i: number) => void;
 }
 export declare function initSettingsMotion(ctx: SettingsMotionCtx): SettingsMotionApi;