@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/render/viz-setters.js

@@ -1,81 +1,77 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// render/viz-setters — APLICAÇÃO dos modos de visão acessível (daltonismo, baixa visão, cegueira, alto
-// contraste), por jogador e globalmente. Extraído verbatim do game.js. É a camada de POLÍTICA — "qual modo
-// vale onde" — e não a de FÁBRICA: quem constrói pixel (pixiFilterFor / parallaxTexFor / playerVizTex /
-// lvOverlayTex / renderVpOverlay) fica no game.js e sai depois em `render/viewports` (grupo B); esses quatro
-// entram AQUI por injeção. Ver docs/5-Refactoring/plano-modularizacao-mapa.md (A16/B2).
+// render/viz-setters — APPLYING the accessible vision modes (colour blindness, low vision, blindness, high contrast), per
+// player and globally. It is the POLICY layer — "which mode counts where" — and not the FACTORY: whoever builds pixels
+// (pixiFilterFor / parallaxTexFor / playerVizTex / lvOverlayTex / renderVpOverlay) is `render/viewports`, and those
+// come in HERE by injection.
 //
-// Fronteiras que este módulo NÃO reabre:
-//  · `_lastSharedViz` FICA no game.js — não é cache de visão, é o registro de qual modo o pipeline de render
-//    ESTÁTICO aplicou por último, escrito de cinco lugares (rebuildCoins/rebuildExtras/applySharedTextures/
-//    setPlayerViz/reapplyVizAll). Entra por `getSharedViz`/`setSharedViz`/`invalidateSharedViz`.
-//  · `selVizPlayer` idem: quatro escritores (renderVizGroup, aba de jogador, ui/settings-visual, menu de
-//    pausa) → get/set por ctx, o `let` continua no game.js até o D1.
-//  · `_playerDirect` é `let` do game.js reatribuído por estas funções → clear por ctx
-//    (binding importado não pode ser reatribuído).
+// Boundaries this module does NOT reopen:
+//  · The host keeps the "mode the STATIC render pipeline last applied" record — not a vision cache, a record several
+//    places write. It comes in through `getSharedViz`/`setSharedViz`/`invalidateSharedViz`.
+//  · The selected player of the visual panel likewise: several writers (renderVizGroup, a player tab, the visual
+//    panel, the pause menu) → get/set through the ctx.
+//  · The outlined-player-frame cache belongs to render/viewports and is reassigned by these functions → cleared through
+//    the ctx (an imported binding cannot be reassigned).
 //
-// As camadas e sprites PIXI (camera/worldSprite/parallaxLayers/decoSprites/vpSpr/vpDots) são CRIADOS no
-// game.js — a ordem de addChild é a ordem de desenho — e entram injetados por interface ESTRUTURAL, para o
-// módulo rodar no project `node` sem importar PIXI. Mesmo precedente de render/scene-sky e game/traffic.
-// SEM I/O no import: initVizSetters(ctx) só fecha closures, não chama nada.
+// The PIXI layers and sprites (camera/worldSprite/parallaxLayers/decoSprites/vpSpr/vpDots) are CREATED by the host — the
+// addChild order is the drawing order — and come in injected through a STRUCTURAL interface, so the module runs in the
+// `node` project without importing PIXI.
+// NO I/O on import: initVizSetters(ctx) only closes closures, it calls nothing.
 import { VIZ_MODES, VIZ_BY_KEY, VIZ_FILTER, simulatesDisability } from './viz-modes.js';
-import { migrarVisual, filtroChave, chaveDeTextura, chaveLegada, ehSimulacao, ehBaixaVisao, ehCego, temAltoContraste, PADRAO, } from './viz-axes.js';
-import { t } from '../core/i18n.js'; // VIZ_MODES guarda CHAVE i18n desde o item 14; quem exibe resolve
-import { eixosHtml, escolhaDoBotao, ROTULO_DO_TEMA, ROTULO_DA_CORRECAO, } from '../ui/visual-axes-panel.js';
-import { recusaDaSimulacao } from '../ui/simulation-refusal.js';
-import { DIRECT_CFG, worldTexFor, spriteTexFor, clearWorldTexCache, clearSpriteTexCache } from './high-contrast.js';
-import { pupTexFor, resetPupTexCache } from './textures.js';
-import { lqFilter } from './lq-filter.js';
-import { setVizModeValue, setModoCegoValue } from '../core/state.js';
-import * as store from '../platform/storage.js';
-/* ===================== PURO (sem PIXI, sem DOM) — o que rende teste de verdade ===================== */
+import { migrateVisual, filterKey, textureKey, legacyKey, isSimulation, isLowVision, isBlind, hasHighContrast, DEFAULT_VISUAL, } from './viz-axes.js';
+import { axesHtml, buttonChoice, THEME_LABEL, CORRECTION_LABEL, } from './viz-axes-labels.js';
+import { simulationRefusal } from './viz-refusal.js';
+import { DIRECT_CFG } from './high-contrast.js';
+import { KEYS } from '../platform/storage-keys.js';
+/* ===================== PURE (no PIXI, no DOM) — what really earns a test ===================== */
 /**
- * Até onde o filtro deste modo vai. MELHORIA alcança os menus; EMPATIA fica no mundo (ver `AlcanceDoFiltro`).
- * Derivado de `sim`, do catálogo — a mesma flag que já distingue os dois, e não uma segunda lista para
- * alguém esquecer de atualizar.
+ * How far this mode's filter reaches. ENHANCEMENT reaches the menus; EMPATHY stays in the world (see `FilterReach`).
+ * Derived from the catalogue's `sim` — the same flag that already tells the two apart, not a second list for someone
+ * to forget to update.
  */
