@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -1,97 +1,39 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/settings-visual — the "Acessibilidade visual" overlay: high-contrast level, L→Q contrast enhancement,
+// ui/settings-visual — the visual accessibility overlay: high-contrast level, L→Q contrast enhancement,
 // owner-colored items, CB-safe (Okabe-Ito) palette, color-blocking role colors, and the two outline selects
-// (foreground/background). `selVizPlayer` (chosen player), `setPlayerViz`/`setLq`/`setOwnerColors`/`setCbSafe`/
-// `setOutlineFg`/`setOutlineBg`/`setRoleColor`/`resetRoleColors` are INJECTED — they mutate PIXI texture caches
-// and rebake the world (`_rebakeDirect`/`rebuildExtras`), which stay in game.js. `numPlayers`/`players` are read
-// live from core/state.js (same source game.js itself uses). Extracted verbatim from renderVisual() in game.js
-// (behavior-preserving) — see docs/5-Refactoring/plano-modularizacao-mapa.md.
-import { toggleLabel } from './dom.js';
-import { t } from '../core/i18n.js';
-import { lqName as lqLabel } from '../render/lq-filter.js';
-import { HC_ROLE_KEYS, HC_ROLE_DEF } from '../render/hc-role-data.js';
-import { VIZ_CORRECTIONS, VIZ_MODES } from '../render/viz-modes.js';
-import { DEFAULTS } from '../core/state.js';
-// O padrao dos DOIS EIXOS (ADR-0076/#104). A marca pergunta ao modelo novo, nao ao espelho p.viz.
-import { PADRAO as PADRAO_VISUAL } from '../render/viz-axes.js';
-import { markChanged, markMenuChanged } from './changed-mark.js';
-/** Contrast levels, in cycle order — mirrors game.js's HC_SEQ (also used there by the physical contrast-cycle button). */
-export const CONTRAST_LEVELS = ['normal', 'hc-direto', 'hc-direto-45', 'hc-direto-7'];
-/**
- * TUDO que este menu escreve em `p.viz`: os 4 níveis de contraste MAIS as 3 correções de daltonismo, que
- * mudaram de casa por decisão do Dev (#60). Elas moravam no Modo empatia, onde a criança daltônica precisava
- * entrar no menu "sentir como é ter uma deficiência" para achar a correção da deficiência que ela tem.
- *
- * Os sete vivem num CONTROLE SÓ, e isso não é economia de espaço: `p.viz` guarda UM valor. Dois controles
- * separados se sobrescreveriam em silêncio — a criança escolheria a correção, depois o contraste, e perderia
- * a correção sem nada dizer que perdeu. Uma lista só conta a verdade sobre a exclusividade.
- */
-export const VISUAL_MODES = [...CONTRAST_LEVELS, ...VIZ_CORRECTIONS.map((m) => m.key)];
-const VISUAL_MODE_SET = new Set(VISUAL_MODES);
-/** Short announcement labels — mirrors game.js's HC_LABEL. */
-// Chaves i18n, não texto. Os dois extremos parecem números universais, mas '4,5:1' usa a vírgula decimal do
-// pt-BR e vira '4.5:1' em inglês — e 'off' era uma palavra inglesa dentro de uma frase em português.
-export const CONTRAST_LABELS = { normal: 'contrast.off', 'hc-direto': 'contrast.3', 'hc-direto-45': 'contrast.45', 'hc-direto-7': 'contrast.7' };
-export const ROLE_KEYS = HC_ROLE_KEYS;
-/** Readable labels for the color-blocking roles — mirrors game.js's ROLE_LBL. */
-export const ROLE_LABELS = { hazard: 'perigo (lava)', climb: 'escalável (escada/trampolim)', water: 'água', gate: 'portão' };
-// ---------- Pure logic (Right-BICEP/ZOMBIES-tested in node) ----------
-/**
- * `viz` quando ele é um modo DESTE menu (contraste ou correção), senão 'normal'.
+// (foreground/background). The selected player and `setPlayerViz`/`setLq`/`setOwnerColors`/`setCbSafe`/
+// `setOutlineFg`/`setOutlineBg`/`setRoleColor`/`resetRoleColors` are INJECTED — they reach texture caches and the
+// world, which belong to the host. The player count and players come from the round the root owns.
+import { mountSteps, updateSteps, nextStep, controlRow, labelRow } from './panel-widgets.js';
+// The DEFAULT colours of the four roles, from render/hc-role-data (a leaf, no dependencies) — the same source
+// render/high-contrast uses to repaint the tiles. Here they only say whether the child changed one.
+import { HC_ROLE_DEF } from '../render/hc-role-data.js';
+import { DEFAULTS } from '../core/setting-defaults.js';
+/*
+ * 📌 THE PURE HALF LIVES IN `ui/visual-choices` (ADR-0221), and the SUITE pointed at the seam:
+ * `tests/settings-visual.node.test.js` imports exactly those names, and the node project mounts no document — so whoever
+ * wrote those cases had to know where this panel stops being a panel.
  *
- * Chamava-se `resolveContrastValue` enquanto o menu só tinha contraste. O nome antigo passaria a mentir ao
- * devolver `fix-deuter`, e um nome que mente sobre o que devolve é pior que um nome comprido.
+ * ⚠️ NO ALIAS: a re-export would keep alive a published path nothing in here uses — surface with no consumer
+ * (issue #204).
  */
