@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -1,128 +1,160 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/settings-motion.ts — "Sensibilidade visual" → painel Movimento (#animation overlay): reduce-motion (WCAG
-// 2.3.3 + Pause/Stop/Hide 2.2.2) por PERSONAGEM (andar/respirar/gracinhas) e por CENA (parallax/decor/itens/
-// partículas), o botão-mestre "Parar/Retomar todas as animações", a seleção de jogador (selAnimPlayer) e a
-// estética CRT (scanlines/vinheta/cantos) — que também mora nesta MESMA tela no game.js original (renderMotion
-// escreve os dois blocos no mesmo #motion-list), por isso vem junto. Lógica PURA (rótulos, HTML, allMotionFrozen,
-// anúncios) separada do DOM. INJETADO via initSettingsMotion(ctx): $ (seletor), srSay, store (persistência),
-// frontOverlay/toggleBtn (helpers compartilhados com os painéis irmãos: visual/audio/typo/empathy/controls/
-// motor), e rm/saveRM/RM_KEYS/RM_CHAR (estado de movimento reduzido — fica em game.js porque applyCalm(), o
-// modo TEA, também os usa; não é exclusivo deste painel). `players`/`numPlayers` (core/state.ts) e CRT/applyCrt
-// (render/crt.ts, já extraído) são importados DIRETO — são módulos-folha, não game.js. A API de render/fx.ts
-// NÃO é referenciada aqui: renderMotion() nunca leu/escreveu JUICE (só o painel ?debug o faz) — ver nota no
-// retorno da extração antes de assumir que falta wiring.
+// ui/settings-motion.ts — the Motion panel (#animation overlay): reduced motion (WCAG 2.3.3 + Pause/Stop/Hide 2.2.2) per
+// CHARACTER (walk/breath/flavour) and per SCENE (parallax/decor/items/particles), the stop/resume-all master button, the
+// player selection and the CRT look (scanlines/vignette/corners), which lives on the SAME screen. What a choice IS lives in
+// ./motion-choices.js. INJECTED via initSettingsMotion(ctx): $ (selector), srSay, store (persistence), matchMedia (the
+// operating system's reduced-motion answer, ADR-0232), frontOverlay/toggleBtn (helpers shared with the sibling panels),
+// the root's CRT (`crt`, ADR-0232 D4), and optionally rm/saveRM/rmKeys/rmChar (reduced-motion state, which a cartridge may
+// share by reference). Only the factory default (`CRT_DEFAULT`, a frozen constant) is imported from render/crt.ts.
 import { toggleLabel, toggleAria } from './dom.js';
-import { CRT, CRT_DEFAULT, applyCrt } from '../render/crt.js';
-import { defaultReducedMotion } from '../core/state.js';
+import { CRT_DEFAULT } from '../render/crt.js';
+import { defaultReducedMotion } from '../core/setting-defaults.js';
 import { markChanged, markMenuChanged } from './changed-mark.js';
-import { t } from '../core/i18n.js';
-import { CHAVES_DE_CENA, ANIMACOES_DO_PERSONAGEM, lerCenaGuardada, guardarCena } from './motion-scene.js';
-/**
- * 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.
+import { mountSteps, updateSteps, nextStep, controlRow, labelRow, sectionHeader } from './panel-widgets.js';
+import { SCENE_KEYS, CHARACTER_ANIMATIONS, readStoredScene, storeScene } from './motion-scene.js';
+/*
+ * 📌 THE PURE HALF LIVES IN `ui/motion-choices` (ADR-0221), and the SUITE pointed at the seam:
+ * `tests/settings-motion.node.test.js` exercises exactly these names, and the node project mounts no document.
  *
- * 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.
+ * ⚠️ NO ALIAS: a re-export would keep alive a published path nothing in here uses — surface with no consumer
+ * (issue #204).
+ */
+import { RM_LABEL, CRT_LBL, CRT_ROUND_LEVELS, clampSelectedPlayer, allMotionFrozen, motionMasterLabel, sceneMotionAnnouncement, crtToggleAnnouncement, crtLevelLabel, crtRoundAnnouncement, stopResumeAllAnnouncement, } from './motion-choices.js';
+/*
+ * 🎯 NO "SOON" MECHANISM: it had no subject — no path let a cartridge supply a coming-soon row, so the only thing
+ * keeping it alive would be tests. The `ui.soon` key stays in the three dictionaries, because the no-parentheses label
+ * gate still reads it.
  */
-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',
-};
-// Alvos de cena "em breve" (hoje nenhum — os 4 já agem).
-export const RM_SOON = new Set([]);
-/** Cabeçalho de seção, com a etiqueta "vale para todos os jogadores".
- *
- *  A etiqueta estava escrita à mão em cada `<h3>` e ia ser repetida pela quarta vez quando a seção nova chegou.
- *  Reunida num ponto só, ela pôde finalmente passar por `t()` — e foi a seção nova que tornou isso urgente: com
- *  o cabeçalho traduzido ao lado de uma etiqueta em português cru, a mistura aparecia na mesma linha da tela.
- *  Os títulos das outras três seções continuam crus; é dívida anterior a esta mudança, contada pelo gate. */
-const secao = (titulo) => `<h3 class="panel-sub">${titulo} <span class="panel-sub__tag">${t('rm.sec.all')}</span></h3>`;
-const CRT_LBL = { scan: 'rm.crt.scan', vig: 'rm.crt.vig', round: 'rm.crt.round' }; // CHAVES i18n (ver RM_LABEL)
-const CRT_ROUND_LEVELS = ['desligado', 'pequeno', 'grande'];
 // ---------------------------------------------------------------------------------------------------------
