@the-inclusionist/engine 6.36.1

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

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/settings-caa.ts — O SÉTIMO MENU: COMUNICAÇÃO AUMENTADA E ALTERNATIVA (ADR-0028, issue #57).
+//
+// O catálogo (quem existe, sob qual licença, em qual camada) mora em ./caa-sets.js; aqui só a tela. DI por
+// ctx, como os seis painéis irmãos: nada de global fora do que for injetado.
+//
+// O QUE ESTE MENU É HOJE, dito sem maquiagem: um seletor de caixa de letra que já mostra, ao lado, os sete
+// conjuntos de pictogramas que virão. Só as duas caixas de letra funcionam — os pictogramas são milhares de
+// arquivos que ainda não entraram no repositório, e três deles dependem de negociação que não é nossa.
+//
+// Mostrar o que não funciona seria desonesto se o menu não dissesse POR QUE. Ele diz, e com duas respostas
+// diferentes de propósito: "em preparação" (a licença está resolvida, o trabalho é nosso) e "aguardando
+// negociação" (a permissão é de outra pessoa). Um educador que lê a primeira sabe esperar; que lê a segunda
+// sabe que esperar não adianta. Esconder tudo o que ainda não anda faria o educador concluir que o jogo não
+// faz pictograma nenhum — que é a conclusão errada, e a que mais custa a quem precisa deles.
+//
+// LETRA vs PICTOGRAMA: a escolha de caixa é `letterCase` (core/state). NÃO existe um `caaMode` paralelo, e
+// isso é decisão: enquanto só duas opções forem escolhíveis, uma segunda variável para a mesma pergunta
+// seria duplicação com aparência de arquitetura. Ver a nota em core/state.
+import { toggleLabel } from './dom.js';
+import { t } from '../core/i18n.js';
+import { DEFAULTS } from '../core/state.js';
+import { CAA_SETS, CAA_BY_KEY, caaMotivo } from './caa-sets.js';
+import { markChanged, markMenuChanged } from './changed-mark.js';
+/**
+ * A linha das LETRAS é um INTERRUPTOR, não duas opções (decisão do Dev). Ligado = só maiúsculas; desligado =
+ * maiúsculas e minúsculas. Uma pergunta binária apresentada como duas linhas obriga a criança a comparar as
+ * duas para descobrir que são a mesma pergunta.
+ */
+export function caixaAltaLigada(caso) {
+    return caso === 'upper';
+}
+/** O interruptor das letras. Sempre disponível: é o piso offline, e nunca dependeu de arquivo nenhum. */
+export function letrasRowHtml(ligado) {
+    return ('<div class="ctrl-row" id="caa-letras"><span><strong>Letras maiúsculas</strong>' +
+        '<span class="opt-hint">Ligado: o jogo inteiro em caixa alta, como a alfabetização brasileira costuma ' +
+        'começar. Desligado: maiúsculas e minúsculas, a escrita do dia a dia.</span></span>' +
+        `<button class="mode-btn switch${ligado ? ' is-on' : ''}" id="caa-caixa-alta" type="button"` +
+        ` aria-pressed="${ligado}" aria-label="Letras maiúsculas">${toggleLabel(ligado)}</button></div>`);
+}
+/**
+ * Uma linha do menu: RÓTULO CURTO e nada mais à vista.
+ *
+ * Tudo o que explica — nota, licença, situação — entra num único `.opt-hint`, que é o que a casca
+ * (`fillExplain`) reconhece e MOVE para o rodapé. A primeira versão pendurava três blocos de prosa dentro da
+ * linha, e o Dev viu o resultado: o menu virou um manual, mais parecido com um arquivo de configuração do que
+ * com um menu de videogame. A explicação já tinha um lugar; eu é que não a pus lá.
+ *
+ * O `disabled` fica: a situação some do TEXTO, não do controle. E o `aria-label` guarda o motivo, para quem
+ * navega por teclado ouvir por que a linha não responde sem precisar caçar o rodapé.
+ */
+export function caaRowHtml(s, selecionada) {
+    const motivo = caaMotivo(s);
+    const explica = [s.nota, s.licenca ? `Licença: ${s.licenca}` : '', motivo ? t(motivo) : '']
+        .filter(Boolean).join(' · ');
+    const hint = explica ? `<span class="opt-hint">${explica}</span>` : '';
+    const estado = toggleLabel(selecionada);
+    return (`<div class="ctrl-row"><span><strong>${s.nome}</strong>${hint}</span>` +
+        `<button class="mode-btn switch${selecionada ? ' is-on' : ''}" data-caa="${s.key}" type="button"` +
+        `${s.disponivel ? '' : ' disabled'} aria-pressed="${selecionada}"` +
+        ` aria-label="${s.nome}${motivo ? ', ' + t(motivo) : ''}">${estado}</button></div>`);
+}
+/** O corpo do menu, em três seções — a seção diz de quem é a vez de agir. */
+export function caaListHtml(caso) {
+    const bloco = (titulo, tag, corpo) => corpo ? `<h3 class="panel-sub">${titulo} <span class="panel-sub__tag">${tag}</span></h3>${corpo}` : '';
+    const sets = (f) => CAA_SETS.filter(f).map((s) => caaRowHtml(s, false)).join('');
+    return (bloco(t('caa.secao.agora'), t('caa.secao.agoraTag'), letrasRowHtml(caixaAltaLigada(caso))) +
+        bloco(t('caa.secao.preparo'), t('caa.secao.preparoTag'), sets((s) => s.tier !== 'negotiating')) +
+        bloco(t('caa.secao.negociacao'), t('caa.secao.negociacaoTag'), sets((s) => s.tier === 'negotiating')));
+}
+export function initSettingsCaa(ctx) {
+    function render() {
+        const el = ctx.$('#caa-list');
+        if (!el)
+            return;
+        el.innerHTML = caaListHtml(ctx.getLetterCase());
+        const alta = el.querySelector('#caa-caixa-alta');
+        if (alta)
+            alta.addEventListener('click', () => {
+                const ligar = !caixaAltaLigada(ctx.getLetterCase());
+                ctx.setLetterCase(ligar ? 'upper' : 'mixed');
+                render();
+                ctx.srSay(t(ligar ? 'sr.caa.caixaAltaOn' : 'sr.caa.caixaAltaOff'));
+            });
+        el.querySelectorAll('button[data-caa]').forEach((b) => {
+            b.addEventListener('click', () => {
+                const set = b.dataset.caa ? CAA_BY_KEY[b.dataset.caa] : undefined;
+                // Nenhum conjunto está disponível hoje, e todos vêm `disabled`. A guarda existe para o dia em que
+                // alguém remover o atributo "só para testar": um conjunto que não está no jogo não pode virar a
+                // escolha da criança por acidente, deixando a tela sem nada para desenhar.
+                if (!set || !set.disponivel)
+                    return;
+            });
+        });
+        ctx.fillExplain(ctx.$('#caa .overlay__card'));
+        refreshMarks();
+    }
+    /** A marca de "saiu do padrão" (ADR-0029), na linha escolhida e no botão do menu. */
+    function refreshMarks() {
+        const mudou = ctx.getLetterCase() !== DEFAULTS.letterCase;
+        markChanged(ctx.$('#caa-letras'), mudou);
+        markMenuChanged(ctx.$('[data-act="caa"]'), [mudou]);
+    }
+    function open() {
+        const ov = ctx.$('#caa');
+        if (!ov)
+            return;
+        render();
+        ov.hidden = false;
+        ctx.frontOverlay(ov);
+        const f = ov.querySelector('button');
+        if (f)
+            f.focus();
+    }
+    function close() {
+        const ov = ctx.$('#caa');
+        if (!ov)
+            return;
+        ov.hidden = true;
+        ctx.restoreFocus?.('caa');
+    }
+    const closeBtn = ctx.$('#caa-close');
+    if (closeBtn)
+        closeBtn.addEventListener('click', close);
+    // ---- restaurar os padrões DESTE menu (ADR-0028) ----
+    // O menu tem uma escolha só, então o reset é uma linha — mas vale dizer para onde ele volta: maiúsculas, que
+    // é onde a alfabetização brasileira costuma começar. Uma criança que trocou a caixa e não consegue mais ler
+    // a tela precisa de um caminho de volta que termine no que a professora dela usa.
+    const resetBtn = ctx.$('#caa-reset');
+    if (resetBtn)
+        resetBtn.addEventListener('click', () => {
+            ctx.setLetterCase(DEFAULTS.letterCase);
+            render();
+            ctx.srSay(t('sr.caa.reset'));
+        });
+    return { render, open, close };
+}

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

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { DomQuery } from '../core/dom-query.js';
+import type { KeyScheme } from '../core/entity.js';
+import type { KBDefaults } from '../input/keyboard.js';
+import type { KeydownEventLike } from '../input/keydown.js';
+/** Minimal DOM-selector shape (matches ui/dom.ts's `$`). */
+export type { DomQuery } from '../core/dom-query.js';
+/** action -> list of physical key codes (KeyboardEvent.code), e.g. {jump:['KeyJ','Space']}. */
+export type { KeyScheme } from '../core/entity.js';
+/** Opaque keyboard config (input/keyboard.ts's KBDefaults shape: {solo,p2,p3,p4}) — never indexed directly here;
+ *  all per-player reads go through the injected `kbFor`, so this module stays decoupled from its exact shape. */
+/** O `KBDefaults` de `input/keyboard`, que é o dono. Este módulo continua NÃO INDEXANDO o valor — toda
+ *  leitura por jogador passa pelo `kbFor` injetado —, e é essa disciplina que o desacopla, não um tipo largo. */
+export type KeyboardConfig = KBDefaults;
+/** Minimal persistence shape this module needs (input/keyboard.ts's saveKB/resetKB — no direct localStorage). */
+export interface ControlsStore {
+    saveKB(kb: KeyboardConfig): void;
+    resetKB(): KeyboardConfig;
+}
+export interface SettingsControlsCtx {
+    /** DOM selector (querySelector), injected — never reaches `document` globally. */
+    $: DomQuery;
+    /**
+     * AS POSIÇÕES QUE ESTE JOGO USA, cada uma com a palavra dele, no idioma vigente.
+     *
+     * ⚠️ É a fronteira do corte de 2026-09-06. A tela de remapeamento mostrava as OITO linhas de uma tabela
+     * deste ficheiro — quer dizer, a engine decidia que todo jogo tem exatamente pular, correr, trocar e
+     * especial. Um quiz mostraria quatro linhas para ações que não existem nele, e uma criança tentaria
+     * remapear um botão que não faz nada.
+     */
+    acoesDoJogo: () => readonly {
+        readonly acao: string;
+        readonly rotulo: string;
+    }[];
+    /** Screen-reader "polite" announcement (core/a11y-sr's srSay), injected. */
+    srSay: (msg: string) => void;
+    /** Screen-reader "assertive" announcement (core/a11y-sr's srAlert) — used for the capture prompt/conflict. */
+    srAlert: (msg: string) => void;
+    /** Persistence (input/keyboard.ts's saveKB/resetKB), injected. */
+    store: ControlsStore;
+    /** The live keyboard config object (game.js's `KB`). Mutated in place by successful remaps. */
+    kb: KeyboardConfig;
+    /** Replaces game.js's `KB` binding wholesale — only used by "restaurar padrões" (reset reassigns, doesn't mutate). */
+    setKB: (kb: KeyboardConfig) => void;
+    /** Shared helper (game.js): the scheme for a given player index, given `kb`/numPlayers. Not owned by this panel —
+     *  other systems (gamepad binding, HUD) call the same game.js function. */
+    kbFor: (playerIndex: number) => KeyScheme;
+    /** Shared: current player count (core/state.ts's numPlayers, read live via game.js). */
+    getNumPlayers: () => number;
+    /** Shared: propagates `kb` -> the live control aliases (game.js's applyControls). Called after remap/reset. */
+    applyControls: () => void;
+    /** Shared: propagates `kb` -> each player's `p.ctrl` (game.js's assignControls). Called after remap/reset. */
+    assignControls: () => void;
+}
+export interface SettingsControlsApi {
+    /** Re-renders #ctrl-list for the given player index and (re)wires its "Alterar" buttons. Idempotent. */
+    render: (selPlayer: number) => void;
+    /** True while a key capture is in progress (game.js's menuNavKey gates menu navigation on this). */
+    isCapturing: () => boolean;
+    /** Cancels any in-progress capture without re-rendering (dialog is closing anyway). */
+    cancelCapture: () => void;
+    /**
+     * Feeds a keydown to the in-progress capture, if any. Returns true when the event was consumed (capture was
+     * active — Escape/conflict/success all consume it) so game.js's own keydown handler can early-return exactly
+     * like the old inline `if(captureAction){...}` block did. Returns false (no-op) when nothing is being captured.
+     */
+    /** `KeydownEventLike` de `input/keydown`, que é quem escuta o teclado e portanto é dono da forma do
+     *  evento nesta engine. Este manipulador lê só `e.code` e chama `preventDefault()` — um subconjunto —,
+     *  mas pedir o `KeyboardEvent` inteiro obrigava o despacho a entregar mais do que tem (ADR-0039). */
+    handleCaptureKeydown: (e: KeydownEventLike) => boolean;
+}
+/**
+ * action key -> i18n KEY of the label shown in the panel. Also reused by main.js's openHelp() (pause-menu help
+ * screen), which is why it lives here instead of being duplicated in two places.
+ *
+ * Holds keys, not text, for the reason spelled out in input/devices: a module-level const is evaluated once at
+ * import, and core/i18n's `dict` is a `let` that setLocale reassigns — text captured here would freeze the
+ * language at boot. Resolve with `t(ACT_LABEL[a])` at the point of use.
+ */
+export declare const ACT_LABEL: Record<string, string>;
+/**
+ * ⚠️ A TABELA ACIMA E DÍVIDA DECLARADA, e o cabeçalho dela ficou desatualizado no dia em que o corte
+ * aconteceu: ela ainda diz quais são as palavras DESTE jogo — `act.run`, `act.jump` — dentro de um módulo de
+ * engine. Continua exportada porque `openHelp()` (a tela de ajuda do menu de pausa) ainda a lê, e mover as
+ * duas coisas no mesmo commit misturaria dois assuntos.
+ *
+ * O que MUDOU é quem manda: a lista de linhas e as palavras vêm agora de `ctx.acoesDoJogo()`, e esta tabela é
+ * só o que sobra para o consumidor que ainda não migrou. Quando `openHelp` perguntar ao jogo, ela sai.
+ */
+/** Physical key code -> short readable label. Only 'Space' has a word to translate; the rest are glyphs and
+ *  bare letters, identical in every language (that is why this is a chain of replaces and not a table). */
+export declare function keyName(code: string): string;
+/**
+ * Which OTHER player already owns `code`, among `schemes` (one entry per player, same order as player index) —
+ * or -1 if free. `mapRef` (the scheme currently being edited) is excluded by reference, mirroring the original
+ * `keyUsedByOther(code, mapRef)` closing over `kbFor`/numPlayers in game.js. Built over a Map (code -> owner
+ * index) so a scheme with many bound keys doesn't cost a full re-scan per lookup.
+ */
+export declare function keyUsedByOther(code: string, mapRef: KeyScheme, schemes: readonly KeyScheme[]): number;
+export declare function initSettingsControls(ctx: SettingsControlsCtx): SettingsControlsApi;

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

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/settings-controls — Keyboard-remap panel (Estágio 4): extracted from game.js's renderControls()/keyName()/
+// the captureAction+captureMapRef remap flow. Pure logic (key→label, cross-player conflict lookup) is separated
+// from the thin DOM-touching render()/handleCaptureKeydown(). DI via initSettingsControls(ctx): `$` (DOM
+// selector), `srSay`/`srAlert`, `store` (save/reset persistence), the live `kb` value + `setKB` setter, and the
+// shared per-player helpers (`kbFor`/`getNumPlayers`/`applyControls`/`assignControls`) that game.js also uses
+// elsewhere (gamepad binding, HUD, other settings panels) and therefore stay there, injected. Overlay open/close
+// plumbing (#options hidden toggle, focus management, Escape-closes-dialog) and the pad-button-design select are
+// shared/unrelated infra and stay in game.js. `openHelp()` (pause-menu help screen) reuses ACT_LABEL/keyName —
+// both are exported here instead of duplicated.
+import { t } from '../core/i18n.js';
+// ---------------------------------------------------------------------------------------------
+// Pure logic (no `document`, testable in node)
+// ---------------------------------------------------------------------------------------------
+/**
+ * action key -> i18n KEY of the label shown in the panel. Also reused by main.js's openHelp() (pause-menu help
+ * screen), which is why it lives here instead of being duplicated in two places.
+ *
+ * Holds keys, not text, for the reason spelled out in input/devices: a module-level const is evaluated once at
+ * import, and core/i18n's `dict` is a `let` that setLocale reassigns — text captured here would freeze the
+ * language at boot. Resolve with `t(ACT_LABEL[a])` at the point of use.
+ */
+export const ACT_LABEL = {
+    left: 'act.left', right: 'act.right', up: 'act.up', down: 'act.down',
+    action1: 'act.run', action2: 'act.jump', action4: 'act.swap', action3: 'act.especial',
+};
+/**
+ * ⚠️ A TABELA ACIMA E DÍVIDA DECLARADA, e o cabeçalho dela ficou desatualizado no dia em que o corte
+ * aconteceu: ela ainda diz quais são as palavras DESTE jogo — `act.run`, `act.jump` — dentro de um módulo de
+ * engine. Continua exportada porque `openHelp()` (a tela de ajuda do menu de pausa) ainda a lê, e mover as
+ * duas coisas no mesmo commit misturaria dois assuntos.
+ *
+ * O que MUDOU é quem manda: a lista de linhas e as palavras vêm agora de `ctx.acoesDoJogo()`, e esta tabela é
+ * só o que sobra para o consumidor que ainda não migrou. Quando `openHelp` perguntar ao jogo, ela sai.
+ */
+/** Physical key code -> short readable label. Only 'Space' has a word to translate; the rest are glyphs and
+ *  bare letters, identical in every language (that is why this is a chain of replaces and not a table). */
+export function keyName(code) {
+    return String(code)
+        .replace('Arrow', '↔')
+        .replace('Key', '')
+        .replace('Space', t('key.space'))
+        .replace('ShiftLeft', 'Shift')
+        .replace('ShiftRight', 'Shift');
+}
+/**
+ * Which OTHER player already owns `code`, among `schemes` (one entry per player, same order as player index) —
+ * or -1 if free. `mapRef` (the scheme currently being edited) is excluded by reference, mirroring the original
+ * `keyUsedByOther(code, mapRef)` closing over `kbFor`/numPlayers in game.js. Built over a Map (code -> owner
+ * index) so a scheme with many bound keys doesn't cost a full re-scan per lookup.
+ */
+export function keyUsedByOther(code, mapRef, schemes) {
+    const owners = new Map();
+    schemes.forEach((m, i) => {
+        if (m === mapRef)
+            return;
+        for (const a in m)
+            for (const c of m[a] || [])
+                if (!owners.has(c))
+                    owners.set(c, i);
+    });
+    return owners.get(code) ?? -1;
+}
+export function initSettingsControls(ctx) {
+    let kb = ctx.kb;
+    let capture = null;
+    let lastPlayer = 0;
+    function schemesFor() {
+        const n = ctx.getNumPlayers();
+        return Array.from({ length: n }, (_, i) => ctx.kbFor(i));
+    }
+    function render(selPlayer) {
+        const el = ctx.$('#ctrl-list');
+        if (!el)
+            return;
+        const n = ctx.getNumPlayers();
+        const player = selPlayer >= n ? 0 : selPlayer;
+        lastPlayer = player;
+        // E3: sem abas de outros jogadores — você edita só o seu controle; só o hint muda com o modo.
+        const tabs = ctx.$('#ctrl-players');
+        if (tabs) {
+            tabs.hidden = false;
+            tabs.innerHTML = `<span class="opt-hint" style="width:100%;margin:0">Editando o <strong>seu</strong> controle — modo <strong>${n === 1 ? '1 jogador' : n + ' jogadores'}</strong>.</span>`;
+        }
+        const map = ctx.kbFor(player);
+        // ⚠️ O `rotulo` SAIU DO MARKUP (issue #106) e entra logo abaixo por `textContent`. Ele é a PALAVRA do
+        // jogo — vem do preset —, e um jogo vive noutro repositório (ADR-0083): esta árvore não revê esse texto.
+        // `data-act="${a}"` fica, e a diferença é a razão: `a` é o nome ABSTRATO da ação, que a engine enumera em
+        // `core/actions`. É separação que o ADR-0086 fez, e é ela que torna um dos dois seguro e o outro não.
+        el.innerHTML = ctx.acoesDoJogo().map(({ acao: a }) => `<div class="ctrl-row"><span><b class="ctrl-nome"></b>: ${(map[a] || []).map(keyName).map((k) => `<kbd>${k}</kbd>`).join(' ')}</span>` +
+            `<button class="mode-btn" data-act="${a}" type="button" aria-label="${t('ctrl.changeKeyAria', { acao: t(ACT_LABEL[a]), n: player + 1 })}">${t('ctrl.change')}</button></div>`).join('');
+        // As palavras do jogo, por `textContent` — que escapa por construção. A ordem casa porque é a mesma lista.
+        {
+            const nomes = el.querySelectorAll('.ctrl-nome');
+            const palavras = ctx.acoesDoJogo();
+            for (let i = 0; i < nomes.length && i < palavras.length; i++)
+                nomes[i].textContent = palavras[i].rotulo;
+        }
+        el.querySelectorAll('button[data-act]').forEach((b) => {
+            b.addEventListener('click', () => {
+                const act = b.dataset.act;
+                if (!act)
+                    return;
+                capture = { action: act, mapRef: map, player };
+                b.textContent = 'Pressione…';
+                ctx.srAlert(t('sr.ctrl.pressNewKey', { acao: t(ACT_LABEL[act]), n: player + 1 }));
+            });
+        });
+    }
+    function isCapturing() {
+        return capture !== null;
+    }
+    function cancelCapture() {
+        capture = null;
+    }
+    function handleCaptureKeydown(e) {
+        if (!capture)
+            return false;
+        if (e.code === 'Escape') {
+            capture = null;
+            render(lastPlayer);
+            e.preventDefault();
+            return true;
+        }
+        const other = keyUsedByOther(e.code, capture.mapRef, schemesFor());
+        if (other >= 0) {
+            ctx.srAlert(t('sr.ctrl.keyTaken', { n: other + 1 }));
+            e.preventDefault();
+            return true; // não associa: segue capturando
+        }
+        capture.mapRef[capture.action] = [e.code];
+        ctx.store.saveKB(kb);
+        ctx.applyControls();
+        ctx.assignControls();
+        capture = null;
+        render(lastPlayer);
+        e.preventDefault();
+        return true;
+    }
+    const resetBtn = ctx.$('#ctrl-reset');
+    if (resetBtn) {
+        resetBtn.addEventListener('click', () => {
+            kb = ctx.store.resetKB();
+            ctx.setKB(kb);
+            ctx.applyControls();
+            ctx.assignControls();
+            render(lastPlayer);
+            ctx.srSay(t('sr.ctrl.reset'));
+        });
+    }
+    return { render, isCapturing, cancelCapture, handleCaptureKeydown };
+}

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

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type VizMode } from '../render/viz-modes.js';
+/**
+ * A fatia do catálogo que ESTE painel mostra: só o que SIMULA uma deficiência.
+ *
+ * Era `VIZ_MODES.filter(m => isSimKind(m.kind))`, e `kind` não distingue simular de corrigir — então as três
+ * "Correção de daltonismo" vinham junto, num menu chamado "sentir como é ter uma deficiência". A criança
+ * daltônica precisava entrar ali para achar a correção da própria condição, ao lado do botão que simula a
+ * condição dela para quem não a tem. Dois públicos opostos na mesma lista.
+ *
+ * O Dev decidiu (#60): as correções vão para a Acessibilidade visual, e a lista passa a se recortar pelo
+ * campo `sim` do catálogo, que responde a pergunta certa. `isSimKind` foi apagado — havia TRÊS cópias dele
+ * (aqui, no main.js e uma derivada morta), todas respondendo pelo `kind`, todas errando junto.
+ */
+export declare const EMPATHY_VIZ_MODES: VizMode[];
+/** On/off label shared by every toggle button in this panel (hearing, one-button, wheelchair). */
+export interface EmpathySettingsCtx {
+    /** ui/dom.ts querySelector shortcut. */
+    $<T extends Element = Element>(sel: string): T | null;
+    /** core/a11y-sr.ts screen-reader announcer. */
+    srSay(msg: string): void;
+    /** platform/storage.ts (or a test double) — read here only, to restore hearing-loss simulation on boot. */
+    store: {
+        getBool(key: string, fallback?: boolean): boolean;
+    };
+    /** Renders one viz-mode radio list (+ per-player tabs); shared with settings-visual, so it stays in game.js. */
+    renderVizGroup(listSel: string, tabsSel: string, modes: VizMode[]): void;
+    /** Reflects #opt-onebtn/#opt-wheelchair; game.js also calls it from its setOneButton/setWheelchair bodies. */
+    reflectMotorEmpathy(): void;
+    /** Reflects the #opt-visual/#opt-empathy summary buttons; shared across every viz-mode change in the game. */
+    reflectVizButtons(): void;
+    /** Brings an overlay to front + fills its footer explanations; shared by every Sensibilidade panel. */
+    frontOverlay(el: HTMLElement | null): void;
+    /** Devolve o foco a quem abriu o diálogo (ui/settings-panel `restoreFocus`). Injetado, e não um `#opt-*`
+     *  fixo: o id que este módulo focava não existe no documento, então fechar deixava o foco no `<body>`. */
+    restoreFocus?: (id: string) => boolean;
+    /** Persists + applies the audio graph change (and announces); body stays in game.js. */
+    setHearingLoss(on: boolean): void;
+    /** Persists + applies one-button-only play (and announces); body stays in game.js. */
+    setOneButton(on: boolean): void;
+    /** Persists + rebuilds world geometry for wheelchair mode (and announces); body stays in game.js. */
+    setWheelchair(on: boolean): void;
+    /** Live reads of game.js's oneButton/wheelchair booleans (not yet migrated to core/state.ts). */
+    getOneButton(): boolean;
+    getWheelchair(): boolean;
+    /** Jogadores vivos (core/state `players`), só para saber QUAL modo visual cada um está usando agora. */
+    getPlayers(): readonly {
+        viz: string;
+    }[];
+    /** Mesmo setPlayerViz do painel visual e do atalho de contraste; usado aqui só pelo "restaurar padrões". */
+    setPlayerViz(i: number, mode: string): void;
+}
+export interface EmpathySettingsApi {
+    /** Redraws the simulation list + reflects the hearing/one-button/wheelchair toggle buttons. */
+    render(): void;
+    /** Opens the #empathy overlay (renders first, fronts it, focuses its first button). */
+    open(): void;
+    /** Closes the #empathy overlay and returns focus to #opt-empathy. */
+    close(): void;
+}
+/** Wires the empathy panel's DOM (buttons + boot restore) and returns render/open/close for game.js to call. */
+export declare function initSettingsEmpathy(ctx: EmpathySettingsCtx): EmpathySettingsApi;

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

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/settings-empathy.ts — Empathy/simulation panel (Sensibilidade → Empatia): lets a player WITHOUT a disability
+// experience one (VIZ_SIM: color-blindness/low-vision/blindness simulation, simulated hearing loss, one-button
+// play, wheelchair). This is the opposite of settings-visual, which CORRECTS the game for a player who has the
+// disability — do not merge the two, even where they share the viz-mode catalog or a helper.
+// Injected via initSettingsEmpathy(ctx): DOM selector, srSay, store, the state setters (setHearingLoss/
+// setOneButton/setWheelchair — still game.js: they touch the audio graph, player powers and world geometry far
+// beyond this panel) plus their live getters, and the shared reflect/overlay helpers (renderVizGroup,
+// reflectMotorEmpathy, reflectVizButtons, frontOverlay — used by sibling panels too, so they stay in game.js).
+// Pure catalog logic (isSimKind/EMPATHY_VIZ_MODES) is unit-tested in node; render/open/close
+// are a thin DOM shell tested in browser. Model: app/js/render/fx.ts.
+import { toggleLabel } from './dom.js';
+import { VIZ_MODES, simulatesDisability } from '../render/viz-modes.js';
+import { hearingLoss, setHearingLossGraph } from '../platform/audio.js';
+import { t } from '../core/i18n.js';
+import { DEFAULTS } from '../core/state.js';
+import { markChanged, markMenuChanged } from './changed-mark.js';
+/**
+ * A fatia do catálogo que ESTE painel mostra: só o que SIMULA uma deficiência.
+ *
+ * Era `VIZ_MODES.filter(m => isSimKind(m.kind))`, e `kind` não distingue simular de corrigir — então as três
+ * "Correção de daltonismo" vinham junto, num menu chamado "sentir como é ter uma deficiência". A criança
+ * daltônica precisava entrar ali para achar a correção da própria condição, ao lado do botão que simula a
+ * condição dela para quem não a tem. Dois públicos opostos na mesma lista.
+ *
+ * O Dev decidiu (#60): as correções vão para a Acessibilidade visual, e a lista passa a se recortar pelo
+ * campo `sim` do catálogo, que responde a pergunta certa. `isSimKind` foi apagado — havia TRÊS cópias dele
+ * (aqui, no main.js e uma derivada morta), todas respondendo pelo `kind`, todas errando junto.
+ */
+export const EMPATHY_VIZ_MODES = VIZ_MODES.filter((m) => simulatesDisability(m.key));
+/** Wires the empathy panel's DOM (buttons + boot restore) and returns render/open/close for game.js to call. */
+export function initSettingsEmpathy(ctx) {
+    function render() {
+        ctx.renderVizGroup('#empathy-list', '#empathy-players', EMPATHY_VIZ_MODES);
+        const h = ctx.$('#opt-hearing');
+        if (h) {
+            h.classList.toggle('is-on', hearingLoss);
+            h.setAttribute('aria-pressed', String(hearingLoss));
+            h.textContent = toggleLabel(hearingLoss); // ui/dom
+        }
+        ctx.reflectMotorEmpathy();
+        refreshMarks();
+    }
+    /**
+     * A marca de "saiu do padrão" (ADR-0029). Neste menu ela quer dizer "esta simulação está LIGADA", e por
+     * isso é a mais útil dos sete: uma criança que ligou a simulação de cegueira está com a tela preta e não
+     * consegue ler nada — mas o leitor de tela dela percorre o menu e diz qual linha saiu do padrão.
+     *
+     * O recorte é o do reset, pelo mesmo motivo dele: as três CORREÇÕES de daltonismo que este painel lista
+     * não são deste menu. Marcá-las aqui mandaria a criança daltônica desfazer, no menu de empatia, a correção
+     * que a faz enxergar o jogo.
+     */
+    function refreshMarks() {
+        const simulando = ctx.getPlayers().some((p) => simulatesDisability(p.viz));
+        const surdez = hearingLoss;
+        const um = ctx.getOneButton() !== DEFAULTS.oneButton;
+        const cadeira = ctx.getWheelchair() !== DEFAULTS.wheelchair;
+        const linha = (sel) => ctx.$(sel)?.closest('.ctrl-row') ?? null;
+        markChanged(linha('#opt-hearing'), surdez);
+        markChanged(linha('#opt-onebtn'), um);
+        markChanged(linha('#opt-wheelchair'), cadeira);
+        markChanged(ctx.$('#empathy-list'), simulando);
+        markMenuChanged(ctx.$('[data-act="empatia"]'), [simulando, surdez, um, cadeira]);
+    }
+    function open() {
+        const ov = ctx.$('#empathy');
+        if (!ov)
+            return;
+        render();
+        ov.hidden = false;
+        ctx.frontOverlay(ov);
+        const f = ov.querySelector('button');
+        if (f)
+            f.focus();
+    }
+    function close() {
+        const ov = ctx.$('#empathy');
+        if (!ov)
+            return;
+        ov.hidden = true;
+        if (ctx.restoreFocus && ctx.restoreFocus('empathy'))
+            return;
+        const b = ctx.$('#opt-empathy');
+        if (b)
+            b.focus(); // recuo: este id nao existe no documento hoje (gancho de uma barra futura)
+    }
+    const empathyBtn = ctx.$('#opt-empathy');
+    if (empathyBtn)
+        empathyBtn.addEventListener('click', open);
+    const empathyClose = ctx.$('#empathy-close');
+    if (empathyClose)
+        empathyClose.addEventListener('click', close);
+    const hearingBtn = ctx.$('#opt-hearing');
+    if (hearingBtn)
+        hearingBtn.addEventListener('click', () => { ctx.setHearingLoss(!hearingLoss); render(); ctx.reflectVizButtons(); });
+    if (ctx.store.getBool('incl_hearingloss'))
+        setHearingLossGraph(true); // restaura o grafo de áudio persistido no boot
+    // `refreshMarks()` depois de CADA um: estes dois setters não passam por `render()` — eles refletem o botão
+    // por conta própria —, então a marca precisa ser puxada aqui ou nunca acompanha a mudança.
+    const oneBtn = ctx.$('#opt-onebtn');
+    if (oneBtn)
+        oneBtn.addEventListener('click', () => { ctx.setOneButton(!ctx.getOneButton()); refreshMarks(); });
+    const wheelBtn = ctx.$('#opt-wheelchair');
+    if (wheelBtn)
+        wheelBtn.addEventListener('click', () => { ctx.setWheelchair(!ctx.getWheelchair()); refreshMarks(); });
+    // ---- restaurar os padrões DESTE menu (ADR-0028) ----
+    //
+    // De todos os oito, este é o reset que mais precisa existir e o que mais precisa ter cuidado, pelo mesmo
+    // motivo: é o menu que simula deficiências. Uma criança que liga "Simular cegueira total" fica com a tela
+    // preta, e a saída — o toque duplo na bolinha — é justamente o que ela acabou de perder a capacidade de ver.
+    //
+    // E o cuidado: A LISTA DESTE PAINEL NÃO É A LISTA QUE O RESET DESLIGA, e a diferença é deliberada. O painel
+    // mostra também `fix-protan/fix-deuter/fix-tritan`, que são CORREÇÃO de daltonismo, porque hoje elas não têm
+    // outro lugar onde morar — o painel visual só cobre os 4 níveis de contraste. Desligá-las junto tiraria de
+    // uma criança daltônica a única correção que ela tem, a mando de um menu feito para quem não é daltônico.
+    // Por isso o reset pergunta `simulatesDisability`, que responde pelo modo, e não `isSimKind`, que responde
+    // pelo `kind` e não distingue simular de corrigir.
+    const resetBtn = ctx.$('#empathy-reset');
+    if (resetBtn)
+        resetBtn.addEventListener('click', () => {
+            // Cada setter já é idempotente e anuncia sozinho ao mudar; chamar só na diferença evita anúncio falso de
+            // "desligado" para algo que nunca esteve ligado. O anúncio-resumo vem por último, e é o que fica no
+            // `#sr-status` — uma ação, uma frase, em vez de três.
+            ctx.getPlayers().forEach((p, i) => { if (simulatesDisability(p.viz))
+                ctx.setPlayerViz(i, 'normal'); });
+            if (hearingLoss)
+                ctx.setHearingLoss(false);
+            if (ctx.getOneButton() !== DEFAULTS.oneButton)
+                ctx.setOneButton(DEFAULTS.oneButton);
+            if (ctx.getWheelchair() !== DEFAULTS.wheelchair)
+                ctx.setWheelchair(DEFAULTS.wheelchair);
+            render();
+            ctx.reflectVizButtons();
+            ctx.srSay(t('sr.empathy.reset'));
+        });
+    return { render, open, close };
+}