-export function resolveVisualMode(viz) {
-    return VISUAL_MODE_SET.has(viz) ? viz : 'normal';
-}
-/** i18n KEY of a contrast level's label; unknown modes fall back to the 'off' key. Resolve with `t()`. */
-export function contrastLabel(mode) {
-    return CONTRAST_LABELS[mode] ?? CONTRAST_LABELS.normal;
-}
-export function clamp01(t) {
-    return Math.max(0, Math.min(1, t));
-}
-/**
- * i18n KEY of the L->Q slider label ('lq.off'/'lq.linear'/'lq.mixed'/'lq.quadratic'). The label belongs to the
- * L->Q feature, so it lives with the filter that owns it (render/lq-filter) and is re-exported here under the
- * name this overlay has always used. Two copies of one rule is one copy too many: only the owner may change
- * what the levels mean. Callers resolve with `t()` — see the note on lqName about the `t` shadowing.
- */
-export { lqName as lqLabel } from '../render/lq-filter.js';
-/** t (0..1) -> slider percent (0..100, rounded) — mirrors `Math.round(lqT*100)`. */
-export function lqPercent(t) {
-    return Math.round(clamp01(t) * 100);
-}
-/** slider percent (any number) -> clamped t (0..1) — mirrors `+lq.value/100` fed into setLq's clamp. */
-export function lqFromPercent(pct) {
-    return clamp01(pct / 100);
-}
-/** Defensive clamp when the player count shrank — mirrors `if(selVizPlayer>=numPlayers)selVizPlayer=0`. */
-export function clampSelectedPlayer(selected, playerCount) {
-    return selected >= playerCount ? 0 : selected;
-}
-/** [r,g,b] (0..255) -> '#rrggbb' — mirrors game.js's rgbHex. */
-export function rgbToHex(rgb) {
-    return '#' + rgb.map((n) => n.toString(16).padStart(2, '0')).join('');
-}
-/** Shared on/off button label used by this panel's toggle buttons. */
-export function onOffLabel(on) {
-    return toggleLabel(on);
-}
+import { ROLE_KEYS, ROLE_LABELS, LQ_STEPS, lqLabel, lqPosition, clampSelectedPlayer, rgbToHex, onOffLabel, resolveVisualMode, VISUAL_MODES, } from './visual-choices.js';
+// The default of the TWO AXES (ADR-0076/#104). The mark asks the new model, not the p.viz mirror.
+import { DEFAULT_VISUAL as PADRAO_VISUAL } from '../render/viz-axes.js';
+import { markChanged, markMenuChanged } from './changed-mark.js';
 /**
- * Lê `player[i].visual` defensivamente, sem importar o tipo do jogador — o mesmo molde do `playerViz` abaixo,
- * e pela mesma razão: `getPlayers()` devolve `readonly unknown[]` porque o tipo real é do JOGO (ADR-0033), e
- * cada consumidor estreita para a SUA fatia.
+ * Reads `player[i].visual` defensively, without importing the player type — the same shape as `playerViz` below, for
+ * the same reason: `getPlayers()` returns `readonly unknown[]` because the real type is the GAME's (ADR-0033), and each
+ * consumer narrows to ITS slice.
  *
- * ⚠️ Sem jogador ou sem o campo, devolve o PADRÃO — que é a resposta certa para «esta criança mexeu em
- * alguma coisa?»: quem não existe não mexeu. Inventar `hc7` aqui marcaria um menu que ninguém tocou.
+ * ⚠️ With no player or no field, it returns the DEFAULT — the right answer to "did this child change anything?":
+ * whoever does not exist changed nothing. Inventing a value here would mark a menu nobody touched.
  */
 function playerVisual(list, i) {
     const v = list[i]?.visual;
     return {
-        tema: typeof v?.tema === 'string' ? v.tema : PADRAO_VISUAL.tema,
-        correcao: typeof v?.correcao === 'string' ? v.correcao : PADRAO_VISUAL.correcao,
+        theme: typeof v?.tema === 'string' ? v.tema : PADRAO_VISUAL.tema,
+        correction: typeof v?.correcao === 'string' ? v.correcao : PADRAO_VISUAL.correcao,
     };
 }
 /** Reads player[i].viz defensively (no player at that index -> 'normal'), without a Player type import. */
