@the-inclusionist/engine 9.0.0 → 10.0.0

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

@@ -1,76 +1,79 @@
 // 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. */
+import type { Translate } from '../core/i18n.js';
+/** Scope of the accessibility overlays: they all live inside #game-region ("no screen outside the canvas"). */
 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`). */
+/**
+ * The i18n KEY of the explanation footer's resting text.
+ *
+ * 🔴 A KEY, never raw text: a raw sentence here would sit in one language under a card title in another, on the same
+ * screen.
+ *
+ * ⚠️ KEY AND NOT TEXT, by the rule `input/devices` already wrote for the same trap: a module `const` is evaluated ONCE,
+ * on import, so a resolved `t('…')` would freeze the boot language. Keeping the key, the point of use resolves it — and
+ * the point of use runs on every `fillExplain`.
+ */
+export declare const EXPLAIN_IDLE = "menu.explainIdle";
+/** Initial z-index of the stack: the first overlay brought to the front gets 61. */
 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. */
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    /** ui/dom.ts `$` — used only to resolve `#<id>` and check visibility in the Escape chain. Injected, not imported,
+     *  so the node test can pass a fake DOM. */
     $: <T extends Element = Element>(sel: string) => T | null;
-    /** ui/dom.ts `$$` — usado só por topVisibleOverlay(), que varre OVERLAY_SCOPE_SELECTOR. */
+    /** ui/dom.ts `$$` — used only by topVisibleOverlay(), which scans 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. */
+    /** Three things from `document`, and only them: `createElement` (fillExplain CREATES the `.opt-explain` footer the
+     *  first time it sees a card), `activeElement` and `contains` (frontOverlay notes who opened the dialog and
+     *  restoreFocus returns focus there). Injected so the module is not tied to the 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. */
+    /** An element's EFFECTIVE z-index — typically `+getComputedStyle(el).zIndex||0` ('auto' becomes NaN and the `||0`
+     *  turns it into 0; that is the injector's responsibility). Injected because getComputedStyle only exists in the
+     *  browser, and the node test needs to simulate the stack. */
     computedZ: (el: Element) => number;
 }
-/** Uma entrada do registro de overlays — substitui a tabela OVERLAY_CLOSE do game.js. */
+/** One entry of the overlay registry. */
 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. */
+    /** Closes the dialog. Each panel returns focus its own way inside it — the shell has no opinion. */
     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á.
+    /** Does this dialog join the Escape chain? REQUIRED with no default on purpose: an exclusion expressed as the ABSENCE
+     *  of a field is the kind of mistake nobody makes by choice, only by forgetting. Whoever registers has to say which
+     *  side they are on.
      *
-     *  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. */
+     *  "Open" is read from the dialog's visibility (`hidden`), not from a separate flag: a flag written next to every
+     *  `ov.hidden` would be redundant with it where they agree, and where they disagree `hidden` is what decides. */
     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). */
+    /** Brings the overlay to the front of the stack (increasing z) and fills its card's explanation footer. Called by
+     *  every panel's open. */
     frontOverlay: (el: HTMLElement | null) => void;
-    /** Move as descrições das `.ctrl-row` do card para o rodapé `.opt-explain` (idempotente por linha). */
+    /** Moves the card's `.ctrl-row` descriptions to the `.opt-explain` footer (idempotent per row). */
     fillExplain: (card: HTMLElement | null) => void;
-    /** Registra um diálogo. A ORDEM DE REGISTRO é significativa: é ela que a cadeia de Escape percorre. */
+    /** Registers a dialog. REGISTRATION ORDER matters: it is what the Escape chain walks. */
     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. */
+    /** Returns focus to whoever opened `id` (the counterpart of `frontOverlay`). False if the opener left or is not
+     *  focusable. */
     restoreFocus: (id: string) => boolean;
-    /** OVERLAY_CLOSE[id]?.() — devolve true se havia entrada registrada (o `if(c)c()` do dialogBack). */
+    /** Closes the registered dialog `id` — returns true if there was a registered entry. */
     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". */
+    /** Id of the dialog that should consume the key, or null. Walks in REGISTRATION ORDER (not by z-index) and returns the
+     *  first that is actually visible (`!el.hidden`). This is NOT "the one on top". */
     escapeTarget: () => string | null;
-    /** O overlay VISÍVEL mais alto na pilha (sharedDialogOpen do game.js). Empate de z: vence o último no DOM. */
+    /** The highest VISIBLE overlay in the stack. A z tie: the last in the DOM wins. */
     topVisibleOverlay: () => HTMLElement | null;