-// Lógica PURA — testável em node, sem `document`.
+// PURE logic — testable in node, no `document`.
 // ---------------------------------------------------------------------------------------------------------
-/** selAnimPlayer nunca aponta pra fora do nº de telas atual. */
-export function clampSelectedPlayer(selected, total) {
-    return selected >= total ? 0 : selected;
-}
-/** Uma linha de switch "Animado/Congelado" (usada tanto para o personagem quanto para a cena). */
-export function motionRowHtml(label, frozen, attr, soon) {
-    const on = !frozen;
-    const soonTag = soon ? ' <em style="opacity:.7">(em breve)</em>' : '';
-    const cls = 'mode-btn switch' + (on ? ' is-on' : '');
-    const btnText = on ? '▶ Animado' : '❄ Congelado';
-    const state = on ? 'animação ligada' : 'animação congelada';
-    return `<div class="ctrl-row"><span>${label}${soonTag}</span><button class="${cls}" ${attr} type="button" aria-pressed="${on}" aria-label="${label}: ${state}">${btnText}</button></div>`;
-}
-/** Linhas "Personagem" (por jogador selecionado). */
-export function buildCharRowsHtml(rmChar, player) {
-    return rmChar.map((c) => motionRowHtml(t(c.lbl), !!(player && player[c.prop]), `data-rmc="${c.prop}"`, false)).join('');
-}
-/** Linhas "Cena" (globais, valem para todos os jogadores). */
-export function buildSceneRowsHtml(rmKeys, rm, labels, soon) {
-    return rmKeys.map((k) => motionRowHtml(t(labels[k]), !!rm[k], `data-rm="${k}"`, soon.has(k))).join('');
-}
-/** Toggle liga/desliga da estética CRT (scanlines/vinheta). */
-export function crtToggleRowHtml(label, key, on) {
-    const cls = 'mode-btn switch' + (on ? ' is-on' : '');
-    return `<div class="ctrl-row"><span>${label}</span><button class="${cls}" data-crt-tgl="${key}" type="button" aria-pressed="${on}" aria-label="${toggleAria(label, on)}">${toggleLabel(on)}</button></div>`;
-}
-/** Cantos CRT: 3 níveis (0=quadrado · 1=pequeno · 2=grande). */
-export function crtRoundRowHtml(label, round) {
-    const opt = (v, text) => `<option value="${v}"${round === v ? ' selected' : ''}>${text}</option>`;
-    return `<div class="ctrl-row"><span>${label}</span><select class="vol" data-crt="round" aria-label="${label}">${opt(0, 'Desligado (quadrado)')}${opt(1, 'Pequeno')}${opt(2, 'Grande')}</select></div>`;
-}
-/** 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 function allMotionFrozen(rmKeys, rm, rmChar, player) {
-    return rmKeys.every((k) => rm[k]) && rmChar.every((c) => !!(player && player[c.prop]));
-}
-/** allFrozen=true (tudo já congelado) → oferece "Retomar"; caso contrário → oferece "Parar". */
-export function motionMasterLabel(allFrozen) {
-    return allFrozen ? '▶ Retomar todas as animações' : '⏸ Parar todas as animações';
-}
-/** `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 function sceneMotionAnnouncement(label, frozen) {
-    return t(frozen ? 'sr.rm.frozen' : 'sr.rm.animated', { alvo: label });
-}
-export function crtToggleAnnouncement(label, on) {
-    return t(on ? 'sr.crt.on' : 'sr.crt.off', { efeito: label });
-}
-export function crtLevelLabel(level) {
-    return CRT_ROUND_LEVELS[level];
+/**
+ * The NAME of each part of this inside, which is what mounting reconciles by.
+ *
+ * 📌 A key and not a position: the character rows appear and disappear with the cartridge (ADR-0153), so mounting has to
+ * know WHICH row is which to relabel the one that stayed and remove the one that lost its subject.
+ */
+const partOfChar = (prop) => `char:${prop}`;
+const partOfScene = (key) => `scene:${key}`;
+const partOfCrt = (key) => `crt:${key}`;
+/**
+ * Mounts this panel's inside and reconciles it afterwards — creates what is missing, rewrites what stayed, removes what
+ * lost its subject. It NEVER moves a node that already exists.
+ *
+ * 🔴 Rebuilding costs the child their place: with the cursor on the rounded corners, a click on the neighbouring row
+ * would destroy the control and drop focus on `<body>`. ⚠️ And moving also blurs, which is why this function INSERTS at
+ * the right position instead of appending and reordering: a node that changes parent is removed and re-added, and the
+ * browser takes its focus away on removal.
+ */
+function mountMotionInside(ctx, list, spec) {
+    reconcile(list, motionParts(ctx, spec));
 }