@@ -99,41 +41,189 @@ function playerViz(list, i) {
     const p = list[i];
     return typeof p?.viz === 'string' ? p.viz : 'normal';
 }
-/** Builds the #visual-list innerHTML — pure string templating, no DOM access. Mirrors renderVisual()'s markup. */
+const EVERY_ROW_OFFERED = { owner: true, roles: true };
+/** The OWNER-COLOURED ITEMS row, already translated. A switch. */
+function ownerRowSpec(t) {
+    return { id: 'opt-ownercolors', label: t('visual.dono'), hint: t('visual.dono.dica') };
+}
+/** The SAFE PALETTE (Okabe-Ito) row, already translated. */
+function cbSafeRowSpec(t) {
+    return { id: 'opt-cbsafe', label: t('visual.cbsafe'), hint: t('visual.cbsafe.dica') };
+}
 /**
- * Os 7 modos como o painel os OFERECE: uma lista de rádio, com nome e descrição em cada linha.
+ * Mounts this panel's inside ONCE. Called again, it RELABELS instead of rebuilding.
  *
- * A primeira versão desta mudança usou um `<select>`, e foi um erro que o Dev pegou na hora: no menu de
- * empatia as três correções eram LINHAS VISÍVEIS, com descrição; dentro de um `<select>` viraram uma linha
- * fechada dentro de uma caixa fechada. Para um controle cuja razão de existir é ser ACHADO por quem enxerga
- * mal, esconder atrás de um clique é quase o mesmo que não ter movido. Voltam a ser linhas, e pelo mesmo
- * renderizador que o painel de empatia usa — o que a criança já sabia procurar continua com a mesma cara.
+ * 🔴 Rebuilding costs more than duplicated markup: rebuilt on every render, the contrast boost's STEPS control would be
+ * a new element each time — a click on any other row would take the cursor off it —, and any node the root inserts
+ * into the list would be erased.
  *
- * Rádio, e não sete botões: `p.viz` guarda UM valor, e a exclusividade fica dita pela forma do controle em
- * vez de ser descoberta ao perder a correção que se acabou de escolher.
+ * ⚠️ Relabel and not rebuild, for the reason `labelRow` already states: listeners are wired at boot, and remaking the
+ * row would leave a control in the document with no listener — a dead button that looks alive (ADR-0106 §5).
  */
