@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -1,68 +1,65 @@
 // 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.
+// ui/settings-empathy.ts — Empathy/simulation panel: lets a player WITHOUT a disability experience one
+// (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.
+// setOneButton/setWheelchair — the host's: they reach far beyond this panel) plus their live getters, and the shared
+// reflect/overlay helpers (renderVizGroup, reflectMobilityEmpathy, reflectVizButtons, frontOverlay — used by sibling
+// panels too). The pure catalog slice (EMPATHY_VIZ_MODES) is unit-tested in node; render/open/close are a thin DOM
+// shell tested in browser.
 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 { DEFAULTS } from '../core/setting-defaults.js';
 import { markChanged, markMenuChanged } from './changed-mark.js';
 /**
- * A fatia do catálogo que ESTE painel mostra: só o que SIMULA uma deficiência.
+ * The slice of the catalogue THIS panel shows: only what SIMULATES a disability.
  *
- * 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.
+ * The catalogue's `kind` does not tell simulating from correcting, so a filter by `kind` brings the colour-blindness
+ * corrections into a menu about feeling what a disability is like — a colour-blind child would have to enter it to find
+ * the correction for their own condition, beside the button that simulates it for someone who does not have it. Two
+ * opposite audiences in one list.
  *
- * 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.
+ * The Dev decided (#60): the corrections live in visual accessibility, and this list is cut by `simulatesDisability`,
+ * which answers the right question.
  */
 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. */
+/** Wires the empathy panel's DOM (buttons + boot restore) and returns render/open/close for the host to call. */
 export function initSettingsEmpathy(ctx) {
+    const { t } = 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
+            h.classList.toggle('is-on', ctx.hearing.hearingLoss);
+            h.setAttribute('aria-pressed', String(ctx.hearing.hearingLoss));
+            h.textContent = toggleLabel(t, ctx.hearing.hearingLoss); // ui/dom
         }
-        ctx.reflectMotorEmpathy();
+        ctx.reflectMobilityEmpathy();
         refreshMarks();