-export function crtRoundAnnouncement(label, level) {
-    return t('sr.crt.round', { efeito: label, nivel: crtLevelLabel(level) });
+/**
+ * What this inside HAS, in order — a different question from how the document gets there.
+ *
+ * ⚠️ Separate from `reconcile` so each stays under McCabe's ceiling of 10 (ADR-0221): each is a sentence with a name.
+ */
+function motionParts(ctx, spec) {
+    const sectionPart = (key, title, tag, rows) => (rows === 0 ? null : {
+        key,
+        build: () => sectionHeader(ctx, title, tag, rows) ?? ctx.create('h3'),
+        write: (el) => {
+            el.textContent = title + ' ';
+            const mark = ctx.create('span');
+            mark.className = 'panel-sub__tag';
+            mark.textContent = tag;
+            el.appendChild(mark);
+        },
+    });
+    const switchPart = (key, id, label, mark) => ({
+        key,
+        build: () => {
+            const { row: newRow, control: switchButton } = controlRow(ctx, { id, label: label, ariaLabel: label });
+            switchButton.setAttribute(mark[0], mark[1]);
+            return newRow;
+        },
+        // ⚠️ ONLY THE WORDS. The state (class, `aria-pressed`, the button's text) is written by the panel's reflect, which
+        // knows the value — writing it here would give two answers to the same question.
+        write: (el) => labelRow(el, { id, label: label, ariaLabel: label }),
+    });
+    const parts = [];
+    const charHeader = sectionPart('sec:char', spec.charTitle ?? '', spec.charTag, spec.charTitle ? spec.charRows.length : 0);
+    if (charHeader)
+        parts.push(charHeader);
+    for (const r of spec.charRows)
+        parts.push(switchPart(partOfChar(r.prop), `motion-char-${r.prop}`, r.label, ['data-rmc', r.prop]));
+    const sceneHeader = sectionPart('sec:scene', spec.sceneTitle, spec.allTag, spec.sceneRows.length);
+    if (sceneHeader)
+        parts.push(sceneHeader);
+    for (const r of spec.sceneRows)
+        parts.push(switchPart(partOfScene(r.key), `motion-scene-${r.key}`, r.label, ['data-rm', r.key]));
+    const crtHeader = sectionPart('sec:crt', spec.crtTitle, spec.allTag, spec.crtToggles.length + 1);
+    if (crtHeader)
+        parts.push(crtHeader);
+    for (const r of spec.crtToggles)
+        parts.push(switchPart(partOfCrt(r.key), `crt-${r.key}`, r.label, ['data-crt-tgl', r.key]));
+    parts.push({
+        key: partOfCrt('round'),
+        build: () => {
+            // ⚠️ NO SEPARATE LABEL (ADR-0130 errata): the steps control writes «◀ Cantos arredondados: pequeno ▶» across the
+            // whole row, and a label beside it would say the name twice.
+            const row = ctx.create('div');
+            row.className = 'ctrl-row ctrl-row--passos';
+            const steps = mountSteps(ctx, spec.roundSpec());
+            steps.setAttribute('data-crt', 'round');
+            row.appendChild(steps);
+            return row;
+        },
+        write: (el) => {
+            const steps = el.querySelector('[data-passos]');
+            if (steps)
+                updateSteps(steps, spec.roundSpec());
+        },
+    });
+    return parts;
 }
-/** `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 function stopResumeAllAnnouncement(nowFrozen) {
-    return t(nowFrozen ? 'sr.rm.allStopped' : 'sr.rm.allResumed');
+/**
+ * The document brought in line with the list: creates what is missing AT THE RIGHT POSITION, rewrites what stayed,
+ * removes what is no longer asked for.
+ *
+ * ⚠️ IT NEVER MOVES A NODE THAT ALREADY EXISTS, and not for thrift: a node that changes parent is removed and re-added,
+ * and the browser takes its focus away on removal — the defect building nodes exists to avoid, through another door.
+ */
+function reconcile(list, parts) {
+    let previous = null;
+    for (const part of parts) {
+        let el = list.querySelector(`[data-motion-part="${part.key}"]`);
+        if (!el) {
+            el = part.build();
+            el.dataset.motionPart = part.key;
+            list.insertBefore(el, previous ? previous.nextSibling : list.firstChild);
+        }
+        part.write(el);
+        previous = el;
+    }
+    const keep = new Set(parts.map((p) => p.key));
+    for (const el of [...list.querySelectorAll('[data-motion-part]')]) {
+        if (!keep.has(el.dataset.motionPart ?? ''))
+            el.remove();
+    }
 }
-// ---------------------------------------------------------------------------------------------------------
-// Estado do módulo — equivalente a `let selAnimPlayer=0` + `animationOpen=false` do game.js.
-// ---------------------------------------------------------------------------------------------------------
-let selectedPlayer = 0;
-export function getSelectedPlayer() { return selectedPlayer; }
-/** Chamado de fora (ex.: o atalho "anim" do menu de pausa) antes de open(). */
-export function setSelectedPlayer(i) { selectedPlayer = i; }
 export function initSettingsMotion(ctx) {
+    const { t } = ctx;
+    const crtCfg = ctx.crt.cfg;
+    const applyCrt = () => { ctx.crt.apply(); };
+    /** The selected player: THIS panel's, in its closure (ADR-0232 D4) — a module `let` was shared by every root's panel. */
+    let selectedPlayer = 0;
     /*
-     * ⚠️ RESOLVIDAS UMA VEZ, NO ARRANQUE, e não a cada uso. O `rm` é mutado in-place e partilhado por
-     * REFERÊNCIA com quem desenha a cena; resolvê-lo a cada leitura criaria um objecto novo por chamada, o
-     * interruptor deixaria de alcançar o desenho, e não haveria erro nenhum — o menu diria «reduzido» e a cena
-     * continuaria a mexer-se.
+     * ⚠️ RESOLVED ONCE, AT BOOT, not on every use. `rm` is mutated in place and shared by REFERENCE with whoever draws
+     * the scene; resolving it on every read would create a new object per call, the switch would stop reaching the
+     * drawing, and there would be no error at all — the menu would say reduced and the scene would keep moving.
      */
-    const rm = ctx.rm ?? lerCenaGuardada();
-    const rmKeys = ctx.rmKeys ?? CHAVES_DE_CENA;
-    const rmChar = ctx.rmChar ?? ANIMACOES_DO_PERSONAGEM;
-    const saveRM = ctx.saveRM ?? (() => guardarCena(rm));
+    const rm = ctx.rm ?? readStoredScene(ctx.store, defaultReducedMotion(ctx.matchMedia));
+    const rmKeys = ctx.rmKeys ?? SCENE_KEYS;
+    const allCharAnimations = ctx.rmChar ?? CHARACTER_ANIMATIONS;
+    /** The character targets that HAVE A SUBJECT in this game — read on every use, because the cartridge changes on `mount()`. */
+    const rmChar = () => (ctx.hasCharacter?.() === false ? [] : allCharAnimations);
+    const saveRM = ctx.saveRM ?? (() => storeScene(ctx.store, rm));
     function reflectMotionBtn() {
         const b = ctx.$('#opt-animation');
         if (b)
@@ -134,119 +166,172 @@ export function initSettingsMotion(ctx) {
         if (!m)
             return;
         const player = ctx.getPlayers()[selectedPlayer];
-        const allFrozen = allMotionFrozen(rmKeys, rm, rmChar, player);
-        m.textContent = motionMasterLabel(allFrozen);
+        const allFrozen = allMotionFrozen(rmKeys, rm, rmChar(), player);
+        m.textContent = motionMasterLabel(t, allFrozen);
         ctx.toggleBtn(m, allFrozen);
     }
+    const kitCtx = (list) => ({
+        find: (sel) => ctx.$(sel),
+        create: (tag) => list.ownerDocument.createElement(tag),
+    });
+    const roundSpec = () => ({ label: t(CRT_LBL.round), values: [0, 1, 2].map((level) => crtLevelLabel(t, level)), current: crtCfg.round });
+    /** Each switch's STATE — what the kit does not write, because the panel knows the value. */
+    function reflectSwitches(el) {
+        const player = ctx.getPlayers()[selectedPlayer];
+        const writeSwitch = (sel, on, name) => {
+            const b = el.querySelector(sel);
+            if (!b)
+                return;
+            ctx.toggleBtn(b, on);
+            b.textContent = toggleLabel(t, on);
+            b.setAttribute('aria-label', toggleAria(t, name, on));
+        };
+        // ⚠️ "Animated" is the OPPOSITE of `rm`/`player[prop]`, which store "reduced motion". The faithful name is in
+        // `allMotionFrozen`, and the inversion lives here, in one place.
+        for (const c of rmChar())
+            writeSwitch(`[data-rmc="${c.prop}"]`, !(player && player[c.prop]), t(c.lbl));
+        for (const k of rmKeys)
+            writeSwitch(`[data-rm="${k}"]`, !rm[k], t(RM_LABEL[k]));
+        writeSwitch('[data-crt-tgl="scan"]', !!crtCfg.scan, t(CRT_LBL.scan));
+        writeSwitch('[data-crt-tgl="vig"]', !!crtCfg.vig, t(CRT_LBL.vig));
+    }
+    /** The listeners, ONCE and by delegation: the character rows come and go with the cartridge (ADR-0153), and wiring
+     *  button by button on every render would pile one listener per pass onto each button that survived. */
+    let wired = false;
+    function wireOnce(el) {
+        if (wired)
+            return;
+        wired = true;
+        el.addEventListener('click', (ev) => {
+            const b = ev.target?.closest('button');
+            if (!b || !el.contains(b))
+                return;
+            const crt = b.dataset.crtTgl;
+            if (crt) {
+                crtCfg[crt] = crtCfg[crt] ? 0 : 1;
+                applyCrt();
+                reflectSwitches(el);
+                refreshMarks();
+                ctx.srSay(crtToggleAnnouncement(t, t(CRT_LBL[crt]), !!crtCfg[crt]));
+                return;
+            }
+            const prop = b.dataset.rmc;
+            if (prop) {
+                const p = ctx.getPlayers()[selectedPlayer];
+                p[prop] = !p[prop];
+                ctx.store.setBool('incl_' + prop + '_p' + selectedPlayer, !!p[prop]);
+                render();
+                return;
+            }
+            const k = b.dataset.rm;
+            if (!k)
+                return;
+            rm[k] = !rm[k];
+            saveRM();
+            render();
+            updateMotionMaster();
+            ctx.srSay(sceneMotionAnnouncement(t, t(RM_LABEL[k]), rm[k]));
+        });
+        el.addEventListener('passo', (ev) => {
+            const stepper = ev.target?.closest('[data-crt="round"]');
+            if (!stepper)
+                return;
+            const next = nextStep(crtCfg.round, CRT_ROUND_LEVELS.length, ev.detail);
+            // ⚠️ AT THE END NOTHING IS ANNOUNCED: repeating the largest level to someone already there would sound like a step.
+            if (next === crtCfg.round)
+                return;
+            crtCfg.round = next;
+            applyCrt();
+            updateSteps(stepper, roundSpec());
+            refreshMarks();
+            ctx.srSay(crtRoundAnnouncement(t, t(CRT_LBL.round), crtCfg.round));
+        });
+    }
     function render() {
         const el = ctx.$('#motion-list');
         if (!el)
             return;
         selectedPlayer = clampSelectedPlayer(selectedPlayer, ctx.getNumPlayers());
-        // E3: sem abas — cada jogador edita só o seu. BUG preservado VERBATIM do game.js (não corrigido, ver
-        // retorno da extração): innerHTML='' roda ANTES do querySelectorAll, então o forEach abaixo nunca acha
-        // botões — este bloco de wiring é código morto tanto aqui quanto no original.
+        // No tabs — each player edits only their own. The strip stays hidden and empty.
         const tabs = ctx.$('#animation-players');
         if (tabs) {
             tabs.hidden = true;
-            tabs.innerHTML = '';
-            tabs.querySelectorAll('button[data-ap]').forEach((b) => b.addEventListener('click', () => {
-                selectedPlayer = Number(b.dataset.ap);
-                render();
-                // A prosa volta para o rodapé depois de as linhas serem reconstruídas (CLAUDE.md §4, #109).
-                ctx.fillExplain?.(ctx.$('#animation .overlay__card'));
-            }));
+            tabs.textContent = '';
         }
-        const player = ctx.getPlayers()[selectedPlayer];
-        const charRows = buildCharRowsHtml(rmChar, player);
-        const sceneRows = buildSceneRowsHtml(rmKeys, rm, RM_LABEL, RM_SOON);
-        const crtRows = crtToggleRowHtml(t(CRT_LBL.scan), 'scan', !!CRT.scan) + crtToggleRowHtml(t(CRT_LBL.vig), 'vig', !!CRT.vig) + crtRoundRowHtml(t(CRT_LBL.round), CRT.round);
-        el.innerHTML =
-            `<h3 class="panel-sub">Personagem${ctx.getNumPlayers() > 1 ? ' · Jogador ' + (selectedPlayer + 1) : ''} <span class="panel-sub__tag">por jogador</span></h3>${charRows}` +
-                `${secao('Cena')}${sceneRows}` +
-                `${secao('Estética CRT')}${crtRows}`;
-        el.querySelectorAll('button[data-crt-tgl]').forEach((b) => b.addEventListener('click', () => {
-            const k = b.dataset.crtTgl;
-            CRT[k] = CRT[k] ? 0 : 1;
-            applyCrt();
-            render();
-            ctx.srSay(crtToggleAnnouncement(t(CRT_LBL[k]), !!CRT[k]));
-        }));
-        el.querySelectorAll('select[data-crt]').forEach((s) => s.addEventListener('change', () => {
-            const key = s.dataset.crt;
-            CRT[key] = +s.value;
-            applyCrt();
-            ctx.srSay(crtRoundAnnouncement(t(CRT_LBL[key]), CRT[key]));
-        }));
-        el.querySelectorAll('button[data-rmc]').forEach((b) => b.addEventListener('click', () => {
-            const prop = b.dataset.rmc;
-            const p = ctx.getPlayers()[selectedPlayer];
-            p[prop] = !p[prop];
-            ctx.store.setBool('incl_' + prop + '_p' + selectedPlayer, !!p[prop]);
-            render();
-        }));
-        el.querySelectorAll('button[data-rm]').forEach((b) => b.addEventListener('click', () => {
-            const k = b.dataset.rm;
-            rm[k] = !rm[k];
-            saveRM();
-            render();
-            updateMotionMaster();
-            ctx.srSay(sceneMotionAnnouncement(t(RM_LABEL[k]), rm[k]));
-        }));
+        mountMotionInside(kitCtx(el), el, {
+            // ⚠️ THE SEAT SUFFIX is a key, and reuses the card's `pause.cardSeat`: it is the SAME sentence for the SAME person,
+            // and two keys would be two places for it to drift between languages.
+            charTitle: rmChar().length
+                ? (ctx.characterLabel?.() ?? 'Personagem') + (ctx.getNumPlayers() > 1 ? t('pause.cardSeat', { n: selectedPlayer + 1 }) : '')
+                : null,
+            // 📌 Three section labels are still raw and are in this module's raw-prose ledger — fixing them in passing would
+            // mix two decisions in one commit.
+            charTag: 'por jogador',
+            charRows: rmChar().map((c) => ({ prop: c.prop, label: t(c.lbl) })),
+            sceneTitle: 'Cena',
+            sceneRows: rmKeys.map((k) => ({ key: k, label: t(RM_LABEL[k]) })),
+            crtTitle: 'Estética CRT',
+            allTag: t('rm.sec.all'),
+            crtToggles: [{ key: 'scan', label: t(CRT_LBL.scan) }, { key: 'vig', label: t(CRT_LBL.vig) }],
+            roundSpec,
+        });
+        reflectSwitches(el);
+        wireOnce(el);
         updateMotionMaster();
         refreshMarks();
+        // The prose goes back to the footer after the rows change (CLAUDE.md §4, #109).
+        ctx.fillExplain?.(ctx.$('#animation .overlay__card'));
     }
     /**
-     * A marca de "saiu do padrão" (ADR-0029), contra o padrão CALCULADO — não contra `false`.
+     * The left-the-default mark (ADR-0029), against the COMPUTED default — not against `false`.
      *
-     * Numa máquina cujo dono pediu menos movimento, o padrão das cinco linhas de animação é CONGELADO. Marcar
-     * contra `false` acusaria "alterado" em cinco linhas que a criança nunca tocou, e mandaria justamente ela
-     * desfazer a preferência do próprio sistema. Uma marca errada é pior que marca nenhuma, e aqui ela erraria
-     * na direção mais cara.
+     * On a machine whose owner asked for less motion, the animation rows' default is FROZEN. Marking against `false` would
+     * accuse "changed" on rows the child never touched, and send exactly them to undo their own system's preference. A
+     * wrong mark is worse than no mark, and here it would err in the costliest direction.
      */
     function refreshMarks() {
-        const padraoRm = defaultReducedMotion();
+        const reducedByDefault = defaultReducedMotion(ctx.matchMedia);
         const el = ctx.$('#motion-list');
         const player = ctx.getPlayers()[selectedPlayer];
-        const mudou = [];
-        const marcar = (sel, changed) => {
-            mudou.push(changed);
-            markChanged(el?.querySelector(sel)?.closest('.ctrl-row') ?? null, changed);
+        const changedFlags = [];
+        const markRow = (sel, changed) => {
+            changedFlags.push(changed);
+            markChanged(t, el?.querySelector(sel)?.closest('.ctrl-row') ?? null, changed);
         };
-        for (const c of rmChar)
-            marcar(`[data-rmc="${c.prop}"]`, !!(player && player[c.prop]) !== padraoRm);
+        for (const c of rmChar())
+            markRow(`[data-rmc="${c.prop}"]`, !!(player && player[c.prop]) !== reducedByDefault);
         for (const k of rmKeys)
-            marcar(`[data-rm="${k}"]`, !!rm[k] !== padraoRm);
-        marcar('[data-crt-tgl="scan"]', !!CRT.scan !== !!CRT_DEFAULT.scan);
-        marcar('[data-crt-tgl="vig"]', !!CRT.vig !== !!CRT_DEFAULT.vig);
-        marcar('[data-crt="round"]', CRT.round !== CRT_DEFAULT.round);
-        markMenuChanged(ctx.$('[data-act="anim"]'), mudou);
+            markRow(`[data-rm="${k}"]`, !!rm[k] !== reducedByDefault);
+        markRow('[data-crt-tgl="scan"]', !!crtCfg.scan !== !!CRT_DEFAULT.scan);
+        markRow('[data-crt-tgl="vig"]', !!crtCfg.vig !== !!CRT_DEFAULT.vig);
+        markRow('[data-crt="round"]', crtCfg.round !== CRT_DEFAULT.round);
+        markMenuChanged(t, ctx.$('[data-act="anim"]'), changedFlags);
     }
-    // ---- restaurar os padrões DESTE menu (ADR-0028) ----
+    // ---- reset THIS menu's defaults (ADR-0028) ----
     //
-    // O único dos sete cujo padrão NÃO é uma constante: o das cinco linhas de animação é o que o sistema
-    // operacional pede (`prefers-reduced-motion`). Devolver `false` aqui RELIGARIA a animação na tela de quem
-    // já pediu menos movimento — o reset faria sozinho o que a WCAG 2.3.3 existe para impedir. Por isso ele
-    // chama `defaultReducedMotion()` e não escreve o valor à mão.
+    // The only menu whose default is NOT a constant: the animation rows' default is what the operating system asks for
+    // (`prefers-reduced-motion`). Returning `false` here would TURN ANIMATION BACK ON for whoever already asked for less
+    // motion — the reset alone would do what WCAG 2.3.3 exists to prevent. That is why it calls `defaultReducedMotion`
+    // and does not write the value by hand.
     //
-    // O escopo é TODOS os jogadores, como no menu motor: o painel edita um por vez, mas o reset é do menu, e
-    // deixar o jogador 2 congelado porque a aba aberta era a do jogador 1 daria dois estados com um nome só.
+    // The scope is ALL players, as in the mobility menu: the panel edits one at a time, but the reset belongs to the menu,
+    // and leaving player 2 frozen because the open tab was player 1's would give two states one name.
     const resetBtn = ctx.$('#animation-reset');
     if (resetBtn)
         resetBtn.addEventListener('click', () => {
-            const padraoRm = defaultReducedMotion();
+            const reducedByDefault = defaultReducedMotion(ctx.matchMedia);
             for (const k of rmKeys)
-                rm[k] = padraoRm;
+                rm[k] = reducedByDefault;
             saveRM();
             ctx.getPlayers().forEach((p, i) => {
-                for (const c of rmChar) {
-                    p[c.prop] = padraoRm;
-                    ctx.store.setBool('incl_' + c.prop + '_p' + i, padraoRm);
+                for (const c of rmChar()) {
+                    p[c.prop] = reducedByDefault;
+                    ctx.store.setBool('incl_' + c.prop + '_p' + i, reducedByDefault);
                 }
             });
-            CRT.scan = CRT_DEFAULT.scan;
-            CRT.vig = CRT_DEFAULT.vig;
-            CRT.round = CRT_DEFAULT.round;
+            crtCfg.scan = CRT_DEFAULT.scan;
+            crtCfg.vig = CRT_DEFAULT.vig;
+            crtCfg.round = CRT_DEFAULT.round;
             applyCrt();
             render();
             ctx.srSay(t('sr.motion.reset'));
@@ -271,25 +356,29 @@ export function initSettingsMotion(ctx) {
             return;
         const b = ctx.$('#opt-animation');
         if (b)
-            b.focus(); // recuo: este id nao existe no documento hoje (gancho de uma barra futura)
+            b.focus(); // fallback: this id does not exist in the document today (a hook for a future bar)
     }
     const master = ctx.$('#motion-master');
     if (master)
         master.addEventListener('click', () => {
             const player = ctx.getPlayers()[selectedPlayer];
-            const allFrozen = allMotionFrozen(rmKeys, rm, rmChar, player);
+            const allFrozen = allMotionFrozen(rmKeys, rm, rmChar(), player);
             const next = !allFrozen;
             for (const k of rmKeys)
                 rm[k] = next;
             saveRM();
             if (player)
-                for (const c of rmChar) {
+                for (const c of rmChar()) {
                     player[c.prop] = next;
                     ctx.store.setBool('incl_' + c.prop + '_p' + selectedPlayer, next);
                 }
             render();
-            ctx.srSay(stopResumeAllAnnouncement(next));
+            ctx.srSay(stopResumeAllAnnouncement(t, next));
         });
-    reflectMotionBtn(); // estado inicial (ex.: prefers-reduced-motion liga por padrão)
-    return { render, open, close };
+    reflectMotionBtn(); // initial state (e.g. prefers-reduced-motion switches it on by default)
+    return {
+        render, open, close,
+        selectedPlayer: () => selectedPlayer,
+        setSelectedPlayer: (i) => { selectedPlayer = i; },
+    };
 }