-    /** Ids registrados, na ordem — só para teste/depuração. */
+    /** Registered ids, in order — for tests/debugging only. */
     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.
+ * An option row's description: is there an `.opt-hint` inside the <span>? use its text. Otherwise take the <strong>'s
+ * prefix (the short label) and the dash separating label from description off the <span>'s text.
+ * Accepts — (em dash), – (en dash) and - (hyphen).
  */
 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.
+ * Picks the visible overlay with the highest z-index. A tie: the LAST in the list (DOM order) wins — the effect of a
+ * stable sort followed by taking the last. An empty list → 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

@@ -1,44 +1,44 @@
 // 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.
+// ui/settings-panel.ts — the COMMON SHELL of the settings dialogs: (a) the overlays' z-index stack (frontOverlay), (b)
+// the explanation footer (fillExplain), (c) the registry of dialogs (id → close) and (d) the Escape chain.
 //
-// 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.
+// DESIGN DECISION: there is NO generic open()/close() here. The dialogs diverge in almost everything a shell would do —
+// what to render before showing, WHICH control receives focus on open, what extra to do on close, and WHERE focus goes
+// back. A shell with a parameter per exception, each a one-line closure, would cost the same code plus one more
+// indirection to read. So this file delivers ONLY what is genuinely common, and each open/close stays a short function
+// readable on its own.
 //
-// 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.
+// ACCESSIBILITY: who focuses what stays in each panel's open/close functions; the focus trap is `ui/focus-trap`. What
+// THIS shell handles is READING ORDER: fillExplain takes the long description out of the row, leaves only the label in
+// <strong>, and hands the description to an `aria-live="polite"` footer — focus/hover on the row updates it. And
+// frontOverlay makes the last dialog opened sit on top (increasing z), which topVisibleOverlay reads back to know what to
+// navigate.
 //