-        // Depois do `renderVizGroup`, e não antes: é ele quem repõe o `.opt-hint` dentro das linhas.
+        // After `renderVizGroup`, not before: it is what puts the `.opt-hint` back inside the rows.
         ctx.fillExplain?.(ctx.$('#empathy .overlay__card'));
     }
     /**
-     * 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.
+     * The left-the-default mark (ADR-0029). In this menu it means this simulation is ON, which makes it the most useful
+     * of all: a child who switched on the blindness simulation has a black screen and cannot read anything — but their
+     * screen reader walks the menu and says which row left the default.
      *
-     * 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.
+     * The cut is the reset's, for the same reason: a colour-blindness CORRECTION a player chose in the visual panel is
+     * not this menu's. Marking it here would send the colour-blind child to undo, in the empathy menu, the correction
+     * that lets them see the game.
      */
     function refreshMarks() {
-        const simulando = ctx.getPlayers().some((p) => simulatesDisability(p.viz));
-        const surdez = hearingLoss;
+        const simulating = ctx.getPlayers().some((p) => simulatesDisability(p.viz));
+        const deafness = ctx.hearing.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]);
+        const wheelchair = ctx.getWheelchair() !== DEFAULTS.wheelchair;
+        const rowOf = (sel) => ctx.$(sel)?.closest('.ctrl-row') ?? null;
+        markChanged(t, rowOf('#opt-hearing'), deafness);
+        markChanged(t, rowOf('#opt-onebtn'), um);
+        markChanged(t, rowOf('#opt-wheelchair'), wheelchair);
+        markChanged(t, ctx.$('#empathy-list'), simulating);
+        markMenuChanged(t, ctx.$('[data-act="empatia"]'), [simulating, deafness, um, wheelchair]);
     }
     function open() {
         const ov = ctx.$('#empathy');
@@ -84,7 +81,7 @@ export function initSettingsEmpathy(ctx) {
             return;
         const b = ctx.$('#opt-empathy');
         if (b)
-            b.focus(); // recuo: este id nao existe no documento hoje (gancho de uma barra futura)
+            b.focus(); // fallback: this id does not exist in the document today (a hook for a future bar)
     }
     const empathyBtn = ctx.$('#opt-empathy');
     if (empathyBtn)
@@ -94,38 +91,34 @@ export function initSettingsEmpathy(ctx) {
         empathyClose.addEventListener('click', close);
     const hearingBtn = ctx.$('#opt-hearing');
     if (hearingBtn)
-        hearingBtn.addEventListener('click', () => { ctx.setHearingLoss(!hearingLoss); render(); ctx.reflectVizButtons(); });
+        hearingBtn.addEventListener('click', () => { ctx.setHearingLoss(!ctx.hearing.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.
+        ctx.hearing.setHearingLossGraph(true); // restores the persisted audio graph at boot
+    // `refreshMarks()` after EACH one: these two setters do not go through `render()` — they reflect the button on
+    // their own —, so the mark has to be pulled here or it never follows the change.
     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) ----
+    // ---- reset THIS menu's defaults (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.
+    // Of all the panels, this is the reset that most needs to exist and most needs care, for the same reason: it is the
+    // menu that simulates disabilities. A child who switches on the total-blindness simulation has a black screen.
     //
-    // 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.
+    // And the care: THE RESET ASKS `simulatesDisability`, which answers per mode. A colour-blindness CORRECTION a player
+    // chose in the visual panel is not a simulation; switching it off here would take the only correction a colour-blind
+    // child has, at the command of a menu made for whoever is not colour-blind.
     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.
+            // Each setter is idempotent and announces on its own when it changes; calling only on a difference avoids a false
+            // "off" announcement for something that was never on. The summary announcement comes last, and it is what stays in
+            // `#sr-status` — one action, one sentence, instead of three.
             ctx.getPlayers().forEach((p, i) => { if (simulatesDisability(p.viz))
                 ctx.setPlayerViz(i, 'normal'); });
-            if (hearingLoss)
+            if (ctx.hearing.hearingLoss)
                 ctx.setHearingLoss(false);
             if (ctx.getOneButton() !== DEFAULTS.oneButton)
                 ctx.setOneButton(DEFAULTS.oneButton);

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

@@ -0,0 +1,192 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { PlayerView } from '../core/entity.js';
+import type { Translate } from '../core/i18n.js';
+import type { DomQuery } from '../core/dom-query.js';
+import { type LatchPlayer as JogadorDaAlternanciaDaAresta } from '../input/latch-sync.js';
+import type { PanelShellCtx } from './panel-shell.js';
+/** Minimal platform/storage.ts shape this module needs. */
+export interface MobilityStore {
+    setBool(key: string, on: boolean): void;
+    /** Reads the raw key. Only ADR-0029's mark uses it, for one precise question: did the child CHOOSE this? */
+    get(key: string): string | null;
+}
+/** Minimal per-player shape this module reads/writes (core/state.ts's `players` entries carry much more). */
+/** The per-player mobility choices: Easy Mode and the latches. */
+export type MobilityPlayer = PlayerView<'easy' | 'toggleMove' | 'toggleRun' | 'walkDir'>;
+export interface SettingsMobilityCtx {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    /** DOM selector (querySelector), injected — never reaches `document` globally. */
+    $: DomQuery;
+    /** Screen-reader announcement (core/a11y-sr's srSay), injected. */
+    srSay: (msg: string) => void;
+    /** Persistence (platform/storage.ts), injected. */
+    store: MobilityStore;
+    /** Live player list (core/state.ts's `players` — mutated in place, same reference every call). */
+    players: MobilityPlayer[];
+    /** Live player count (core/state.ts's `numPlayers`); a getter because the value is reassigned over time. */
+    getNumPlayers: () => number;
+    /** SHARED setter (also used by the pause-menu quick icon `altmove`) — optional: the engine's `setMoveLatch` otherwise. */
+    setToggleMove?: (i: number, on: boolean) => void;
+    /**
+     * DOES THIS GAME HOLD ANY KEY? — `GameDeclaration.holdsKeys` (ADR-0115). Without it the latch row is ABSENT from this
+     * panel.
+     *
+     * ⚠️ Not offering it means making the row absent for everyone, with `hidden`, which takes it off the screen AND out of
+     * the accessibility tree — not an `aria-disabled` row that stays in the tab order doing nothing.
+     *
+     * ⚠️ REQUIRED, for the same reason as in `PauseIconsCtx`: there is no safe default. `true` leaves the row in a game
+     * where it does nothing; `false` hides it from a child who depends on it.
+     */
+    holdsKeys: boolean;
+    /**
+     * WHICH DEVICE THIS PLAYER IS USING (ADR-0113) — it travels from here to the write.
+     *
+     * ⚠️ Optional for the same reason as in `LatchWriteCtx`: without it the write does what it already did.
+     */
+    transportInUse?: (player: number) => string;
+    /**
+     * THE RUN BUTTON'S LATCH.
+     *
+     * ⚠️ OPTIONAL (ADR-0106 §1): the engine answers it itself, through `setRunLatch` — none of its steps is the game's.
+     * Whoever injects still rules.
+     */
+    setToggleRun?: (i: number, on: boolean) => void;
+    /**
+     * THE WORLD'S REACTION to Easy Mode (e.g. coins on the ground) — the game's, and therefore OPTIONAL rather than
+     * required.
+     *
+     * 📌 The default is to DO NOTHING, which is what `core/state` decides a setter does — store, persist, notify — and
+     * nothing more: game effects are REACTIONS, subscribed by whoever reacts. The child's choice is stored and holds for
+     * whoever reads it; a game without coins has nothing to rebuild, and one that has them injects its own.
+     *
+     * ⚠️ AND THE ROW STAYS ALIVE WITHOUT IT — not a dead button. `setEasy` writes `p.easy`, persists and announces before
+     * calling this; what is missing without the injection is the finishing touch in the world, not the effect.
+     */
+    rebuildCoins?: () => void;
+    /**
+     * Moves the rows' prose to the footer (`ui/settings-panel` → `fillExplain`). Called on EVERY render.
+     *
+     * ⚠️ Relabelling a row puts its `.opt-hint` back inside it — so without this call the explanation appears twice, in
+     * the footer and under the label, from the first click. `CLAUDE.md` §4 records exactly this (issue #109).
+     *
+     * Optional in the signature because a consumer can mount the panel without the shell (a test): without the shell
+     * there is no footer to duplicate.
+     */
+    fillExplain?: (card: HTMLElement | null) => void;
+}
+export interface SettingsMobilityApi {
+    /** Re-renders #movement-players (kept `hidden` — see playerTabsHTML) and (re)wires its buttons. */
+    renderMovPlayers: () => void;
+    /** Reflects the selected player's Easy Mode onto #opt-facil (+ the #opt-movement bar light). */
+    reflectEasy: () => void;
+    /** Reflects the selected player's movement latch onto #opt-altmove (+ the #opt-movement bar light). */
+    reflectAltMove: () => void;
+    /** Likewise for the RUN button's latch (#opt-togglerun). */
+    reflectToggleRun: () => void;
+    /** Sets Easy Mode for player `i`. */
+    setEasy: (i: number, on: boolean) => void;
+    /** Selects which player this panel edits (the pause actor, before opening the panel). */
+    setSelPlayer: (i: number) => void;
+    /** Currently selected player index. */
+    getSelPlayer: () => number;
+}
+/** localStorage key for a player's Modo Fácil flag (== platform/storage.ts's `easy_p{i}` pattern). */
+export declare function easyKey(i: number): string;
+/**
+ * localStorage key of the RUN button's latch, in the LEGACY form (no transport).
+ *
+ * ⚠️ IT DELEGATES to `platform/storage`, so there is one name only.
+ *
+ * ⚠️ AND IT IS THE LEGACY KEY. ADR-0104 §C put the TRANSPORT in the name, because the latch belongs to the device and not
+ * the person; this one is still read to inherit what the child already had, and is not written. The new key is
+ * `latchKey`, in `input/latch-scope`.
+ */
+export declare function toggleRunKey(i: number): string;
+/** localStorage key of the MOVEMENT latch, per player. It delegates, like the two siblings above. */
+export declare function toggleMoveKey(i: number): string;
+/**
+ * The minimal slice the movement latch's write touches.
+ *
+ * ⚠️ `walkDir` IS IN IT, and not as a detail: switching the latch off has to STOP whoever is walking by latch. Without
+ * it, the child switches the mode off and the character keeps walking by itself, with no key pressed — and no error
+ * says so.
+ *
+ * ⚠️ AND IT IS ITS OWN SLICE, not `MobilityPlayer`, because the TWO callers have different slices: the mobility panel
+ * brings `easy`/`toggleRun`, which this does not read, and `PausePlayer` brings the visual and the three reduced-motion
+ * flags. A minimal slice lets both pass without either carrying the other's.
+ *
+ * 📌 THE DEFINITION LIVES IN `input/latch-sync` (issue #127), beside the rule that uses it, and the NAME stays published
+ * here, as an alias (ADR-0106 step 1a). Since issue #204 the names snapshot reads a re-export too, so either form keeps
+ * the name in this module's snapshot.
+ */
+export type LatchPlayer = JogadorDaAlternanciaDaAresta;
+/** What the write needs to know. Everything here already lives in `SettingsMobilityCtx` and `PauseIconsCtx`. */
+export interface LatchWriteCtx {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    readonly t: Translate;
+    readonly players: readonly LatchPlayer[];
+    readonly store: {
+        setBool(key: string, on: boolean): void;
+    };
+    readonly srSay: (msg: string) => void;
+    readonly getNumPlayers: () => number;
+    /**
+     * WHICH DEVICE THIS PLAYER IS USING (ADR-0113). `input/state.inputOf(i)` answers it.
+     *
+     * ⚠️ OPTIONAL ON PURPOSE, because of what happens without it: the write falls back to exactly what it did before —
+     * only the per-player key.
+     *
+     * 📌 And it is INJECTED instead of imported: `ui/` reading `input/` module state would be a new edge between two
+     * layers, to save one argument. This ctx receives everything else that way.
+     */
+    readonly transportInUse?: (player: number) => string;
+}
+/**
+ * SWITCHES A PLAYER'S MOVEMENT LATCH ON OR OFF — the engine does it (ADR-0106 §4).
+ *
+ * ⚠️ Being shared by TWO engine surfaces (this panel and the pause bar's `altmove` icon) is a reason for the engine to
+ * own it, not for the cartridge to keep it — and every step is the engine's: `toggleMove` and `walkDir` are
+ * `PlayerBase` fields, the key is `platform/storage`'s, and `sr.motor.toggleMove*` are engine i18n keys. There is no
+ * game effect left to inject.
+ */
+export declare function setMoveLatch(ctx: LatchWriteCtx, i: number, on: boolean): void;
+/**
+ * SWITCHES THE RUN LATCH ON OR OFF — `setMoveLatch`'s sibling, and simpler.
+ *
+ * 🎯 THE SAME REASON TO EXIST: every step is the engine's — `toggleRun` is a `PlayerBase` field, the key is
+ * `platform/storage`'s `KEYS.toggleRunP(i)`, and `sr.motor.toggleRun*` are engine i18n keys. **There is no game effect
+ * to inject**, which is why `SettingsMobilityCtx.setToggleRun` is optional: a game that does not supply it still gets a
+ * live run row instead of a dead one.
+ *
+ * ⚠️ AND IT DOES NOT CALL `applyLatch`, unlike its sibling. That one stops whoever walks by latch on switch-off, because
+ * the MOVEMENT latch leaves the character walking by itself; the run latch governs a speed lock, which cannot leave anyone
+ * moving. Copying the line "for symmetry" would touch `walkDir` because of a button that does not.
+ *
+ * 📌 The announcement is UNCONDITIONAL, like its sibling's: the child pressed the button, and staying silent because the
+ * value already was that leaves the control with no answer for whoever listens instead of looking.
+ */
+export declare function setRunLatch(ctx: LatchWriteCtx, i: number, on: boolean): void;
+/**
+ * MOUNTS THIS PANEL'S INSIDE — the per-seat tabs and the three rows it reaches.
+ *
+ * 🔴 THE CONTRACT WOULD OTHERWISE BE INVISIBLE (the shape `ui/panel-shell` names one level up): this module looks for
+ * `#movement-players`, `#opt-facil`, `#opt-altmove` and `#opt-togglerun`, and nothing in the type says so — so it builds
+ * them, instead of a panel that opens with nothing but a card, a title and a reset button.
+ *
+ * ⚠️ AND IT LIVES HERE, not in the composition root: whoever knows these four ids and each control's shape is this file,
+ * and nobody else. A root writing them would be a root guessing.
+ *
+ * ⚠️ THE THREE ROWS ARE ALWAYS CREATED, the latch row included. Whether it is SEEN is decided at init by `holdsKeys`
+ * (ADR-0115), with `hidden`, which takes the row off the screen AND out of the accessibility tree. Creating it only when
+ * it applies would put the same rule in two places, and the day they diverged the row would appear in a game where it
+ * does nothing.
+ *
+ * 📌 THE ORDER IS THE DECISION, as in every menu of this project (ADR-0044 §2): the tabs first, because they say WHOSE
+ * the next choices are; then Easy Mode, the most sought; and the two latches together, the same idea applied to two
+ * buttons.
+ *
+ * Idempotent: calling it twice reuses the list instead of duplicating it.
+ */
+export declare function mountMobilityInside(t: Translate, ctx: PanelShellCtx, card: HTMLElement, list: HTMLElement): void;
+export declare function initSettingsMobility(ctx: SettingsMobilityCtx): SettingsMobilityApi;