-export function alcanceDoModo(mode) {
+export function reachOfMode(mode) {
     return simulatesDisability(mode) ? 'mundo' : 'mundo-e-menus';
 }
-/** Modo por chave, com o fallback do original: chave desconhecida (ou nula) CAI em `normal`. */
+/** The mode by key, with a fallback: an unknown (or null) key FALLS to `normal`. */
 export function resolveViz(key) {
     return VIZ_BY_KEY[key] || VIZ_BY_KEY.normal;
 }
 /**
- * O ESTADO VISUAL GUARDADO deste jogador, de qualquer das duas formas (issue #104).
+ * This player's STORED VISUAL STATE, in either of its two shapes (issue #104).
  *
- * ⚠️ ESTA FUNÇÃO É A CAIXA «um ajuste salvo antes da divisão restaura o mesmo estado visível» da definition
- * of done, e a ordem das duas leituras é a decisão inteira:
+ * ⚠️ THIS FUNCTION IS THE definition of done's box that says a setting saved before the split restores the same visible
+ * state, and the order of the two reads is the whole decision:
  *
- *   1. a chave NOVA (`visualP`), que é a única que sabe dizer dois eixos;
- *   2. na falta dela, a chave VELHA (`vizP`), que guarda a string única — e é aqui que mora o ajuste de toda
- *      criança que já jogou este jogo antes de hoje;
- *   3. na falta das duas, o padrão.
+ *   1. the NEW key (`visualP`), the only one that can express two axes;
+ *   2. without it, the OLD key (`vizP`), which keeps the single string — and where the setting of every child who
+ *      played this game before the split lives;
+ *   3. without either, the default.
  *
- * ⚠️ O RECUO NÃO É ZELO: sem ele, a primeira sessão depois da actualização apagaria o modo visual que ela
- * escolheu — e quem escolheu `fix-deuter` ou `hc-direto-7` escolheu-o porque enxerga assim. É a diferença
- * entre migrar e recomeçar.
+ * ⚠️ THE FALLBACK IS NOT ZEAL: without it, the first session after the update would erase the visual mode the child
+ * chose — and whoever chose `fix-deuter` or `hc-direto-7` chose it because that is how they see. It is the difference
+ * between migrating and starting over.
  *
- * `migrarVisual` aceita as duas formas e é idempotente, então isto pode correr quantas vezes for preciso.
+ * `migrateVisual` accepts both shapes and is idempotent, so this can run as many times as needed.
+ *
+ * 📌 THE STORE IS A PARAMETER (ADR-0232, issue #207): the page's store, built by whoever composes the page.
  */
-export function lerVisualGuardado(i) {
-    const novo = store.getJSON(store.KEYS.visualP(i), null);
-    if (novo !== null)
-        return migrarVisual(novo);
-    return migrarVisual(store.get(store.KEYS.vizP(i), null));
+export function readStoredVisual(store, i) {
+    const storedVisual = store.getJSON(KEYS.visualP(i), null);
+    if (storedVisual !== null)
+        return migrateVisual(storedVisual);
+    return migrateVisual(store.get(KEYS.vizP(i), null));
 }
-/** É um dos três níveis de Renderização Direta (alto contraste)? Mesmo teste do original: `!!DIRECT_CFG[mode]`. */
+/** Is it one of the three Direct Rendering (high contrast) levels? The test is `!!DIRECT_CFG[mode]`. */
 export function isDirectMode(mode) { return !!DIRECT_CFG[mode]; }
-/** Filtro CSS da canvas no SOLO: simulação/correção de visão + realce L→Q, compostos e sem vazios. */
+/** The canvas's CSS filter in SOLO: vision simulation/correction + the L→Q enhancement, composed and with no gaps. */
 export function cssFilterFor(mode, lq) {
     return [VIZ_FILTER[mode] || '', lq].filter(Boolean).join(' ');
 }
-/** Bolinha indicadora de um viewport: só cegueira (branca) e baixa visão (verde) acendem. */
+/** A viewport's indicator dot: only blindness (white) and low vision (green) light it. */
 export function vizDotFor(m) {
     const on = !!m && (m.kind === 'blind' || m.kind === 'lowvision');
     return { visible: on, fill: on ? (m.kind === 'blind' ? 0xffffff : 0x36d36a) : null };
 }
-/** Bolinha GLOBAL (#viz-indicator) para um `kind`: visível, classes e rótulo de leitor de tela. */
+/** The GLOBAL dot (#viz-indicator) for a `kind`: visible, classes and screen-reader label. */
 export function vizIndicatorFor(kind) {
     return {
         on: kind === 'blind' || kind === 'lowvision',
@@ -83,46 +79,47 @@ export function vizIndicatorFor(kind) {
         label: (kind === 'blind' ? 'Modo cegueira total' : 'Modo baixa visão') + '. Toque duas vezes para voltar às cores normais.',
     };
 }
-/** Classe do overlay DOM de baixa visão (`lv-haze`/`lv-tunnel`/…); '' para qualquer outro kind. */
+/** The low-vision DOM overlay's class (`lv-haze`/`lv-tunnel`/…); '' for any other kind. */
 export function lvOverlayClassFor(m) {
     return m.kind === 'lowvision' ? 'lv-' + m.lv : '';
 }
-/** HTML do grupo de rádios de modos visuais (uma linha por modo; o atual marcado). Verbatim do game.js. */
-export function vizGroupHtml(modes, cur) {
+/** The HTML of the vision modes' radio group (one row per mode; the current one marked). */
+export function vizGroupHtml(t, modes, cur) {
     return modes.map((m) => {
         const sel = m.key === cur;
-        return `<div class="ctrl-row"><span><strong>${t(m.nome)}</strong><br><span class="opt-hint" style="margin:0">${t(m.desc)}</span></span>`
+        return `<div class="ctrl-row"><span><strong>${t(m.name)}</strong><br><span class="opt-hint" style="margin:0">${t(m.desc)}</span></span>`
             + `<button class="mode-btn${sel ? ' is-on' : ''}" role="radio" aria-checked="${sel}" data-viz="${m.key}" type="button">${sel ? '✓ Selecionado' : 'Selecionar'}</button></div>`;
     }).join('');
 }
-/** Fala do leitor de tela ao escolher um modo: prefixa "Jogador N:" só em multi-tela. */
-export function vizGroupSay(numPlayers, sel, nome) {
-    return (numPlayers > 1 ? 'Jogador ' + (sel + 1) + ': ' : '') + nome + '.';
+/** The screen reader's line when a mode is chosen: prefixed with the player only on several screens. */
+export function vizGroupSay(numPlayers, sel, name) {
+    return (numPlayers > 1 ? 'Jogador ' + (sel + 1) + ': ' : '') + name + '.';
 }
 export function initVizSetters(ctx) {
-    // estáticos (mundo/parallax/moedas/itens) só re-aplicam quando o modo muda (_lastSharedViz mora no game.js)
+    const { t } = ctx;
+    // the statics (world/parallax/items) only reapply when the mode changes (the host keeps the record)
     function applySharedTextures(mode) {
         if (mode !== ctx.getSharedViz()) {
             ctx.setSharedViz(mode);
-            ctx.setFrontDim(!!DIRECT_CFG[mode]); // HC: carros/placas/semáforo (frente) escurecem como fundo
-            ctx.worldSprite.texture = worldTexFor(mode);
+            ctx.setFrontDim(!!DIRECT_CFG[mode]); // HC: foreground props darken like the background
+            ctx.worldSprite.texture = ctx.hc.worldTexFor(mode);
             ctx.parallaxLayers.forEach((ts, j) => { ts.texture = ctx.parallaxTexFor(j, mode); });
             ctx.decoSprites.forEach((s) => { s.texture = ctx.treeTexFor(mode); });
             for (const s of ctx.getItemSprites()) {
                 if (s)
-                    s.texture = spriteTexFor(ctx.itemTexId, mode);
+                    s.texture = ctx.hc.spriteTexFor(ctx.itemTexId, mode);
             }
             for (const pu of ctx.getPowerups()) {
                 if (pu.sprite)
-                    pu.sprite.texture = pupTexFor(pu.kind, mode);
+                    pu.sprite.texture = ctx.pupTexFor(pu.kind, mode);
             }
         }
         for (const pl of ctx.getPlayers()) {
             if (pl.sprite && pl._tx)
                 pl.sprite.texture = ctx.playerVizTex(pl._tx, mode);
-        } // player muda de quadro toda frame
+        } // the player changes frame every tick
     }
-    // bolinhas indicadoras por viewport (sobre os sprites de saída → NÃO sofrem o filtro do viewport, ex. cegueira)
+    // per-viewport indicator dots (over the output sprites → they do NOT get the viewport's filter, e.g. blindness)
     function updateVpDots() {
         const dots = ctx.getVpDots(), players = ctx.getPlayers();
         for (let i = 0; i < dots.length; i++) {
@@ -142,56 +139,54 @@ export function initVizSetters(ctx) {
     }
     function applyVpFilters() {
         const spr = ctx.getVpSpr(), players = ctx.getPlayers();
-        // ⚠️ `filtroChave` E NÃO `p.viz` (#104). É a outra metade do par que a etapa 0 mediu: o TEMA vai pela
-        // textura (`playerVizTex`/`applySharedTextures`) e a CORREÇÃO ou SIMULAÇÃO vai pelo FILTRO — e é
-        // exactamente por serem dois caminhos que os dois eixos podem coexistir. `null` (sem filtro) entra como
-        // `'normal'`, que é a chave que o `pixiFilterFor` já usa para «nenhum», e ele cacheia por ela.
+        // ⚠️ `filterKey` AND NOT `p.viz` (#104). The THEME goes through the texture (`playerVizTex`/`applySharedTextures`)
+        // and the CORRECTION or SIMULATION through the FILTER — and it is precisely because they are two paths that the two
+        // axes can coexist. `null` (no filter) enters as `'normal'`, the key `pixiFilterFor` already uses for "none", and it
+        // caches by it.
         for (let i = 0; i < ctx.getNumPlayers(); i++) {
             const p = players[i];
             if (spr[i])
-                spr[i].filters = ctx.pixiFilterFor((p.visual && filtroChave(p.visual)) || 'normal');
+                spr[i].filters = ctx.pixiFilterFor((p.visual && filterKey(p.visual)) || 'normal');
         }
     }
     /**
-     * O ESCRITOR DE VERDADE desde a etapa 4 da #104: recebe o ESTADO, não uma chave.
+     * THE REAL WRITER (#104): it takes the STATE, not a key.
      *
-     * ⚠️ E É AQUI QUE O ESPELHO MUDA DE SIGNIFICADO, o que estava previsto e escrito. Enquanto os controles
-     * escreviam um valor de cada vez, `viz` conseguia ser «o modo equivalente». Com dois eixos não há chave
-     * única que descreva `hc7 + fix-deuter`, então o espelho passa a ser exactamente o que ele ainda consegue
-     * ser com honestidade: **a CHAVE DE TEXTURA** — `simulação ?? tema ?? normal`, o que mais muda o que se vê.
+     * ⚠️ AND HERE THE MIRROR CHANGES MEANING. While the controls wrote one value at a time, `viz` could be "the equivalent
+     * mode". With two axes no single key describes `hc7 + fix-deuter`, so the mirror is exactly what it can still honestly
+     * be: the legacy key (`legacyKey`) — simulation, else theme, else correction, else default.
      *
-     * Isso não é uma perda escondida: é a mesma chave que o `setVizModeValue` já escreve, e o invariante do
-     * gate passou a afirmá-la nesses termos. Um leitor antigo continua a ver algo verdadeiro sobre a tela; o
-     * que ele deixa de ver é a metade que a forma antiga nunca soube dizer.
+     * It is not a hidden loss: an old reader still sees something true about the screen; what it stops seeing is the half
+     * the old shape never could say.
      */
-    function setVisualDoJogador(i, v) {
+    function writePlayerVisual(i, v) {
         const p = ctx.getPlayers()[i];
         p.visual = v;
-        p.viz = chaveLegada(v);
-        store.set(store.KEYS.vizP(i), p.viz); // legada: um leitor antigo faria `VIZ_BY_KEY[v]` e recusaria JSON
-        store.setJSON(store.KEYS.visualP(i), v); // nova: os dois eixos, que a chave velha não sabe dizer
-        aplicarVisualDoJogador(i, v);
+        p.viz = legacyKey(v);
+        ctx.store.set(KEYS.vizP(i), p.viz); // legacy: an old reader would do `VIZ_BY_KEY[v]` and refuse JSON
+        ctx.store.setJSON(KEYS.visualP(i), v); // new: the two axes, which the old key cannot say
+        applyPlayerVisual(i, v);
     }
-    /** Muda SÓ o tema deste jogador. A correção e a simulação ficam onde estavam — é o ponto da #104. */
-    function setTemaDoJogador(i, tema) {
+    /** Changes ONLY this player's theme. The correction and the simulation stay where they were — the point of #104. */
+    function writePlayerTheme(i, theme) {
         const p = ctx.getPlayers()[i];
-        setVisualDoJogador(i, { ...(p.visual ?? PADRAO), tema });
+        writePlayerVisual(i, { ...(p.visual ?? DEFAULT_VISUAL), tema: theme });
     }
-    /** Muda SÓ a correção de cor deste jogador. O tema e a simulação ficam onde estavam. */
-    function setCorrecaoDoJogador(i, correcao) {
+    /** Changes ONLY this player's colour correction. The theme and the simulation stay where they were. */
+    function writePlayerCorrection(i, correction) {
         const p = ctx.getPlayers()[i];
-        setVisualDoJogador(i, { ...(p.visual ?? PADRAO), correcao });
+        writePlayerVisual(i, { ...(p.visual ?? DEFAULT_VISUAL), correcao: correction });
     }
-    /** A API antiga, por chave única. Continua a valer: um jogo que escolhe um modo inteiro passa por aqui. */
+    /** The old API, by a single key. It still holds: a game that picks a whole mode goes through here. */
     function setPlayerViz(i, mode) {
-        setVisualDoJogador(i, migrarVisual(resolveViz(mode).key));
+        writePlayerVisual(i, migrateVisual(resolveViz(mode).key));
     }
-    /** Os efeitos colaterais de ter mudado o visual de um jogador. Separados do ESCREVER de propósito: os dois
-     *  escritores por eixo e o antigo por chave partilham-nos, e uma cópia a mais seria uma cópia a divergir. */
-    function aplicarVisualDoJogador(i, v) {
+    /** The side effects of having changed a player's visual. Separate from WRITING on purpose: the two per-axis writers
+     *  and the old per-key one share them, and one more copy would be one more copy to drift. */
+    function applyPlayerVisual(i, v) {
         ctx.invalidateSharedViz();
-        if (ehCego(v))
-            (ctx.setModoCego ?? setModoCegoValue)(true); // empatia cegueira total liga o modo cego (áudio) por padrão
+        if (isBlind(v))
+            ctx.setBlindMode(true); // total-blindness empathy turns blind mode (audio) on by default
         if (ctx.getNumPlayers() <= 1 && i === 0) {
             applyVizGlobal(v);
         }
@@ -204,64 +199,60 @@ export function initVizSetters(ctx) {
         ctx.renderEmpathyPanel();
     }
     /**
-     * ⚠️ AQUI É QUE OS DOIS EIXOS PASSAM A COEXISTIR (#104, ADR-0076), e a função nem cresceu — ela SEPAROU-SE.
+     * ⚠️ THIS IS WHERE THE TWO AXES COEXIST (#104, ADR-0076), and the function did not grow — it SPLIT.
      *
-     * Enquanto o estado era uma chave só, cada linha abaixo perguntava a mesma coisa (`mode`, `m.kind`) e a
-     * resposta tinha de ser uma. Com dois eixos, as mesmas linhas dividem-se em três grupos que nunca se
-     * tocaram — e essa é a razão de a composição já ser mecanicamente possível, como o `viz-axes` regista:
+     * With one key, every line below asked the same thing (`mode`, `m.kind`) and the answer had to be one. With two axes,
+     * the same lines fall into three groups that never touch — which is why the composition is mechanically possible, as
+     * `viz-axes` records:
      *
-     *   · TEMA (contraste) → textura e classe de DOM. `chaveDeTextura` e `temAltoContraste`.
-     *   · CORREÇÃO ou SIMULAÇÃO → filtro CSS. `filtroChave`.
-     *   · SIMULAÇÃO → as classes do corpo, o overlay, os controles de toque, a bolinha.
+     *   · THEME (contrast) → texture and DOM class. `textureKey` and `hasHighContrast`.
+     *   · CORRECTION or SIMULATION → CSS filter. `filterKey`.
+     *   · SIMULATION → the body classes, the overlay, the touch controls, the dot.
      *
-     * ⚠️ E O ALCANCE DO FILTRO CONTINUA A DEPENDER DE SIMULAR OU CORRIGIR, que é a distinção do ADR-0046: uma
-     * CORREÇÃO alcança os menus, porque a criança precisa dela para LER o menu; uma SIMULAÇÃO fica no mundo,
-     * porque quem simula tem de conseguir sair.
+     * ⚠️ AND THE FILTER'S REACH STILL DEPENDS ON SIMULATING OR CORRECTING, ADR-0046's distinction: a CORRECTION reaches the
+     * menus, because the child needs it to READ the menu; a SIMULATION stays in the world, because whoever simulates has to
+     * be able to leave.
      *
-     * `setVizModeValue` continua a escrever a chave ÚNICA legada, e a que ele escreve é a de TEXTURA — que é
-     * `simulação ?? tema ?? normal`, ou seja o que mais muda o que se vê. É espelho, não fonte: o estado a
-     * sério são os dois eixos, e esta linha sai quando o último leitor da chave velha sair.
+     * `ctx.setVizMode` keeps writing the single legacy key. It is a mirror, not a source: the real state is the two axes,
+     * and this line goes when the last reader of the old key goes.
      */
     function applyVizGlobal(v) {
-        const filtro = filtroChave(v);
-        const textura = chaveDeTextura(v);
-        // ⚠️ `chaveLegada` E NÃO `textura`: a de textura devolve `normal` para uma correção de cor, e escrevê-la
-        // aqui faria um leitor antigo da chave global perder a correção da criança. Ver a nota em `chaveLegada`.
-        setVizModeValue(chaveLegada(v)); // core/state: valor + persistência (incl_viz) + evento — espelho legado
-        // ANTES daqui saía também `ctx.setHcMode(m.kind === 'hcnew')`, alimentando um `let hcMode` no game.js cujo
-        // único leitor era o gancho window.__incl. Era `vizMode` reescrito com outro nome: derivar de VIZ_BY_KEY
-        // custa uma comparação e não pode divergir. (O inicializador daquele `let` usava OUTRA fórmula,
-        // `vizMode!=='normal'`, e discordava do setter — sem efeito, porque applyVizGlobal roda no boot antes de
-        // o gancho existir, mas é o sintoma clássico de cópia de estado.)
-        // --- eixo CORREÇÃO/SIMULAÇÃO: o filtro CSS ---
-        ctx.aplicarFiltroCss(cssFilterFor(filtro ?? '', lqFilter()), ehSimulacao(v) ? 'mundo' : 'mundo-e-menus');
-        // --- eixo TEMA: DOM e textura. Não é filtro (ver `AplicarAltoContrasteNoDom`), e é por isso que compõe.
-        ctx.aplicarAltoContrasteNoDom(temAltoContraste(v));
-        ctx.camera.filters = temAltoContraste(v) ? ctx.pixiFilterFor(textura) : null; // solo: alto contraste na câmera
-        ctx.setFrontDim(temAltoContraste(v)); // HC: frente (carros/placas/semáforo) escurece como fundo
-        ctx.worldSprite.texture = worldTexFor(textura); // alto contraste direto = Renderização Direta · resto=normal
-        ctx.parallaxLayers.forEach((ts, i) => { ts.texture = ctx.parallaxTexFor(i, textura); });
-        ctx.decoSprites.forEach((s) => { s.texture = ctx.treeTexFor(textura); });
+        const filterName = filterKey(v);
+        const textureForMode = textureKey(v);
+        // ⚠️ `legacyKey` AND NOT the texture key: that one returns `normal` for a colour correction, and writing it here
+        // would make an old reader of the global key lose the child's correction. See the note on `legacyKey`.
+        ctx.setVizMode(legacyKey(v)); // the settings store: value + persistence (incl_viz) + event — the legacy mirror
+        // There is no separate "high contrast is on" flag: deriving it from VIZ_BY_KEY costs a comparison and cannot drift,
+        // where a copied flag once disagreed with its own setter.
+        // --- the CORRECTION/SIMULATION axis: the CSS filter ---
+        ctx.applyCssFilter(cssFilterFor(filterName ?? '', ctx.lqFilter()), isSimulation(v) ? 'mundo' : 'mundo-e-menus');
+        // --- the THEME axis: DOM and texture. It is not a filter (see `ApplyHighContrastToDom`), which is why it composes.
+        ctx.applyHighContrastToDom(hasHighContrast(v));
+        ctx.camera.filters = hasHighContrast(v) ? ctx.pixiFilterFor(textureForMode) : null; // solo: high contrast on the camera
+        ctx.setFrontDim(hasHighContrast(v)); // HC: the foreground props darken like the background
+        ctx.worldSprite.texture = ctx.hc.worldTexFor(textureForMode); // direct high contrast = Direct Rendering · else normal
+        ctx.parallaxLayers.forEach((ts, i) => { ts.texture = ctx.parallaxTexFor(i, textureForMode); });
+        ctx.decoSprites.forEach((s) => { s.texture = ctx.treeTexFor(textureForMode); });
         ctx.rebuildExtras();
         ctx.rebuildCoins();
-        // --- SIMULAÇÃO: baixa visão = névoa+manchas (overlay) + bolinha verde; cegueira = tela preta + esconde
-        //     controles + bolinha branca. Nenhuma delas olha para o tema, e é por isso que o tema não as apaga.
-        ctx.body.classList.toggle('lowvision-mode', ehBaixaVisao(v));
-        ctx.body.classList.toggle('blind-mode', ehCego(v));
+        // --- SIMULATION: low vision = haze+spots (overlay) + green dot; blindness = black screen + hidden controls + white
+        //     dot. None of them looks at the theme, which is why the theme does not erase them.
+        ctx.body.classList.toggle('lowvision-mode', isLowVision(v));
+        ctx.body.classList.toggle('blind-mode', isBlind(v));
         const ov = ctx.$('#viz-overlay');
         if (ov) {
-            ov.hidden = !ehBaixaVisao(v);
-            ov.className = ehBaixaVisao(v) ? 'lv-' + String(v.simulacao).slice(3) : '';
+            ov.hidden = !isLowVision(v);
+            ov.className = isLowVision(v) ? 'lv-' + String(v.simulacao).slice(3) : '';
         }
-        if (ehCego(v)) {
+        if (isBlind(v)) {
             ctx.hideTouchControls('cegueira');
         }
-        updateVizIndicator(ehCego(v) ? 'blind' : ehBaixaVisao(v) ? 'lowvision' : 'normal');
-        ctx.reflectVizButtons(); // (a guarda `typeof ...==='function'` do original morreu: era declaração de função, sempre verdadeira)
+        updateVizIndicator(isBlind(v) ? 'blind' : isLowVision(v) ? 'lowvision' : 'normal');
+        ctx.reflectVizButtons();
         ctx.renderVisualPanel();
         ctx.renderEmpathyPanel();
     }
-    // bolinha indicadora (canto sup. dir.): branca=cegueira, verde=baixa visão; toque/clique 2× volta ao normal
+    // the indicator dot (top right corner): white=blindness, green=low vision; a double tap/click goes back to normal
     function updateVizIndicator(kind) {
         const el = ctx.$('#viz-indicator');
         if (!el)
@@ -272,14 +263,14 @@ export function initVizSetters(ctx) {
         el.classList.toggle('low', s.low);
         el.setAttribute('aria-label', s.label);
     }
-    // MP: filtro CSS/overlay/bolinha globais OFF (por viewport agora)
+    // several screens: the global CSS filter/overlay/dot OFF (per viewport now)
     function reapplyVizAll() {
         ctx.invalidateSharedViz();
         if (ctx.getNumPlayers() <= 1) {
-            applyVizGlobal(ctx.getPlayers()[0].visual ?? PADRAO);
+            applyVizGlobal(ctx.getPlayers()[0].visual ?? DEFAULT_VISUAL);
         }
         else {
-            ctx.aplicarFiltroCss(lqFilter(), 'mundo-e-menus'); // realce L/Q é melhoria: alcança o menu
+            ctx.applyCssFilter(ctx.lqFilter(), 'mundo-e-menus'); // the L/Q enhancement is an enhancement: it reaches the menu
             ctx.camera.filters = null;
             ctx.body.classList.remove('lowvision-mode', 'blind-mode');
             const ov = ctx.$('#viz-overlay');
@@ -289,15 +280,15 @@ export function initVizSetters(ctx) {
             applyVpFilters();
         }
     }
-    // invalida os caches de textura direta (mundo depende de bg; sprites de fg) e re-renderiza
+    // invalidates the direct texture caches (the world depends on bg; sprites on fg) and re-renders
     function rebakeDirect() {
-        clearWorldTexCache();
-        clearSpriteTexCache();
-        resetPupTexCache();
+        ctx.hc.clearWorldTexCache();
+        ctx.hc.clearSpriteTexCache();
+        ctx.resetPupTexCache();
         ctx.clearPlayerDirectCache();
         ctx.invalidateSharedViz();
         if (ctx.getNumPlayers() <= 1)
-            applyVizGlobal(ctx.getPlayers()[0].visual ?? PADRAO);
+            applyVizGlobal(ctx.getPlayers()[0].visual ?? DEFAULT_VISUAL);
         else
             applyVpFilters();
     }
@@ -309,10 +300,10 @@ export function initVizSetters(ctx) {
             ctx.setSelVizPlayer(0);
         const tabs = ctx.$(tabsSel);
         if (tabs) {
-            tabs.hidden = true; // E3: sem abas — cada jogador edita só o seu
+            tabs.hidden = true; // no tabs — each player edits only their own
             tabs.innerHTML = '';
-            // NOTA (verbatim do original): o innerHTML acima já esvaziou `tabs`, então este querySelectorAll não
-            // acha nada e o listener nunca é ligado. Preservado como estava — ver relatório da extração.
+            // ⚠️ DEAD CODE, kept as it was: the innerHTML above has already emptied `tabs`, so this querySelectorAll finds
+            // nothing and the listener is never wired.
             tabs.querySelectorAll('button[data-vp]').forEach((b) => b.addEventListener('click', () => {
                 ctx.setSelVizPlayer(+b.dataset.vp);
                 ctx.renderVisualPanel();
@@ -320,49 +311,49 @@ export function initVizSetters(ctx) {
             }));
         }
         const players = ctx.getPlayers(), sel = ctx.getSelVizPlayer();
-        const v = players[sel]?.visual ?? PADRAO;
-        const cur = chaveLegada(v);
-        el.innerHTML = vizGroupHtml(modes, cur);
-        // ⚠️ A RECUSA DA SIMULAÇÃO (#104, ADR-0076 §4). Com qualquer dos dois eixos fora do padrão, uma
-        // demonstração não mostra a deficiência — mostra o AJUSTE por cima do qual ela corre, e isso ensina uma
-        // coisa falsa. A linha CONTINUA na tela, desabilitada e com o motivo: sumir ensinaria que a coisa não
-        // existe, e um adulto concluiria que ela foi tirada em vez de perceber que foi ele que ligou o contraste.
+        const v = players[sel]?.visual ?? DEFAULT_VISUAL;
+        const cur = legacyKey(v);
+        el.innerHTML = vizGroupHtml(t, modes, cur);
+        // ⚠️ THE SIMULATION'S REFUSAL (#104, ADR-0076 §4). With either axis off its default, a demonstration does not show
+        // the disability — it shows the SETTING it runs over, and that teaches something false. The row STAYS on screen,
+        // disabled and with the reason: vanishing would teach that the thing does not exist, and an adult would conclude it
+        // was taken away instead of noticing they turned the contrast on themselves.
         //
-        // A prosa entra num `.opt-hint`, que é o que a casca (`ui/settings-panel.fillExplain`) MOVE para o rodapé
-        // — a regra das três zonas do CLAUDE.md: a explicação mora no rodapé, nunca na linha.
+        // The prose goes into an `.opt-hint`, which the shell (`ui/settings-panel.fillExplain`) MOVES to the footer — the
+        // three-zone rule in CLAUDE.md: the explanation lives in the footer, never in the row.
         //
-        // ⚠️ SÓ AS LINHAS QUE SIMULAM. Esta função desenha hoje a lista de simulações (o painel visual passou a
-        // usar o `renderEixosVisuais`), mas ela continua a receber os modos por parâmetro — e uma correção de
-        // cor nesta lista não deve ser recusada por causa do eixo dela própria.
-        const recusa = recusaDaSimulacao(v);
+        // ⚠️ ONLY THE ROWS THAT SIMULATE. This function draws the list of simulations (the visual panel uses
+        // `drawVisualAxes`), but it still gets the modes as a parameter — and a colour correction in this list must not be
+        // refused because of its own axis.
+        const refusal = simulationRefusal(v);
         el.querySelectorAll('button[data-viz]').forEach((btn) => {
             const key = btn.dataset.viz;
-            if (recusa && simulatesDisability(key)) {
+            if (refusal && simulatesDisability(key)) {
                 btn.setAttribute('aria-disabled', 'true');
-                const dica = btn.closest('.ctrl-row')?.querySelector('.opt-hint');
-                if (dica)
-                    dica.textContent = `${dica.textContent} ${t(recusa.chave)}`.trim();
-                return; // sem ouvinte: aceitar o clique e ignorá-lo é a outra metade do que o ADR proíbe
+                const explanation = btn.closest('.ctrl-row')?.querySelector('.opt-hint');
+                if (explanation)
+                    explanation.textContent = `${explanation.textContent} ${t(refusal.key)}`.trim();
+                return; // no listener: accepting the click and ignoring it is the other half of what the ADR forbids
             }
             btn.addEventListener('click', () => {
                 setPlayerViz(ctx.getSelVizPlayer(), key);
-                ctx.srSay(vizGroupSay(ctx.getNumPlayers(), ctx.getSelVizPlayer(), t(VIZ_MODES.find((m) => m.key === key).nome)));
+                ctx.srSay(vizGroupSay(ctx.getNumPlayers(), ctx.getSelVizPlayer(), t(VIZ_MODES.find((m) => m.key === key).name)));
             });
         });
     }
     /**
-     * OS DOIS EIXOS no painel VISUAL (#104). Irmão do `renderVizGroup`, e SEPARADO dele de propósito.
+     * The TWO AXES in the VISUAL panel (#104). The sibling of `renderVizGroup`, and SEPARATE from it on purpose.
      *
-     * ⚠️ QUASE FIZ ISTO DENTRO DO `renderVizGroup`, E TERIA PARTIDO O PAINEL DE EMPATIA. Aquela função serve os
-     * DOIS painéis — `#visual-modes` com os sete modos e `#empathy-list` com as nove simulações —, e trocar o
-     * corpo dela teria posto os dois eixos na lista de simulações. Ali o rádio único continua CERTO: as
-     * simulações são mesmo exclusivas entre si, e o que deixou de ser exclusivo foi outra coisa.
+     * ⚠️ DOING THIS INSIDE `renderVizGroup` WOULD BREAK THE EMPATHY PANEL. That function serves BOTH panels —
+     * `#visual-modes` with the seven modes and `#empathy-list` with the nine simulations —, and changing its body would put
+     * the two axes into the list of simulations. There the single radio stays RIGHT: the simulations really are exclusive
+     * among themselves; what stopped being exclusive is something else.
      *
-     * ⚠️ E OS DOIS GRUPOS ENTRAM NO CONTENEDOR QUE JÁ EXISTE, sem markup nova do hospedeiro. Exigir um elemento
-     * a mais faria cada um dos 300 jogos ter de se lembrar dele — a forma de defeito que o ADR-0106 acabou de
-     * medir em cinco jogos sem barra de acessibilidade nenhuma.
+     * ⚠️ AND THE TWO GROUPS GO INTO THE CONTAINER THAT ALREADY EXISTS, with no new host markup. Requiring one more element
+     * would make every game have to remember it — the shape of defect ADR-0106 measured in five games with no accessibility
+     * bar at all.
      */
-    function renderEixosVisuais(listSel, tabsSel) {
+    function drawVisualAxes(listSel, tabsSel) {
         const el = ctx.$(listSel);
         if (!el)
             return;
@@ -374,27 +365,27 @@ export function initVizSetters(ctx) {
             tabs.innerHTML = '';
         }
         const sel = ctx.getSelVizPlayer();
-        const v = ctx.getPlayers()[sel]?.visual ?? PADRAO;
-        el.innerHTML = eixosHtml(v, t);
+        const v = ctx.getPlayers()[sel]?.visual ?? DEFAULT_VISUAL;
+        el.innerHTML = axesHtml(v, t);
         el.querySelectorAll('button[data-eixo]').forEach((btn) => btn.addEventListener('click', () => {
-            const escolha = escolhaDoBotao(btn.dataset);
-            if (!escolha)
-                return; // botão de outro assunto, ou um `data-` editado à mão: não se adivinha
+            const choice = buttonChoice(btn.dataset);
+            if (!choice)
+                return; // a button of another subject, or a hand-edited `data-`: no guessing
             const i = ctx.getSelVizPlayer();
-            if (escolha.eixo === 'tema') {
-                setTemaDoJogador(i, escolha.valor);
-                ctx.srSay(vizGroupSay(ctx.getNumPlayers(), i, t(ROTULO_DO_TEMA[escolha.valor])));
+            if (choice.axis === 'tema') {
+                writePlayerTheme(i, choice.value);
+                ctx.srSay(vizGroupSay(ctx.getNumPlayers(), i, t(THEME_LABEL[choice.value])));
             }
             else {
-                setCorrecaoDoJogador(i, escolha.valor);
-                ctx.srSay(vizGroupSay(ctx.getNumPlayers(), i, t(ROTULO_DA_CORRECAO[escolha.valor])));
+                writePlayerCorrection(i, choice.value);
+                ctx.srSay(vizGroupSay(ctx.getNumPlayers(), i, t(CORRECTION_LABEL[choice.value])));
             }
         }));
     }
     return {
         applySharedTextures, updateVpDots, applyVpFilters, setPlayerViz, applyVizGlobal, reapplyVizAll,
-        updateVizIndicator, rebakeDirect, renderVizGroup, renderEixosVisuais,
-        // Os DOIS escritores por eixo (#104): é o que um painel de dois controles chama.
-        setVisualDoJogador, setTemaDoJogador, setCorrecaoDoJogador,
+        updateVizIndicator, rebakeDirect, renderVizGroup, renderVisualAxes: drawVisualAxes,
+        // The TWO per-axis writers (#104): what a two-control panel calls.
+        setPlayerVisual: writePlayerVisual, setPlayerTheme: writePlayerTheme, setPlayerCorrection: writePlayerCorrection,
     };
 }