@the-inclusionist/engine 6.36.1

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

@@ -0,0 +1,215 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/settings-motor — MOTOR / MOVIMENTO POR JOGADOR panel (Estágio 4): extracted from game.js's
+// renderMovPlayers()/reflectFacil()/reflectAltMove()/setEasy() (~line 2136). Pure logic (per-player tab
+// clamp/view-model, the "any player active" predicate, the Modo Fácil announcement text) is separated from the
+// thin DOM-touching render/reflect functions. DI via initSettingsMotor(ctx): `$` (DOM selector), `srSay`,
+// `store` (platform/storage shape), `players`/`getNumPlayers` (core/state.ts's live state) and two setters that
+// stay OUTSIDE this module because they are shared with other UI surfaces: `setToggleMove` (also fired by the
+// pause-menu quick-icon `iconAct('altmove', …)`, unrelated to this panel) and `rebuildCoins` (coin subsystem,
+// Modo Fácil puts coins on the ground). Overlay open/close plumbing (frontOverlay, #movement hidden toggle,
+// Escape handling, renderMapHub) is the SHARED helper used by every settings panel and stays in game.js.
+import { toggleLabel } from './dom.js';
+import { t } from '../core/i18n.js';
+import { markChanged, markMenuChanged } from './changed-mark.js';
+import { DEFAULTS } from '../core/state.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) {
+    return 'incl_easy_p' + i;
+}
+/** localStorage key da alternância do botão de CORRER (== `toggleRunP` de platform/storage). */
+export function toggleRunKey(i) {
+    return 'incl_togglerun_p' + i;
+}
+/** 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 Modo Fácil or alternância — lights the #opt-movement bar button. */
+export function anyMotorActive(players) {
+    return players.some((p) => p.easy || p.toggleMove);
+}
+/** '❚❚ Ligado' / '▶ Desligado' para #opt-facil e #opt-altmove. Reexporta o de ui/dom, que é o único que
+ *  existe desde o item 14 — o corpo daqui era uma cópia, e o comentário já dizia "shared" sem sê-lo. */
+export const onOffLabel = toggleLabel;
+/**
+ * Full innerHTML for #movement-players, given the player count and the active index. Pure string building —
+ * no DOM. NOTE (verbatim from game.js, E3): 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('');
+}
+/**
+ * O 'Jogador N: ' que abre um anúncio quando há mais de uma tela. Uma tela só não leva prefixo — dizer
+ * "Jogador 1" para quem está sozinho é ruído, e ruído no leitor de tela custa tempo de escuta.
+ */
+export function playerPrefix(i, numPlayers) {
+    return numPlayers > 1 ? t('sr.player.prefix', { n: i + 1 }) : '';
+}
+/** srSay text for a Modo Fácil change. A frase inteira vem do dicionário — ver `sr.motor.easyOn`. */
+export function easyAnnouncement(i, numPlayers, on) {
+    return playerPrefix(i, numPlayers) + t(on ? 'sr.motor.easyOn' : 'sr.motor.easyOff');
+}
+// ---------------------------------------------------------------------------------------------
+// DOM-facing (thin) — requires `document`/injected ctx
+// ---------------------------------------------------------------------------------------------
+export function initSettingsMotor(ctx) {
+    let selMovPlayer = 0; // jogador selecionado no painel Acessibilidade motora
+    const facilBtn = ctx.$('#opt-facil');
+    const altMoveBtn = ctx.$('#opt-altmove');
+    const toggleRunBtn = ctx.$('#opt-togglerun');
+    // barra acende se QUALQUER jogador usa Fácil/alternância
+    function reflectMovementBtn() {
+        const b = ctx.$('#opt-movement');
+        if (b)
+            b.classList.toggle('is-on', anyMotorActive(ctx.players));
+        refreshMarks();
+    }
+    /**
+     * A marca de "saiu do padrão" (ADR-0029). Pendurada no reflect que JÁ roda a cada mudança dos dois
+     * controles, porque uma marca que precise de uma chamada própria é uma marca que alguém vai esquecer —
+     * e uma marca errada manda a criança desfazer o que ela nunca mexeu.
+     *
+     * O escopo segue o do reset deste menu: as duas PREFERÊNCIAS. Os métodos de entrada (olhos, mapeamento)
+     * ficam de fora aqui também — não porque não possam mudar, mas porque o padrão deles não mora em DEFAULTS,
+     * e marcar sem uma fonte única de "o que é padrão" seria inventar uma segunda opinião sobre isso.
+     */
+    function refreshMarks() {
+        const easy = ctx.players.some((p) => !!p.easy) !== DEFAULTS.easy;
+        const alt = ctx.players.some((p) => !!p.toggleMove) !== DEFAULTS.toggleMove;
+        // A ALTERNÂNCIA DO CORRER PERGUNTA DIFERENTE, e a diferença é o que ela tem de próprio: ela LIGA SOZINHA
+        // no controle de tela. Marcar pelo ESTADO acenderia a marca para 100% de quem joga em tablet, sem ninguém
+        // ter tocado em nada — e uma marca sempre acesa não significa nada. Pior: o comentário do reset deste
+        // menu já diz que "uma marca errada manda a criança desfazer o que ela nunca mexeu".
+        //
+        // Então o que marca é a ESCOLHA GUARDADA. Valor salvo significa que alguém mexeu naquele controle; o
+        // ligar automático não salva nada, e por isso não marca.
+        const runEscolhido = ctx.players.some((p, i) => ctx.store.get(toggleRunKey(i)) != null && !!p.toggleRun !== DEFAULTS.toggleRun);
+        markChanged(facilBtn?.closest('.ctrl-row') ?? null, easy);
+        markChanged(altMoveBtn?.closest('.ctrl-row') ?? null, alt);
+        markChanged(toggleRunBtn?.closest('.ctrl-row') ?? null, runEscolhido);
+        markMenuChanged(ctx.$('[data-act="motora"]'), [easy, alt, runEscolhido]);
+    }
+    function reflectFacil() {
+        const p = ctx.players[selMovPlayer];
+        const on = !!(p && p.easy);
+        if (facilBtn) {
+            facilBtn.classList.toggle('is-on', on);
+            facilBtn.setAttribute('aria-pressed', String(on));
+            facilBtn.textContent = onOffLabel(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(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(on);
+        }
+        reflectMovementBtn();
+    }
+    function setEasy(i, on) {
+        const p = ctx.players[i];
+        if (!p)
+            return;
+        p.easy = on;
+        ctx.store.setBool(easyKey(i), on);
+        reflectFacil();
+        ctx.rebuildCoins();
+        ctx.srSay(easyAnnouncement(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; // E3: sem abas — cada jogador edita só o seu (escopo = pauseActor)
+        tabs.innerHTML = playerTabsHTML(numPlayers, selMovPlayer);
+        tabs.querySelectorAll('button[data-mp]').forEach((b) => {
+            b.addEventListener('click', () => {
+                selMovPlayer = Number(b.dataset.mp);
+                renderMovPlayers();
+                reflectFacil();
+                reflectAltMove();
+            });
+        });
+    }
+    if (facilBtn) {
+        facilBtn.addEventListener('click', () => setEasy(selMovPlayer, !ctx.players[selMovPlayer].easy));
+    }
+    if (altMoveBtn) {
+        altMoveBtn.addEventListener('click', () => {
+            ctx.setToggleMove(selMovPlayer, !ctx.players[selMovPlayer].toggleMove);
+            reflectAltMove();
+        });
+    }
+    if (toggleRunBtn) {
+        toggleRunBtn.addEventListener('click', () => {
+            ctx.setToggleRun(selMovPlayer, !ctx.players[selMovPlayer].toggleRun);
+            reflectToggleRun();
+        });
+    }
+    // ---- restaurar os padrões DESTE menu (ADR-0028) ----
+    //
+    // O alcance aqui é MENOR que a tela, e de propósito. A Acessibilidade motora hospeda quatro coisas: Modo
+    // Fácil, movimento por alternância, o controle pelos olhos (#opt-eyes) e o mapeamento de teclas (#map-hub).
+    // O reset devolve as duas PREFERÊNCIAS e não encosta nos dois MÉTODOS DE ENTRADA, por uma razão que vale
+    // mais que a simetria:
+    //
+    //   UM RESET SÓ PODE DESFAZER O QUE ELE TAMBÉM CONSEGUE REFAZER.
+    //
+    // A criança que joga com os olhos aponta com os olhos. Desligar o controle pela webcam tira dela o ponteiro
+    // com que ela clicaria o botão de volta — o reset deixaria de remover uma armadilha para virar uma, e a
+    // saída passaria a depender de outra pessoa estar por perto. O mesmo vale para quem remapeou as teclas
+    // porque só alcança algumas: devolver o mapa de fábrica é devolver teclas que a mão dela não chega. Esse
+    // mapeamento, aliás, já tem o reset dele (#ctrl-reset), onde a escolha é explícita e não um efeito colateral.
+    //
+    // Por isso o anúncio DIZ o que ficou de fora: um botão que restaura menos do que o nome promete precisa
+    // dizer isso em voz alta, ou a criança conclui que ele não funcionou.
+    const resetBtn = ctx.$('#movement-reset');
+    if (resetBtn)
+        resetBtn.addEventListener('click', () => {
+            ctx.players.forEach((p, i) => {
+                if (p.easy)
+                    setEasy(i, false);
+                if (p.toggleMove)
+                    ctx.setToggleMove(i, false);
+                if (p.toggleRun)
+                    ctx.setToggleRun(i, false);
+            });
+            reflectFacil();
+            reflectAltMove();
+            reflectToggleRun();
+            ctx.srSay(t('sr.motor.reset'));
+        });
+    reflectFacil();
+    reflectAltMove();
+    reflectToggleRun();
+    return {
+        renderMovPlayers,
+        reflectFacil,
+        reflectAltMove,
+        reflectToggleRun,
+        setEasy,
+        setSelPlayer: (i) => { selMovPlayer = i; },
+        getSelPlayer: () => selMovPlayer,
+    };
+}

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

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Escopo dos overlays de a11y: o inCanvasMenus() do game.js reparenta TODOS para dentro do #game-region
+ *  ("nenhuma tela fora do canvas"). Verbatim do sharedDialogOpen() original. */
+export declare const OVERLAY_SCOPE_SELECTOR = "#game-region .overlay";
+/** Texto de repouso do rodapé de explicação (verbatim do game.js). */
+export declare const EXPLAIN_IDLE = "Passe o mouse ou navegue pelas op\u00E7\u00F5es para ver a explica\u00E7\u00E3o.";
+/** z-index inicial da pilha: o primeiro overlay trazido à frente recebe 61. Verbatim (`let _ovZ=60`). */
+export declare const OVERLAY_BASE_Z = 60;
+export interface SettingsPanelCtx {
+    /** ui/dom.ts `$` — usado só para resolver `#<id>` e checar visibilidade na cadeia de Escape (o `dlgVis`
+     *  do game.js). Injetado, e não importado direto, para o teste node poder passar um DOM falso. */
+    $: <T extends Element = Element>(sel: string) => T | null;
+    /** ui/dom.ts `$$` — usado só por topVisibleOverlay(), que varre OVERLAY_SCOPE_SELECTOR. */
+    $$: <T extends Element = Element>(sel: string) => T[];
+    /** Três coisas do `document`, e só elas: `createElement` (fillExplain CRIA o rodapé `.opt-explain` na
+     *  primeira vez que vê um card), `activeElement` e `contains` (frontOverlay anota quem abriu o diálogo e
+     *  restoreFocus devolve o foco para lá). Injetado para não amarrar o módulo ao global. */
+    doc: Pick<Document, 'createElement' | 'activeElement' | 'contains'>;
+    /** z-index EFETIVO de um elemento. No game.js é `+getComputedStyle(el).zIndex||0` (repare: 'auto' vira NaN
+     *  e o `||0` o transforma em 0 — comportamento preservado, é responsabilidade de quem injeta). Injetado
+     *  porque getComputedStyle só existe no navegador, e porque o teste node precisa simular a pilha. */
+    computedZ: (el: Element) => number;
+}
+/** Uma entrada do registro de overlays — substitui a tabela OVERLAY_CLOSE do game.js. */
+export interface OverlayEntry {
+    /** Fecha o diálogo. É o MESMO valor que estava em OVERLAY_CLOSE[id] no game.js: cada painel devolve o foco
+     *  do seu jeito lá dentro (uns a um `#opt-*`, outros ao menu de pausa) — a casca não opina. */
+    close: () => void;
+    /** Este diálogo entra na cadeia de Escape? #touchcfg e #help NÃO entram — nunca tiveram flag `*Open` no
+     *  monólito, e a exclusão é verbatim (há conserto pendente). É obrigatório e não tem padrão de propósito:
+     *  no monólito a exclusão era a AUSÊNCIA de um campo, o tipo de erro que ninguém comete de novo por escolha,
+     *  só por esquecimento. Aqui quem registra tem de dizer em qual lado está.
+     *
+     *  ANTES aqui havia `isOpen?: () => boolean`, espelhando sete flags `let` do game.js (`optionsOpen`,
+     *  `audioOpen`, …) mais o `export let motionOpen` de ui/settings-motion. Todas eram escritas na linha
+     *  colada ao `ov.hidden` do próprio open/close, e nenhuma tinha outro leitor. Como `escapeTarget` já
+     *  descartava diálogo invisível (a guarda `dlgVis` logo abaixo), a flag era redundante COM a guarda: onde
+     *  concordavam não mudava nada, e onde divergiam quem decidia era o `hidden`. Sete variáveis mutáveis, um
+     *  binding mutável exportado entre módulos e um callback de ctx, todos apagados sem mudar comportamento —
+     *  o teste que pina a divergência (flag presa em true num diálogo escondido) continua verde. */
+    inEscapeChain: boolean;
+}
+export interface SettingsPanelApi {
+    /** Traz o overlay para a frente da pilha (z crescente) e preenche o rodapé de explicação do seu card.
+     *  Chamado por TODOS os open* (game.js) e pelos módulos que já têm o seu (motion/empathy/touch/gamepad). */
+    frontOverlay: (el: HTMLElement | null) => void;
+    /** Move as descrições das `.ctrl-row` do card para o rodapé `.opt-explain` (idempotente por linha). */
+    fillExplain: (card: HTMLElement | null) => void;
+    /** Registra um diálogo. A ORDEM DE REGISTRO é significativa: é ela que a cadeia de Escape percorre. */
+    register: (id: string, entry: OverlayEntry) => void;
+    /** Devolve o foco a quem abriu `id` (o par de `frontOverlay`). Falso se o abridor sumiu ou não é focável. */
+    restoreFocus: (id: string) => boolean;
+    /** OVERLAY_CLOSE[id]?.() — devolve true se havia entrada registrada (o `if(c)c()` do dialogBack). */
+    closeById: (id: string) => boolean;
+    /** Id do diálogo que deve consumir a tecla, ou null. Percorre na ORDEM DE REGISTRO (não por z-index — é o
+     *  encadeamento if/else do game.js portado verbatim) e devolve o primeiro que esteja com a flag `*Open`
+     *  ligada E de fato visível (`!el.hidden`). Ver o relatório: isto NÃO é "o de cima". */
+    escapeTarget: () => string | null;
+    /** O overlay VISÍVEL mais alto na pilha (sharedDialogOpen do game.js). Empate de z: vence o último no DOM. */
+    topVisibleOverlay: () => HTMLElement | null;
+    /** Ids registrados, na ordem — só para teste/depuração. */
+    registeredIds: () => string[];
+}
+/**
+ * A descrição de uma linha de opção, do jeito que o game.js a extrai:
+ * há `.opt-hint` dentro do <span>? usa o texto dele. Senão, tira do texto do <span> o prefixo do <strong>
+ * (o rótulo curto) e o travessão que separa rótulo de descrição.
+ * Aceita — (em dash), – (en dash) e - (hífen), como no original.
+ */
+export declare function rowExplainText(spanText: string, strongText: string, hintText: string | null): string;
+/**
+ * Escolhe o overlay visível de z-index mais alto. Empate: vence o ÚLTIMO da lista (ordem do DOM) — é o efeito
+ * do `sort` estável seguido de `ov[ov.length-1]` no game.js. Lista vazia → null.
+ */
+export declare function topByZ<T>(overlays: readonly T[], zOf: (el: T) => number): T | null;
+export declare function initSettingsPanel(ctx: SettingsPanelCtx): SettingsPanelApi;

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

@@ -0,0 +1,187 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/settings-panel.ts — a CASCA COMUM dos diálogos de configuração (#visual, #typo, #audio, #options,
+// #movement, #animation, #empathy, #touchcfg, #help). Os SETE painéis já saíram para ui/settings-*.ts; o que
+// sobrou no game.js em volta deles era: (a) a pilha de z-index dos overlays (`_ovZ` + frontOverlay), (b) o
+// rodapé de explicação (fillExplain), (c) a tabela OVERLAY_CLOSE (id → fechar) e (d) o encadeamento de Escape.
+//
+// DECISÃO DE PROJETO (ver relatório da extração): NÃO existe aqui um open()/close() genérico. Os nove diálogos
+// divergem em quase tudo o que a casca faria — o que renderizar antes de mostrar (de 0 a 5 chamadas distintas),
+// QUAL controle recebe o foco ao abrir (`button` · `button[data-viz]||button` · `button[data-font]:not([disabled])
+// ||button` · `select,button`), qual flag `*Open` refletir (sete têm, dois não), o que fazer a mais ao fechar
+// (só #options cancela a captura de tecla) e PARA ONDE o foco volta (sete vão a um `#opt-*`, dois devolvem ao
+// menu de pausa por menuFocus/sharedDialogOpen). Uma casca com seis parâmetros de exceção, todos eles closures
+// de uma linha, custaria o mesmo código e uma indireção a mais para ler — e três dos painéis (motion, empathy,
+// touch) já implementam o seu próprio open/close dentro do módulo. Então este arquivo entrega SÓ o que é
+// genuinamente comum, e o open/close continua sendo sete (nove) funções curtas, cada uma legível sozinha.
+//
+// ACESSIBILIDADE: quem foca o quê continua nas funções de abrir/fechar de cada painel — esta casca não mexe em
+// foco, em `aria-modal` (é estático no index.html) e não instala armadilha de foco (o original também não tem;
+// ver o relatório). O que ELA cuida é da ORDEM DE LEITURA: fillExplain tira a descrição longa de dentro da
+// linha, deixa só o rótulo em <strong>, e passa a descrição a um rodapé `aria-live="polite"` — foco/hover na
+// linha atualiza esse rodapé. E frontOverlay garante que o último diálogo aberto fique por cima (z crescente),
+// que é o que sharedDialogOpen/topVisibleOverlay lê de volta para saber quem navegar.
+//
+// INJETADO via initSettingsPanel(ctx): $/$$ (ui/dom.ts), doc (só `createElement`, para o rodapé) e computedZ
+// (leitura do z-index efetivo). Nenhuma I/O no import; todo o estado (o contador `_ovZ` e o registro de
+// overlays) vive no closure do init — dois inits em processos de teste distintos não vazam um no outro.
+/** Escopo dos overlays de a11y: o inCanvasMenus() do game.js reparenta TODOS para dentro do #game-region
+ *  ("nenhuma tela fora do canvas"). Verbatim do sharedDialogOpen() original. */
+export const OVERLAY_SCOPE_SELECTOR = '#game-region .overlay';
+/** Texto de repouso do rodapé de explicação (verbatim do game.js). */
+export const EXPLAIN_IDLE = 'Passe o mouse ou navegue pelas opções para ver a explicação.';
+/** z-index inicial da pilha: o primeiro overlay trazido à frente recebe 61. Verbatim (`let _ovZ=60`). */
+export const OVERLAY_BASE_Z = 60;
+// ---------------------------------------------------------------------------------------------------------
+// Lógica PURA — sem `document`, testável no project node.
+// ---------------------------------------------------------------------------------------------------------
+/**
+ * A descrição de uma linha de opção, do jeito que o game.js a extrai:
+ * há `.opt-hint` dentro do <span>? usa o texto dele. Senão, tira do texto do <span> o prefixo do <strong>
+ * (o rótulo curto) e o travessão que separa rótulo de descrição.
+ * Aceita — (em dash), – (en dash) e - (hífen), como no original.
+ */
+export function rowExplainText(spanText, strongText, hintText) {
+    if (hintText !== null)
+        return hintText.trim();
+    return spanText.slice(strongText.length).replace(/^\s*[—–-]\s*/, '').trim();
+}
+/**
+ * Escolhe o overlay visível de z-index mais alto. Empate: vence o ÚLTIMO da lista (ordem do DOM) — é o efeito
+ * do `sort` estável seguido de `ov[ov.length-1]` no game.js. Lista vazia → null.
+ */
+export function topByZ(overlays, zOf) {
+    if (!overlays.length)
+        return null;
+    const sorted = [...overlays].sort((a, b) => zOf(a) - zOf(b));
+    return sorted[sorted.length - 1];
+}
+// ---------------------------------------------------------------------------------------------------------
+// Casca DOM
+// ---------------------------------------------------------------------------------------------------------
+export function initSettingsPanel(ctx) {
+    // `_ovZ` do game.js. Fica no closure (e não no módulo) para que cada init comece limpo — sem isso um teste
+    // herdaria a pilha do anterior.
+    let ovZ = OVERLAY_BASE_Z;
+    // OVERLAY_CLOSE + as flags `*Open`, num registro só. Map preserva a ordem de inserção, que é justamente a
+    // ordem do encadeamento de Escape.
+    const registry = new Map();
+    function fillExplain(card) {
+        if (!card)
+            return;
+        let f = card.querySelector('.opt-explain');
+        if (!f) {
+            f = ctx.doc.createElement('div');
+            f.className = 'opt-explain';
+            f.setAttribute('aria-live', 'polite'); // rodapé anunciado ao mudar (foco/hover na linha)
+            // O texto de repouso pode ser DO PAINEL, via `data-explain-idle` no card. É onde uma introdução de menu
+            // deve morar: um parágrafo de prosa no topo transforma o menu num manual, e o rodapé já é o lugar da
+            // explicação — o painel só passa a ter algo a dizer enquanto ninguém aponta para nenhuma linha.
+            const idle = card.dataset.explainIdle || EXPLAIN_IDLE;
+            f.dataset.idle = idle;
+            f.textContent = idle;
+            card.appendChild(f);
+        }
+        const footer = f; // estreita o tipo para os closures abaixo
+        card.querySelectorAll('.ctrl-row').forEach((row) => {
+            if (row.dataset.explainDone)
+                return; // idempotente: render() redesenha o card, mas linha feita não repete
+            const span = row.querySelector(':scope > span');
+            const strong = span ? span.querySelector('strong') : null;
+            if (!span || !strong) {
+                row.dataset.explainDone = '1';
+                return;
+            } // linha sem rótulo curto: nada a mover
+            const hint = span.querySelector('.opt-hint');
+            const desc = rowExplainText(span.textContent ?? '', strong.textContent ?? '', hint ? (hint.textContent ?? '') : null);
+            row.dataset.explainDone = '1';
+            if (!desc)
+                return; // rótulo sem descrição: a linha fica como está
+            row.dataset.explain = desc;
+            span.innerHTML = strong.outerHTML; // ORDEM DE LEITURA: a linha passa a ter só o rótulo curto…
+            const show = () => { footer.textContent = desc; }; // …e a descrição vai ao rodapé ao focar/passar o mouse
+            const clear = () => { footer.textContent = footer.dataset.idle ?? ''; };
+            row.addEventListener('mouseenter', show);
+            row.addEventListener('focusin', show);
+            row.addEventListener('mouseleave', clear);
+            // NOTA (bug do original, preservado): não há listener de 'focusout' — navegando por teclado o rodapé
+            // nunca volta ao texto de repouso. Relatado, não corrigido.
+        });
+    }
+    /** Quem tinha o foco quando cada diálogo foi trazido para a frente — a chave é o id do diálogo. Usado por
+     *  `restoreFocus`, o par de `frontOverlay`. Não é um `let` global disfarçado: nasce e morre com o registro,
+     *  e a única coisa que o lê é a devolução do foco. */
+    const openerOf = new Map();
+    function frontOverlay(el) {
+        if (!el)
+            return;
+        // ANTES de o diálogo aparecer: quem está com o foco agora é quem o abriu, e é para ele que o foco volta
+        // (WCAG 2.4.3). O elemento de verdade, e não um id fixo: o mesmo painel é aberto do menu de pausa, de um
+        // atalho de teclado e de um botão da barra, e só um deles é o certo em cada vez.
+        // Checagem ESTRUTURAL, e não `instanceof HTMLElement`: este módulo roda no project `node`, onde não existe
+        // global de DOM nenhum. O que se pede do abridor é só o que se vai usar dele — saber receber foco.
+        const opener = ctx.doc.activeElement;
+        const focavel = !!opener && typeof opener.focus === 'function';
+        const dentro = !!opener && typeof el.contains === 'function' && el.contains(opener);
+        if (focavel && opener !== el && !dentro)
+            openerOf.set(el.id, opener);
+        el.style.zIndex = String(++ovZ);
+        const card = el.querySelector('.overlay__card');
+        if (card)
+            fillExplain(card);
+    }
+    /**
+     * Devolve o foco a quem abriu o diálogo `id`. Verdadeiro se conseguiu.
+     *
+     * Antes disto cada `close*` focava um `#opt-*` fixo — e SEIS desses nove ids não existem no documento
+     * (`#opt-visual`, `#opt-sound`, `#opt-movement`, `#opt-controls`, `#opt-animation`, `#opt-empathy`: são
+     * ganchos para uma barra de botões que ainda não foi feita). O `if (b) b.focus()` engolia isso em silêncio,
+     * então fechar o painel deixava o foco no `<body>`: quem navega por teclado voltava para o começo do
+     * documento, e quem usa leitor de tela perdia o lugar inteiro.
+     *
+     * Só devolve para elemento que ainda está no documento e ainda é focável — um painel pode ter sido aberto de
+     * dentro de outro que já fechou, e nesse caso quem decide é o chamador (daí o booleano).
+     */
+    function restoreFocus(id) {
+        const opener = openerOf.get(id);
+        openerOf.delete(id);
+        if (!opener)
+            return false;
+        if (typeof ctx.doc.contains === 'function' && !ctx.doc.contains(opener))
+            return false; // saiu do documento
+        if (typeof opener.hasAttribute === 'function' && opener.hasAttribute('disabled'))
+            return false;
+        if (opener.offsetParent === null)
+            return false; // escondido: focar nele não levaria o foco a lugar nenhum
+        opener.focus();
+        return ctx.doc.activeElement === opener;
+    }
+    function register(id, entry) {
+        registry.set(id, entry);
+    }
+    function closeById(id) {
+        const entry = registry.get(id);
+        if (!entry)
+            return false;
+        entry.close();
+        return true;
+    }
+    function escapeTarget() {
+        for (const [id, entry] of registry) {
+            if (!entry.inEscapeChain)
+                continue; // #touchcfg e #help ficam de fora, verbatim
+            const el = ctx.$('#' + id);
+            if (!el || el.hidden)
+                continue; // aberto = VISÍVEL; era `dlgVis` no monólito, e agora é a única fonte
+            return id;
+        }
+        return null;
+    }
+    function topVisibleOverlay() {
+        const visible = ctx.$$(OVERLAY_SCOPE_SELECTOR).filter((o) => !o.hidden);
+        return topByZ(visible, ctx.computedZ);
+    }
+    return {
+        frontOverlay, fillExplain, register, closeById, escapeTarget, topVisibleOverlay, restoreFocus,
+        registeredIds: () => [...registry.keys()],
+    };
+}

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

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type FontItem } from './fonts.js';
+/** Minimal DOM-selector shape (matches ui/dom.ts's `$`). */
+export type { DomQuery } from '../core/dom-query.js';
+/** Minimal platform/storage.ts shape this module needs (get/set only — no direct localStorage access). */
+export interface TypoStore {
+    get(key: string, fallback?: string | null): string | null;
+    set(key: string, value: string | number | boolean): boolean;
+}
+export interface SettingsTypoCtx {
+    /** DOM selector (querySelector), injected — never reaches `document` globally. */
+    $: DomQuery;
+    /** Screen-reader announcement (core/a11y-sr's srSay), injected. */
+    srSay: (msg: string) => void;
+    /** Persistence (platform/storage.ts), injected. */
+    store: TypoStore;
+    /** Element the chosen font is applied to (dataset.fonte + --font-custom): document.documentElement in prod. */
+    root: HTMLElement;
+    /**
+     * Move a prosa das linhas para o rodapé (`ui/settings-panel` → `fillExplain`). Chamado a CADA `render()`, e
+     * não só ao abrir — que é o defeito que este parâmetro existe para fechar.
+     *
+     * `fillExplain` roda uma vez quando o overlay é frontalizado e reescreve cada `<span>` para conter só o
+     * rótulo curto. Mas `render()` reconstrói o `#typo-list` inteiro a cada clique numa fonte, e as linhas novas
+     * voltam com o `.opt-hint` dentro. Sem esta chamada a descrição aparece DUAS vezes — no rodapé, vinda da
+     * primeira passada, e sob o nome da fonte, vinda do redesenho. O CLAUDE.md §4 avisa exatamente isso.
+     *
+     * OPCIONAL de propósito: um consumidor que monte este painel sem a casca (o segundo consumidor, um teste)
+     * continua desenhando. O que ele não pode é desenhar prosa duplicada, e sem casca não há rodapé para duplicar.
+     */
+    fillExplain?: (card: HTMLElement | null) => void;
+}
+export interface SettingsTypoApi {
+    /** Re-renders #typo-list from current selection and (re)wires its buttons. Idempotent. */
+    render: () => void;
+    /** Selects+applies+persists a font by key; no-op for unknown/disabled keys. Mirrors old setGameFont(k,announce). */
+    setFont: (k: string, announce?: boolean) => void;
+    /** Currently selected font key. */
+    getFontKey: () => string;
+}
+/** A key is selectable when it exists in the catalog and is not marked `.off` (licence pending, etc.). */
+export declare function isSelectableFont(k: string): boolean;
+export { resolveFontKey, persistFontKey } from './fonts.js';
+import type { DomQuery } from '../core/dom-query.js';
+export interface FontCssTarget {
+    /** Value written to root.dataset.fonte. */
+    fonte: 'padrao' | 'alfabetizacao' | 'dislexia' | 'custom';
+    /** Value for the --font-custom CSS property, or null to remove the property. */
+    customFamily: string | null;
+}
+/**
+ * Maps a selectable font key to the CSS it drives. The three canonical EdSP fonts (atkinson/andika/lexend) use
+ * dedicated data-fonte values (Lexend's keeps the BDA letter/word spacing tied to data-fonte="dislexia"); every
+ * other catalog font goes through --font-custom with a generic fallback by family (serif/cursive/none).
+ * Verbatim port of the branching inside the old setGameFont().
+ */
+export declare function fontCssTarget(k: string, it: FontItem): FontCssTarget;
+export interface TypoRow {
+    key: string;
+    fam: string;
+    selected: boolean;
+    disabled: boolean;
+    /** Description (+ "— <off reason>" when disabled), or '' when there is none. */
+    note: string;
+}
+export interface TypoGroupView {
+    g: string;
+    rows: TypoRow[];
+}
+/** Pure view-model for the typography list: which row is selected/disabled and its note, per catalog group. */
+export declare function typoGroups(fontKey: string): TypoGroupView[];
+/** Full innerHTML for #typo-list, given the currently selected key. Pure string building — no DOM. */
+export declare function typoListHTML(fontKey: string): string;
+export declare function initSettingsTypo(ctx: SettingsTypoCtx): SettingsTypoApi;