-export const VISUAL_MODE_LIST = VIZ_MODES.filter((m) => m.kind === 'normal' || m.kind === 'hcnew').concat(VIZ_CORRECTIONS);
-export function renderVisualPanelHtml(_contrastValue, s) {
-    const roleInputs = ROLE_KEYS.map((k) => `<input type="color" id="opt-role-${k}" value="${rgbToHex(s.roleColors[k])}" aria-label="Cor de ${ROLE_LABELS[k]}" style="inline-size:2.2em;block-size:1.8em;padding:0;border:1px solid #666;border-radius:4px;background:none">`).join('');
-    return ('<div class="ctrl-row"><span><strong>Realce de contraste (Linear → Quadrático)</strong> — curva de tom na tela inteira: o começo da faixa estica o contraste (linear), o fim realça sombras e altas-luzes (curva S quadrática). Zero desliga. Vale para todos os jogadores.</span>' +
-        '<span style="display:flex;align-items:center;gap:.4rem"><input type="range" id="opt-lq" min="0" max="100" step="5" style="width:9em" aria-label="Realce de contraste: zero desligado, começo linear, fim quadrático"><strong id="opt-lq-val" aria-hidden="true"></strong></span></div>' +
-        '<div class="ctrl-row"><span><strong>Itens na cor do dono</strong> — no multiplayer, cada jogador vê os próprios itens na cor dele. Desligado: itens na cor original para todos.</span>' +
-        `<button id="opt-ownercolors" class="mode-btn${s.ownerColors ? ' is-on' : ''}" type="button" aria-pressed="${s.ownerColors}">${onOffLabel(s.ownerColors)}</button></div>` +
-        '<div class="ctrl-row"><span><strong>Paleta segura para daltonismo</strong> — troca as cores de jogadores, itens e efeitos pela paleta Okabe-Ito (distinguível em protan/deutan/tritan). O cenário mantém as cores naturais.</span>' +
-        `<button id="opt-cbsafe" class="mode-btn${s.cbSafe ? ' is-on' : ''}" type="button" aria-pressed="${s.cbSafe}">${onOffLabel(s.cbSafe)}</button></div>` +
-        '<div class="ctrl-row"><span><strong>Cores do color-blocking</strong> — nos modos de alto contraste, escolha a cor de cada papel: perigo, escalável, água e portão. ↺ restaura o padrão.</span>' +
-        '<span style="display:flex;gap:.35rem;align-items:center">' +
-        roleInputs +
-        '<button id="opt-role-reset" class="mode-btn" type="button" aria-label="Restaurar cores padrão">↺</button></span></div>');
+function mountVisualInside(t, ctx, list, offered = EVERY_ROW_OFFERED) {
+    /*
+     * 🔴 THE CONTRAST BOOST, IN STEPS AND WITH THE PROSE IN THE RIGHT PLACE (ADR-0151). The explanation lives in an
+     * `.opt-hint` from birth (`CLAUDE.md` §4), and THE LABEL GOES INSIDE THE STEPS — «◀ Realce de contraste: linear ▶»
+     * (ADR-0130 errata). `render` places the control, because it knows the current position.
+     */
+    let enhanceRow = list.querySelector('.ctrl-row--passos');
+    if (!enhanceRow) {
+        enhanceRow = ctx.create('div');
+        enhanceRow.className = 'ctrl-row ctrl-row--passos';
+        const envelope = ctx.create('span');
+        const newHint = ctx.create('span');
+        newHint.className = 'opt-hint';
+        envelope.appendChild(newHint);
+        enhanceRow.appendChild(envelope);
+        const placeholder = ctx.create('span');
+        placeholder.setAttribute('data-passos-lugar', 'lq');
+        enhanceRow.appendChild(placeholder);
+        list.appendChild(enhanceRow);
+    }
+    const enhanceHint = enhanceRow.querySelector('.opt-hint');
+    if (enhanceHint)
+        enhanceHint.textContent = t('visual.lq.dica');
+    for (const spec of [...(offered.owner ? [ownerRowSpec(t)] : []), cbSafeRowSpec(t)]) {
+        const already = ctx.find('#' + spec.id)?.closest('.ctrl-row');
+        if (already)
+            labelRow(already, spec);
+        else
+            list.appendChild(controlRow(ctx, spec).row);
+    }
+    if (offered.roles)
+        mountRoleColoursRow(t, ctx, list);
 }
-/** Duas cores de papel são a mesma? Comparação por componente — `[0,0,0] === [0,0,0]` é `false` em JS, e
- *  esse `false` diria "alterado" para uma cor que ninguém tocou, mandando a criança desfazer o que não fez. */
-export function sameRgb(a, b) {
+/**
+ * The FOUR ROLES row, and the only row of this panel the kit does not build.
+ *
+ * 📌 AND NOT FOR LACK OF ANOTHER SHAPE: `controlRow` builds one label, one hint and ONE control, and this row has FIVE —
+ * four colour swatches and the ↺ that resets them. Inventing a shape for it would give a second answer to the question
+ * of what a row is, which is exactly what the kit exists to prevent. It stays in nodes with the same discipline as the
+ * rest: mounted once, relabelled after.
+ *
+ * 📌 THE FRAME TRANSLATES, THE ROLE'S NAME PASSES THROUGH (`CLAUDE.md` §A FRONTEIRA): the frame is the engine's and goes
+ * through `t()`; the role's name is the word of the GAME mounting this panel, and the engine neither translates nor
+ * invents it — it passes through `{param}`, so the sentence stays true in a cartridge with other roles.
+ */
+function mountRoleColoursRow(t, ctx, list) {
+    let row = ctx.find('#opt-role-reset')?.closest('.ctrl-row') ?? null;
+    if (!row) {
+        row = ctx.create('div');
+        row.className = 'ctrl-row';
+        const envelope = ctx.create('span');
+        envelope.appendChild(ctx.create('strong'));
+        const newHint = ctx.create('span');
+        newHint.className = 'opt-hint';
+        envelope.appendChild(newHint);
+        row.appendChild(envelope);
+        const swatches = ctx.create('span');
+        swatches.style.cssText = 'display:flex;gap:.35rem;align-items:center';
+        for (const k of ROLE_KEYS) {
+            const swatch = ctx.create('input');
+            swatch.id = 'opt-role-' + k;
+            swatch.setAttribute('type', 'color');
+            swatch.style.cssText = 'inline-size:2.2em;block-size:1.8em;padding:0;border:1px solid #666;border-radius:4px;background:none';
+            swatches.appendChild(swatch);
+        }
+        const resetButton = ctx.create('button');
+        resetButton.id = 'opt-role-reset';
+        resetButton.className = 'mode-btn';
+        resetButton.setAttribute('type', 'button');
+        resetButton.textContent = '↺';
+        swatches.appendChild(resetButton);
+        row.appendChild(swatches);
+        list.appendChild(row);
+    }
+    const label = row.querySelector('strong');
+    if (label)
+        label.textContent = t('visual.papeis');
+    const hint = row.querySelector('.opt-hint');
+    if (hint)
+        hint.textContent = t('visual.papeis.dica');
+    for (const k of ROLE_KEYS) {
+        ctx.find('#opt-role-' + k)?.setAttribute('aria-label', t('visual.papel.cor', { papel: ROLE_LABELS[k] }));
+    }
+    ctx.find('#opt-role-reset')?.setAttribute('aria-label', t('visual.papel.repor'));
+}
+/** Are two role colours the same? Compared per component — `[0,0,0] === [0,0,0]` is `false` in JS, and that `false`
+ *  would say "changed" for a colour nobody touched, sending the child to undo what they did not do. */
+// 🎯 Not published: both its readers are here, a screen away.
+function sameRgb(a, b) {
     if (!a || !b)
         return false;
     return a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
 }
 export function initSettingsVisual(ctx) {
+    const { t } = ctx;
+    /*
+     * 📌 THE KIT'S CTX COMES FROM THE LIST NODE ITSELF, not from a global `document` nor a new contract field.
+     * `ownerDocument` is the document that list LIVES in — exactly the document the rows must be born in —, so this
+     * module's global reach stays ZERO (ADR-0221) and `SettingsVisualCtx`, which is published surface, gains no required
+     * member (ADR-0172). The same shape as `ui/settings-aac`.
+     */
+    const kitCtx = (list) => ({
+        find: (sel) => ctx.$(sel),
+        create: (tag) => list.ownerDocument.createElement(tag),
+    });
+    /** The boost's position is LOCAL to the control: the injected `setLq` may not return the new value in
+     *  `getVisualSettings` until the next render, and rereading from there would move the position back. */
+    let enhanceStep = lqPosition(ctx.getVisualSettings().lq);
+    const enhanceSpec = () => ({ label: t('visual.lq'), values: LQ_STEPS.map((v) => t(lqLabel(v))), current: enhanceStep });
+    /** Listeners are wired ONCE. A second `addEventListener` on the same button gives two clicks per click. */
+    let wired = false;
+    function wireOnce(list) {
+        if (wired)
+            return;
+        wired = true;
+        const placeholder = ctx.$('[data-passos-lugar="lq"]');
+        if (placeholder) {
+            const stepper = mountSteps(kitCtx(list), enhanceSpec());
+            stepper.id = 'opt-lq';
+            placeholder.replaceWith(stepper);
+            stepper.addEventListener('passo', (ev) => {
+                const nextIndex = nextStep(enhanceStep, LQ_STEPS.length, ev.detail);
+                if (nextIndex === enhanceStep)
+                    return; // at the end, a step that did not happen is not announced
+                enhanceStep = nextIndex;
+                ctx.setLq(LQ_STEPS[enhanceStep]);
+                updateSteps(stepper, enhanceSpec());
+                ctx.srSay(t('sr.visual.lq', { v: t(lqLabel(LQ_STEPS[enhanceStep])) }));
+            });
+        }
+        const oc = ctx.$('#opt-ownercolors');
+        if (oc)
+            oc.addEventListener('click', () => { ctx.setOwnerColors(!ctx.getVisualSettings().ownerColors); render(); });
+        const cb = ctx.$('#opt-cbsafe');
+        if (cb)
+            cb.addEventListener('click', () => { ctx.setCbSafe(!ctx.getVisualSettings().cbSafe); render(); });
+        for (const k of ROLE_KEYS) {
+            const inp = ctx.$('#opt-role-' + k);
+            if (inp)
+                inp.addEventListener('change', () => ctx.setRoleColor(k, inp.value));
+        }
+        const rr = ctx.$('#opt-role-reset');
+        if (rr)
+            rr.addEventListener('click', () => { ctx.resetRoleColors(); render(); });
+    }
+    /** What the controls SHOW — the state, written on every render. */
+    function reflectControls(s) {
+        for (const [sel, on] of [['#opt-ownercolors', s.ownerColors], ['#opt-cbsafe', s.cbSafe]]) {
+            const b = ctx.$(sel);
+            if (!b)
+                continue;
+            b.classList.toggle('is-on', on);
+            b.setAttribute('aria-pressed', String(on));
+            b.textContent = onOffLabel(t, on);
+        }
+        for (const k of ROLE_KEYS) {
+            const inp = ctx.$('#opt-role-' + k);
+            if (inp)
+                inp.value = rgbToHex(s.roleColors[k]);
+        }
+        const stepper = ctx.$('#opt-lq');
+        if (stepper)
+            updateSteps(stepper, enhanceSpec());
+    }
     function reflectOutlines() {
         const s = ctx.getVisualSettings();
         const f = ctx.$('#opt-outline-fg');
@@ -161,119 +251,76 @@ export function initSettingsVisual(ctx) {
             ctx.setSelectedPlayer(selected);
         const contrastValue = resolveVisualMode(playerViz(ctx.getPlayers(), selected));
         const settings = ctx.getVisualSettings();
-        // ⚠️ `renderEixosVisuais` E NÃO `renderVizGroup` desde a #104: este painel passou a ter DOIS controles,
-        // e o `renderVizGroup` continua a servir o painel de EMPATIA, cuja lista de simulações é mesmo exclusiva.
-        // Trocar o corpo daquela função em vez de acrescentar esta teria posto os dois eixos na lista de
-        // simulações — foi o que quase aconteceu, e o que a separação impede.
-        ctx.renderEixosVisuais('#visual-modes', '#visual-players');
-        el.innerHTML = renderVisualPanelHtml(contrastValue, settings);
-        const lq = ctx.$('#opt-lq');
-        const lqv = ctx.$('#opt-lq-val');
-        if (lq) {
-            // O parâmetro chamava-se `t` e passou a `amount`: `lqLabel` agora devolve uma chave que precisa de
-            // `t()` para virar texto, e o nome antigo sombreava justamente a função que faltava chamar aqui.
-            const reflect = (amount) => {
-                if (lqv)
-                    lqv.textContent = t(lqLabel(amount));
-            };
-            lq.value = String(lqPercent(settings.lq));
-            reflect(settings.lq);
-            lq.addEventListener('input', () => {
-                const amount = lqFromPercent(Number(lq.value));
-                ctx.setLq(amount);
-                reflect(amount);
-            });
-            lq.addEventListener('change', () => {
-                ctx.srSay(t('sr.visual.lq', { v: t(lqLabel(lqFromPercent(Number(lq.value)))) }));
-            });
-        }
-        const oc = ctx.$('#opt-ownercolors');
-        if (oc)
-            oc.addEventListener('click', () => { ctx.setOwnerColors(!settings.ownerColors); render(); });
-        const cb = ctx.$('#opt-cbsafe');
-        if (cb)
-            cb.addEventListener('click', () => { ctx.setCbSafe(!settings.cbSafe); render(); });
-        for (const k of ROLE_KEYS) {
-            const inp = ctx.$('#opt-role-' + k);
-            if (inp)
-                inp.addEventListener('change', () => ctx.setRoleColor(k, inp.value));
-        }
-        const rr = ctx.$('#opt-role-reset');
-        if (rr)
-            rr.addEventListener('click', () => { ctx.resetRoleColors(); render(); });
+        // ⚠️ `renderVisualAxes` AND NOT `renderVizGroup` (#104): this panel has TWO controls, and `renderVizGroup` keeps
+        // serving the EMPATHY panel, whose simulation list really is exclusive. Changing that function's body instead of
+        // adding this one would put the two axes into the simulation list — the separation prevents it.
+        ctx.renderVisualAxes('#visual-modes', '#visual-players');
+        void contrastValue; // not read: `refreshMarks` compares through the new model, not this mirror
+        mountVisualInside(t, kitCtx(el), el, ctx.offer);
+        wireOnce(el);
+        reflectControls(settings);
         reflectOutlines();
         refreshMarks();
-        // A prosa volta para o rodapé depois de as linhas serem reconstruídas (CLAUDE.md §4, #109).
+        // The prose goes back to the footer after the rows are relabelled (CLAUDE.md §4, #109).
         ctx.fillExplain?.(ctx.$('#visual .overlay__card'));
     }
     /**
-     * A marca de "saiu do padrão" (ADR-0029). Cada linha contra o SEU padrão, e o botão do menu por cima.
+     * The left-the-default mark (ADR-0029). Each row against ITS default, and the menu's button on top.
      *
-     * O contraste é comparado pelo valor RESOLVIDO, não pelo `viz` cru: quem está com uma simulação ou uma
-     * O modo visual é comparado pelo valor RESOLVIDO: quem está com uma SIMULAÇÃO ligada (empatia) tem
-     * `resolveVisualMode` respondendo 'normal', que é a verdade sobre ESTE menu — aquele modo não saiu do
-     * padrão daqui, e é no menu de empatia que a marca precisa aparecer para levar a criança ao lugar certo.
+     * A SIMULATION switched on (empathy) does not mark THIS menu: its mark belongs to the empathy menu, and that is where it
+     * has to lead the child.
      */
     function refreshMarks() {
         const s = ctx.getVisualSettings();
         /**
-         * 🔴 A MARCA É POR EIXO DESDE 2026-09-08, e a granularidade que ela recupera foi perdida por mim na #104
-         * etapa 4d. Enquanto o `#visual-modes` era UM rádio de sete opções, marcar o contentor era marcar a
-         * escolha. A etapa 4d pôs DOIS eixos lá dentro, e uma marca no contentor deixou de dizer QUAL saiu do
-         * padrão — que é o terceiro canal do ADR-0029 a perder informação: «a criança cega percorre o menu e OUVE,
-         * em ordem, o que saiu do padrão». Ouvir «mudado» sem saber de quê manda-a procurar em oito linhas.
+         * 🔴 THE MARK IS PER AXIS. `#visual-modes` holds TWO axes, and a mark on the container would stop saying WHICH one
+         * left the default — the third channel of ADR-0029 losing information: a blind child walks the menu and HEARS, in
+         * order, what left the default. Hearing "changed" without knowing what sends them searching through every row.
          *
-         * ⚠️ E VEM DO MODELO NOVO. Isto era `resolveVisualMode(playerViz(...))`, que lê o `p.viz` que a etapa 1a
-         * marcou `@deprecated` — um leitor que ficou para trás na migração.
+         * ⚠️ AND IT COMES FROM THE NEW MODEL, not from the deprecated `p.viz`.
          *
-         * 📌 E A REGRA DA SIMULAÇÃO DEIXA DE SER DERIVADA E PASSA A SER ESTRUTURAL, que é o ganho de fundo. Ela
-         * está escrita logo acima: uma simulação de empatia não marca ESTE menu, porque a marca dela pertence ao
-         * menu de empatia e é lá que ela leva a criança. Antes isso dependia de o `resolveVisualMode` responder
-         * `normal`; agora a simulação vive noutro campo do `VisualState`, e perguntar pelo tema e pela correcção
-         * nunca a alcança.
+         * 📌 AND THE SIMULATION RULE IS STRUCTURAL: the simulation lives in another field of `VisualState`, so asking for the
+         * theme and the correction never reaches it.
          */
         const visual = playerVisual(ctx.getPlayers(), ctx.getSelectedPlayer());
-        const tema = visual.tema !== PADRAO_VISUAL.tema;
-        const correcao = visual.correcao !== PADRAO_VISUAL.correcao;
-        const linhaDoEixo = (eixo) => ctx.$(`#visual-modes button[data-eixo="${eixo}"][aria-checked="true"]`)
+        const themeChanged = visual.theme !== PADRAO_VISUAL.tema;
+        const correctionChanged = visual.correction !== PADRAO_VISUAL.correcao;
+        const rowOfCheckedAxis = (axis) => ctx.$(`#visual-modes button[data-eixo="${axis}"][aria-checked="true"]`)
             ?.closest('.ctrl-row') ?? null;
         const lqOff = s.lq !== DEFAULTS.lq;
         const owner = s.ownerColors !== DEFAULTS.ownerColors;
         const cb = s.cbSafe !== DEFAULTS.cbSafe;
         const fg = s.outlineFg !== DEFAULTS.hcOutlineFg;
         const bg = s.outlineBg !== DEFAULTS.hcOutlineBg;
-        const papeis = ROLE_KEYS.some((k) => !sameRgb(s.roleColors[k], HC_ROLE_DEF[k]));
-        const linha = (sel) => ctx.$(sel)?.closest('.ctrl-row') ?? null;
-        markChanged(linhaDoEixo('tema'), tema);
-        markChanged(linhaDoEixo('correcao'), correcao);
-        markChanged(linha('#opt-lq'), lqOff);
-        markChanged(linha('#opt-ownercolors'), owner);
-        markChanged(linha('#opt-cbsafe'), cb);
-        markChanged(linha('#opt-outline-fg'), fg);
-        markChanged(linha('#opt-outline-bg'), bg);
-        markChanged(linha('#opt-role-reset'), papeis);
-        markMenuChanged(ctx.$('[data-act="visual"]'), [tema, correcao, lqOff, owner, cb, fg, bg, papeis]);
+        const rolesChanged = ROLE_KEYS.some((k) => !sameRgb(s.roleColors[k], HC_ROLE_DEF[k]));
+        const rowOf = (sel) => ctx.$(sel)?.closest('.ctrl-row') ?? null;
+        markChanged(t, rowOfCheckedAxis('tema'), themeChanged);
+        markChanged(t, rowOfCheckedAxis('correcao'), correctionChanged);
+        markChanged(t, rowOf('#opt-lq'), lqOff);
+        markChanged(t, rowOf('#opt-ownercolors'), owner);
+        markChanged(t, rowOf('#opt-cbsafe'), cb);
+        markChanged(t, rowOf('#opt-outline-fg'), fg);
+        markChanged(t, rowOf('#opt-outline-bg'), bg);
+        markChanged(t, rowOf('#opt-role-reset'), rolesChanged);
+        markMenuChanged(t, ctx.$('[data-act="visual"]'), [themeChanged, correctionChanged, lqOff, owner, cb, fg, bg, rolesChanged]);
     }
-    // ---- restaurar os padrões DESTE menu (ADR-0028) ----
+    // ---- reset THIS menu's defaults (ADR-0028) ----
     //
-    // `p.viz` é UM campo compartilhado com o menu de empatia, então o reset só pode zerá-lo quando o que
-    // estiver lá for um modo DESTE menu. Se a criança está com uma simulação de baixa visão ou de cegueira
-    // ligada, este botão não tem nada a dizer sobre isso.
+    // `p.viz` is ONE field shared with the empathy menu, so the reset may only clear it when what is there is a mode of
+    // THIS menu. If the child has a low-vision or blindness simulation on, this button has nothing to say about it.
     //
-    // As correções de daltonismo AGORA entram no que ele zera, e isso mudou com a #60: elas passaram a morar
-    // aqui. Desfazê-las é legítimo porque a criança as reencontra no MESMO seletor que acabou de usar — a
-    // regra é "um reset só pode desfazer o que ele também consegue refazer", e aqui ela é satisfeita. Por isso
-    // o anúncio nomeia o modo visual entre o que voltou.
+    // The colour-blindness corrections ARE among what it clears: they live here (#60), and undoing them is legitimate
+    // because the child finds them again in the SAME selector they just used — a reset may only undo what it can also
+    // redo. That is why the announcement names the visual mode among what came back.
     //
-    // As LEGENDAS (#opt-captions) estão nesta tela mas ficam de fora: quem as liga e persiste é o main.js, e a
-    // pergunta de a qual menu elas pertencem está aberta (#58 — são uma acomodação de surdez morando no menu
-    // visual). Puxá-las para cá agora responderia essa pergunta por acidente, num commit sobre outra coisa.
+    // The CAPTIONS switch (#opt-captions) stays out: this panel is not given its writer, and a reset that could not
+    // reach it would announce a default it did not restore.
     const resetBtn = ctx.$('#visual-reset');
     if (resetBtn)
         resetBtn.addEventListener('click', () => {
             ctx.getPlayers().forEach((_p, i) => {
                 const viz = playerViz(ctx.getPlayers(), i);
-                if (VISUAL_MODE_SET.has(viz) && viz !== 'normal')
+                if (VISUAL_MODES.includes(viz) && viz !== 'normal')
                     ctx.setPlayerViz(i, 'normal');
             });
             const s = ctx.getVisualSettings();