-// 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. */
+// INJECTED via initSettingsPanel(ctx): $/$$ (ui/dom.ts), doc (`createElement` for the footer, `activeElement` and
+// `contains` for focus return) and computedZ (the effective z-index). No I/O on import; all state (the z counter and the
+// overlay registry) lives in the init's closure — two inits do not leak into each other.
+/** Scope of the accessibility overlays: they all live inside #game-region ("no screen outside the canvas"). */
 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`). */
+/**
+ * The i18n KEY of the explanation footer's resting text.
+ *
+ * 🔴 A KEY, never raw text: a raw sentence here would sit in one language under a card title in another, on the same
+ * screen.
+ *
+ * ⚠️ KEY AND NOT TEXT, by the rule `input/devices` already wrote for the same trap: a module `const` is evaluated ONCE,
+ * on import, so a resolved `t('…')` would freeze the boot language. Keeping the key, the point of use resolves it — and
+ * the point of use runs on every `fillExplain`.
+ */
+export const EXPLAIN_IDLE = 'menu.explainIdle';
+/** Initial z-index of the stack: the first overlay brought to the front gets 61. */
 export const OVERLAY_BASE_Z = 60;
 // ---------------------------------------------------------------------------------------------------------
-// Lógica PURA — sem `document`, testável no project node.
+// PURE logic — no `document`, testable in the node project.
 // ---------------------------------------------------------------------------------------------------------
 /**
- * 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.
+ * An option row's description: is there an `.opt-hint` inside the <span>? use its text. Otherwise take the <strong>'s
+ * prefix (the short label) and the dash separating label from description off the <span>'s text.
+ * Accepts — (em dash), – (en dash) and - (hyphen).
  */
 export function rowExplainText(spanText, strongText, hintText) {
     if (hintText !== null)
@@ -46,8 +46,79 @@ export function rowExplainText(spanText, strongText, hintText) {
     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.
+ * The three listeners that take the description to the footer and return it to rest. Both row shapes use them word for
+ * word, and writing them once is what keeps the two from drifting.
+ *
+ * NOTE (known defect, not fixed): there is no `focusout` listener — navigating by keyboard, the footer never returns to
+ * its resting text.
+ */
+function wireFooter(row, footer) {
+    // 🔴 READ AT THE INSTANT OF SHOWING, never captured: a closure keeps the sentence from the day the row was born, and a
+    // row built ONCE AND KEPT would never change it — the explanation would stay in the boot language forever.
+    const show = () => { footer.textContent = row.dataset.explain || (footer.dataset.idle ?? ''); };
+    const clear = () => { footer.textContent = footer.dataset.idle ?? ''; };
+    row.addEventListener('mouseenter', show);
+    row.addEventListener('focusin', show);
+    row.addEventListener('mouseleave', clear);
+}
+/**
+ * 🔴 A STEPS ROW HAS NO `<strong>`: its label lives inside the control itself («◀ Tamanho do controle: adulto pequeno ▶»,
+ * ADR-0130 errata), and giving up on rows without a separate short label would leave the hint beside the steps,
+ * squeezing them until they break over several lines. For it, the description is the whole hint, and the `<span>` is
+ * emptied.
+ */
+function wireStepsRow(row, span, hint, footer) {
+    const desc = (hint.textContent ?? '').trim();
+    row.dataset.explainDone = '1';
+    if (!desc)
+        return;
+    row.dataset.explain = desc;
+    span.textContent = '';
+    span.appendChild(hint); // hidden and not erased, for the same reason as the ordinary row, below
+    hint.hidden = true;
+    wireFooter(row, footer);
+}
+/**
+ * An ALREADY WIRED row, reread: only the TEXT changes, never the wiring.
+ *
+ * 📌 It is the half that makes the explanation follow the language (ADR-0225). The producer rewrites the `.opt-hint`, this
+ * function takes the new text to `data-explain`, and the footer reads it at the instant of showing. A hint that becomes
+ * EMPTY erases the explanation instead of keeping the previous one — the reason `labelRow` already gives for erasing
+ * instead of not writing: on a retranslation into a dictionary without the key, the old text would survive.
+ */
+function refreshExplain(row) {
+    const hint = row.querySelector(':scope > span .opt-hint');
+    if (!hint)
+        return; // a row that never had a hint, or lost it: it keeps what it has
+    row.dataset.explain = (hint.textContent ?? '').trim();
+}
+/** The ordinary row: short label in `<strong>`, prose beside it — and the prose goes down to the footer. */
+function wireLabelledRow(row, span, strong, footer) {
+    const hint = span.querySelector('.opt-hint');
+    const desc = rowExplainText(span.textContent ?? '', strong.textContent ?? '', hint ? (hint.textContent ?? '') : null);
+    row.dataset.explainDone = '1';
+    if (!desc)
+        return; // a label with no description: the row stays as it is
+    row.dataset.explain = desc;
+    span.innerHTML = strong.outerHTML; // READING ORDER: only the short label stays in view…
+    /*
+     * ⚠️ …and the hint COMES BACK, HIDDEN, instead of being destroyed.
+     *
+     * 🔴 Erasing it froze the explanation in the language the row was born in: the kit's `labelRow` rewrites `.opt-hint` on
+     * every relabel, and a node that no longer exists receives nothing.
+     *
+     * 📌 `hidden` takes it out of the whole accessibility tree, so the reading order of `CLAUDE.md` §4 stays intact: the
+     * screen reader still reads "short label, control", and the prose still belongs only to the footer.
+     */
+    if (hint) {
+        hint.hidden = true;
+        span.appendChild(hint);
+    }
+    wireFooter(row, footer); // the description goes to the footer on focus/hover
+}
+/**
+ * Picks the visible overlay with the highest z-index. A tie: the LAST in the list (DOM order) wins — the effect of a
+ * stable sort followed by taking the last. An empty list → null.
  */
 export function topByZ(overlays, zOf) {
     if (!overlays.length)
@@ -56,73 +127,75 @@ export function topByZ(overlays, zOf) {
     return sorted[sorted.length - 1];
 }
 // ---------------------------------------------------------------------------------------------------------
-// Casca DOM
+// DOM shell
 // ---------------------------------------------------------------------------------------------------------
 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.
+    const { t } = ctx;
+    // The z counter lives in the closure (not the module) so each init starts clean — otherwise a test would inherit the
+    // previous one's stack.
     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.
+    // The dialog registry. A Map preserves insertion order, which is exactly the Escape chain's order.
     const registry = new Map();
+    /** The card's footer, found or created. */
+    function explainFooter(card) {
+        const found = card.querySelector('.opt-explain');
+        if (found)
+            return found;
+        const f = ctx.doc.createElement('div');
+        f.className = 'opt-explain';
+        f.setAttribute('aria-live', 'polite'); // the footer is announced when it changes (focus/hover on the row)
+        // The resting text can be the PANEL's, via `data-explain-idle` on the card. It is where a menu introduction belongs:
+        // a paragraph of prose at the top turns the menu into a manual, and the footer is already the place for
+        // explanation — the panel has something to say only while nobody points at any row.
+        // ⚠️ RESOLVED HERE, not at the top of the module: `fillExplain` runs on every render, so the text follows a language
+        // change. A `t()` in a module `const` would freeze the boot language.
+        const idle = card.dataset.explainIdle || t(EXPLAIN_IDLE);
+        f.dataset.idle = idle;
+        f.textContent = idle;
+        card.appendChild(f);
+        return f;
+    }
     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
+        const footer = explainFooter(card);
         card.querySelectorAll('.ctrl-row').forEach((row) => {
-            if (row.dataset.explainDone)
-                return; // idempotente: render() redesenha o card, mas linha feita não repete
+            // Idempotent in the WIRING and only there: a finished row is not wired again, but its TEXT is reread, otherwise a
+            // row built once and kept would never change language (ADR-0225).
+            if (row.dataset.explainDone) {
+                refreshExplain(row);
+                return;
+            }
             const span = row.querySelector(':scope > span');
             const strong = span ? span.querySelector('strong') : null;
+            const stepsHint = !strong && span ? span.querySelector('.opt-hint') : null;
+            if (span && stepsHint && row.querySelector('[data-passos]')) {
+                wireStepsRow(row, span, stepsHint, footer);
+                return;
+            }
             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.
+            } // a row with no short label: nothing to move
+            wireLabelledRow(row, span, strong, footer);
         });
     }
-    /** 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. */
+    /** Who had focus when each dialog was brought to the front — keyed by dialog id. Used by `restoreFocus`, the
+     *  counterpart of `frontOverlay`. Not a disguised global `let`: it is born and dies with the registry, and the only
+     *  thing reading it is focus return. */
     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.
+        // BEFORE the dialog appears: whoever has focus now is whoever opened it, and that is where focus returns (WCAG
+        // 2.4.3). The real element, not a fixed id: the same panel is opened from the pause menu, a keyboard shortcut and a
+        // bar button, and only one of them is right each time.
+        // A STRUCTURAL check, not `instanceof HTMLElement`: this module runs in the `node` project, where there is no DOM
+        // global at all. All that is asked of the opener is what will be used — being able to receive focus.
         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)
+        const focusable = !!opener && typeof opener.focus === 'function';
+        const isInside = !!opener && typeof el.contains === 'function' && el.contains(opener);
+        if (focusable && opener !== el && !isInside)
             openerOf.set(el.id, opener);
         el.style.zIndex = String(++ovZ);
         const card = el.querySelector('.overlay__card');
@@ -130,16 +203,14 @@ export function initSettingsPanel(ctx) {
             fillExplain(card);
     }
     /**
-     * Devolve o foco a quem abriu o diálogo `id`. Verdadeiro se conseguiu.
+     * Returns focus to whoever opened dialog `id`. True if it succeeded.
      *
-     * 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.
+     * A fixed `#opt-*` per panel would fail silently: most of those ids do not exist in the document (they are hooks for a
+     * button bar that does not exist yet), so closing would leave focus on `<body>` — a keyboard user back at the start of
+     * the document, a screen-reader user losing their place entirely.
      *
-     * 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).
+     * It only returns to an element still in the document and still focusable — a panel may have been opened from inside
+     * another that already closed, and then the caller decides (hence the boolean).
      */
     function restoreFocus(id) {
         const opener = openerOf.get(id);
@@ -147,11 +218,11 @@ export function initSettingsPanel(ctx) {
         if (!opener)
             return false;
         if (typeof ctx.doc.contains === 'function' && !ctx.doc.contains(opener))
-            return false; // saiu do documento
+            return false; // it left the document
         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
+            return false; // hidden: focusing it would take focus nowhere
         opener.focus();
         return ctx.doc.activeElement === opener;
     }
@@ -168,10 +239,10 @@ export function initSettingsPanel(ctx) {
     function escapeTarget() {
         for (const [id, entry] of registry) {
             if (!entry.inEscapeChain)
-                continue; // #touchcfg e #help ficam de fora, verbatim
+                continue; // whoever registered outside the chain stays out
             const el = ctx.$('#' + id);
             if (!el || el.hidden)
-                continue; // aberto = VISÍVEL; era `dlgVis` no monólito, e agora é a única fonte
+                continue; // open = VISIBLE, the single source
             return id;
         }
         return null;