@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/core/state.js

@@ -1,303 +1,328 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// core/state.ts — estado/cena do jogo (FONTE ÚNICA). Módulo-folha. As 8 mega-variáveis migram do game.js
-// UMA A UMA, lidas como binding vivo (import) e escritas por setter.
-// Bus mínimo (Map<evento, Set<fn>>) para os poucos leitores "de longe" que virão com os outros subsistemas.
-import * as store from '../platform/storage.js'; // persistência (as mega-vars com chave leem/gravam aqui)
-const _subs = new Map();
-/** Assina `evt`. Devolve a função que cancela — guardar o retorno é mais barato que lembrar do `off`. */
-export function on(evt, fn) {
-    if (!_subs.has(evt))
-        _subs.set(evt, new Set());
-    _subs.get(evt).add(fn);
-    return () => off(evt, fn);
-}
-export function off(evt, fn) {
-    const s = _subs.get(evt);
-    if (s)
-        s.delete(fn);
-}
+// core/state.ts — the child's settings for a ROOT (the SINGLE source it reads), built by `createSettingsStore` over the port the
+// root lends, read through live getters and written by setters, plus a minimal typed bus (Map<event, Set<fn>>) for the
+// readers "from afar" that react to a setting.
+// ⚠️ NO STORAGE IMPORT (ADR-0178, issue #174): the child's settings come through the port `createSettingsStore` receives — the
+// shape `platform/storage` already has — so `core` does not reach up to `platform` (ADR-0173).
+// 🔴 A FACTORY, NOT A MODULE OF BINDINGS (ADR-0232 D4, issue #207): the settings and the bus live in the closure a root builds,
+// so two roots on one page — and two test files — share nothing (ADR-0142). A game reads the root's store as `engine.settings`.
+import { isGameSpeed } from './game-speed.js';
+import { isCaptionRate } from './caption-duration.js';
+import { isSpeechRate } from './speech-rate.js';
+// 📌 THE VOCABULARY IS NOT HERE (ADR-0232, issue #207): the defaults and the camera positions are stateless, and a module that
+// needs only them imports `core/setting-defaults` or `core/camera-cycle`, never this store.
+import { DEFAULTS } from './setting-defaults.js';
+import { toCameraControl } from './camera-cycle.js';
+const toOutlineLevel = (v) => Math.max(0, Math.min(2, v | 0));
+/** A wait in whole milliseconds; anything that is not a positive number is off. The writer and the loader share it. */
+const toCooldown = (ms) => (Number.isFinite(ms) && ms > 0 ? Math.round(ms) : 0);
+// ========================= WHAT DOES NOT LIVE HERE (ADR-0038, cut by LIFETIME) =========================
+// This store holds what lives for the PAGE — the child's accessibility, language and device settings — and nothing
+// else; `tests/lifetime-gate.node.test.ts` asserts it on every run.
+//   · The PHASE became a stack (`core/scenes`). `phase === 'paused'` ERASED the fact that a game is underneath; the stack
+//     keeps it, and engine modules receive BOOLEANS, never the phase names (ADR-0030).
+//   · The ROUND (players, who paused, what ended) does not persist, and lives in the game's run state, not here.
+//   · A GAME's own state (its scenery, activity, level, coins) persists under the game's key and travels with the
+//     cartridge (ADR-0033, ADR-0036).
 /**
- * Avisa os assinantes de `evt`. EXPORTADO desde 2026-08-25 (item 19) porque `game/state` emite pelos mesmos
- * canais: um segundo mapa de assinantes seria um segundo barramento, e quem assinasse `coins` no lugar errado
- * simplesmente não seria avisado — sem erro, sem teste vermelho.
- *
- * O `try` em volta de cada assinante NÃO é preguiça: um ouvinte que estoura não pode impedir os outros de
- * receber. Um painel quebrado derruba o painel; não derruba o jogo.
+ * Builds a settings store over `port`, READING THE CHILD'S STORED SETTINGS FIRST (ADR-0178): the composition root builds it
+ * before anything reads or writes a setting, so no write can put a default over what the child saved. The port is
+ * REQUIRED — an optional one falling back to a shared store would be the singleton again (ADR-0232, erratum D2b).
  */
-export function emit(evt, val) {
-    const s = _subs.get(evt);
-    if (s)
-        for (const fn of s) {
-            try {
-                fn(val);
+export function createSettingsStore(port) {
+    const subs = new Map();
+    function on(evt, fn) {
+        if (!subs.has(evt))
+            subs.set(evt, new Set());
+        subs.get(evt).add(fn);
+        return () => off(evt, fn);
+    }
+    function off(evt, fn) {
+        const s = subs.get(evt);
+        if (s)
+            s.delete(fn);
+    }
+    /*
+     * The `try` around each subscriber is NOT laziness: a listener that throws must not stop the others from receiving. A
+     * broken panel brings down the panel, not the game.
+     */
+    function emit(evt, val) {
+        const s = subs.get(evt);
+        if (s)
+            for (const fn of s) {
+                try {
+                    fn(val);
+                }
+                catch (e) { /* noop */ }
             }
-            catch (e) { /* noop */ }
-        }
-}
-// ========================= `phase` SAIU DAQUI (ADR-0030 C3, passo 3 da Fase B) =========================
-// Ele não virou campo de fábrica como os outros doze de RODADA: virou uma PILHA. `core/scenes` já existia,
-// testado e sem consumidor; agora a raiz de composição o usa, e `title`/`playing`/`paused` são
-// `[titulo]`, `[jogo]` e `[jogo, pausa]`.
-//
-// A diferença que motivou a troca: `phase === 'paused'` APAGAVA a informação de que há um jogo por baixo. A
-// pilha a mantém, e é dela que sai "o mundo continua desenhado, mas não recebe tempo".
-//
-// E o ADR-0030 registra ALARGAR a união (`'mapa' | 'resultado' | …`) como NÃO-OPÇÃO: um segundo jogo
-// continuaria amarrado ao NOSSO vocabulário, e teria de pedir uma constante nova à engine para existir. Por
-// isso os três nomes não moram em módulo nenhum da engine — moram na raiz, que é este jogo. Quem é engine
-// recebe BOOLEANOS: `mundoRodando()`, `menuDePausa()`, `telaDeTitulo`. É a mesma correção que o
-// `consumer-quiz` obrigou a fazer no `menu-nav` (`getPhase()` → `isNavigable()`), registrada em
-// `core/constants` como o erro a não repetir.
-/* (`quizLevel` SAIU daqui em 2026-08-25, item 19 — está em `game/state`. É o nível da atividade de
- *  alfabetização: conteúdo pedagógico, e nem sequer mecânica de engine. A regra é a do ADR-0033, aplicada ao
- *  estado: o estado COMPARTILHADO guarda o que a engine possui — acessibilidade, idioma, dispositivo.) */
-// ========================= O RESTO DA RODADA SAIU DAQUI (ADR-0038, Fase B) =========================
-// `ended`, `decorSeed`, `grassDensity`, `selVizPlayer` e `pauseActor` foram para `core/run-state`, na
-// segunda fatia do passo 2. Nenhum deles persiste — que é o critério do corte —, e todos eram importados
-// APENAS pelo composition root, o que manteve a mudança em dois arquivos, como na primeira fatia.
-//
-// O CLAMP do `grassDensity` foi junto, e ele é a razão de aquele setter existir: a fração vinha protegida só
-// para quem entrasse pelo `window.__incl`, e qualquer outro caminho podia gravar 5 ou -1. Deixá-lo para trás
-// transformaria a fábrica num `let` com nome novo.
-//
-// E a fatia grande saiu em 2026-08-26: `players` e `numPlayers`, com quatorze importadores CADA. Com o
-// `phase` indo para a pilha de cenas no mesmo dia, a RODADA saiu INTEIRA daqui — este módulo é só de PÁGINA
-// agora, e `tests/lifetime-gate.node.test.ts` afirma isso a cada rodada de testes.
-// ========================= `cenario` E `activity` SAÍRAM DAQUI (ADR-0038, Fase B) =========================
-// Os dois eram estado de JOGO morando na engine — a mesma exceção que o `coins` e o `quizLevel` já haviam
-// deixado no item 19. O corte por LIFETIME do ADR-0038 os classifica como GAME: ambos são persistidos em
-// chave `kJogo()`, que é o critério mecânico, e ambos viajam com o cartucho quando o jogo mudar de
-// repositório (ADR-0036).
-//
-// Moram agora em `game/state`, com a MESMA forma — binding vivo + setter que persiste e emite. O que mudou
-// foi só o endereço, e é isso que torna a mudança conferível.
-//
-// Um consumidor precisou de mais que um import novo: `ui/activities-menu` é ENGINE, e o gate de fronteira
-// proíbe engine importar de `game/` (a lista dele esvaziou em 2026-08-25). Ele passou a receber
-// `getActivityId`/`setActivityId` por injeção, que é o que a raiz de composição existe para fazer.
-// --- vizMode: modo visual/cor ativo (persistido em incl_viz). A validação (VIZ_CYCLE) e o default por
-//     prefers-contrast ficam no game.js. initVizMode NÃO persiste (o default de mídia deve seguir o SO a cada
-//     boot; persistir travaria o rastreio de prefers-contrast). Mudanças do usuário usam setVizModeValue. ---
-export let vizMode = 'normal';
-export function initVizMode(mode) { vizMode = mode; }
-export function setVizModeValue(mode) { vizMode = mode; store.set('incl_viz', mode); emit('vizMode', mode); }
-/* (`coins` SAIU daqui em 2026-08-25, item 19 — está em `game/state`. Ele era `unknown[]` porque `core/` não
- *  podia conhecer o tipo, e esse `unknown` era o SINTOMA: um estado que não consegue declarar o próprio tipo
- *  está na camada errada. Do outro lado da fronteira ele é `unknown[]` ainda, mas por escolha de quem pode
- *  decidir — e o `game/coins` que o consome sabe exatamente o que há dentro.) */
-// ========================= `players` E `numPlayers` SAÍRAM DAQUI (ADR-0038, Fase B) =========================
-// Os dois são RODADA pelo critério mecânico do ADR-0038 — nenhum é persistido —, e moram em
-// `core/run-state`, na instância que a raiz de composição possui.
-//
-// O `players` era o caso mais caro de todos os treze. Um `export let` é um binding vivo COMPARTILHADO: dois
-// jogos na mesma página (que é o que a casca do `demos` faz, ADR-0036) veriam a MESMA lista, e o segundo
-// começaria com os jogadores do primeiro ainda dentro. Não haveria erro em lugar nenhum — só uma criança a
-// mais na tela.
-//
-// A referência continua sendo mutada NO LUGAR (`push`/`length`/`players[i]`), e é por isso que a rodada não
-// tem setter para ela: trocar a lista inteira deixaria para trás as referências que os módulos já guardaram.
-// Quem entra e quem sai é `game/session`, e só ele recebe a lista mutável.
-//
-// (O tipo continua sendo `Player[]` — a visão da ENGINE. Cada jogo acrescenta campos e estreita por conta
-//  própria, que é o que o ADR-0033 desenhou.)
-/**
- * OS PADRÕES, com nome. Um valor por linha, e cada um usado em DOIS lugares: a leitura do boot (quando não há
- * nada gravado) e o "restaurar padrões" do menu que o contém (ADR-0028).
- *
- * Existe porque a alternativa é escrever o mesmo padrão duas vezes — uma no `store.getBool(chave, X)` e outra
- * no reset — e este repositório já mostrou quatro vezes o que acontece com duas cópias que ninguém obriga a
- * concordar. Aqui a divergência seria pior que as anteriores: um reset que restaura um valor DIFERENTE do que
- * o jogo usa quando nunca foi configurado deixa a criança num terceiro estado, que não é nem o dela nem o de
- * fábrica, e que ela não tem como nomear para pedir ajuda.
- *
- * `as const` + `Object.freeze` de propósito: um padrão que alguém consiga escrever em tempo de execução deixa
- * de ser padrão.
- */
-/**
- * O padrão do MOVIMENTO REDUZIDO não é uma constante — é o que o sistema operacional pede.
- *
- * Mora aqui, ao lado do DEFAULTS, porque a regra do ADR-0029 é que existe UMA fonte sobre o que é padrão, e
- * um padrão calculado não deixa de ser padrão por não caber num objeto congelado. Quem lê isto: a carga do
- * boot (main.js) e o "restaurar padrões" do menu de sensibilidade visual.
- *
- * Por que importa que o reset leia isto em vez de `false`: numa máquina cujo dono pediu menos movimento,
- * devolver `false` RELIGARIA a animação — o reset passaria a fazer, sozinho, exatamente o que a WCAG 2.3.3
- * existe para impedir, e faria isso na tela de quem já tinha dito que não aguenta.
- *
- * `matchMedia` é guardado: este módulo roda no projeto `node` dos testes, onde `window` não existe.
- */
-export function defaultReducedMotion() {
-    return !!(typeof window !== 'undefined' && window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches);
-}
-export const DEFAULTS = Object.freeze({
-    // auditiva
-    modoCego: false,
-    caneBlockDiv: 1,
-    captionsOn: true,
-    menuIndexOn: true, // o indice nasce LIGADO: quem nao sabe que ele existe e quem mais precisa dele
-    // motora
-    wheelchair: false,
-    oneButton: false,
-    easy: false, // por jogador (Modo Fácil)
-    toggleMove: false, // por jogador (movimento por alternância)
-    // A alternância do botão de CORRER nasce desligada de FÁBRICA — e liga sozinha no controle de tela, que é
-    // contexto e não escolha. A distinção importa para a marca do ADR-0029: ver `refreshMarks` em
-    // ui/settings-motor, que marca a ESCOLHA guardada e não o estado.
-    toggleRun: false, // por jogador (alternância do botão de correr)
-    // visual
-    cbSafe: false,
-    ownerColors: true,
-    lq: 0, // realce de contraste L→Q desligado
-    hcOutlineFg: 1,
-    hcOutlineBg: 1,
-    // comunicação (hoje só a caixa da letra; o menu de CAA do ADR-0028 amplia isto)
-    letterCase: 'upper',
-    // ⚠️ AS DUAS ÚLTIMAS ENTRARAM EM 2026-09-07 (issue #61), e não por simetria: elas faltavam, e a falta
-    // tinha consequência. A marca do ADR-0029 lê `DEFAULTS` e mais nada — regra que continua certa —, e por
-    // isso um valor sem padrão nomeado aqui é um valor que a marca NÃO PODE marcar. Cinco dos sete ícones da
-    // barra rápida caíam nisso.
+    }
+    // --- vizMode: the active visual/colour mode (stored in incl_viz). `initVizMode` does NOT store it: a default taken from
+    //     the media query must follow the OS at every boot, and storing it would freeze the tracking of prefers-contrast. The
+    //     child's own changes go through `setVizModeValue`. ---
+    let vizMode = 'normal';
+    // --- blindMode: BLIND MODE. Only the audio aids — cane, sonar, edge guard, narration — with no black screen; the
+    //     Empathy blindness simulation is another thing and turns this on as well.
     //
-    //   · `calmMode` — o nível TEA (0 normal · 1 calmo · 2 silencioso). Além de não ter padrão, ele não
-    //     PERSISTIA: ver a nota de `KEYS.tea` em platform/storage.
-    //   · `viz` — o modo de visão. `core/entity` declara `viz: string` sem dizer qual é o padrão, e o snapshot
-    //     da barra fazia `p.viz || ''`. Funcionava por acidente: a cadeia vazia não casa `hc-direto` nem
-    //     `fix-*`, então os dois ícones ficavam apagados. `'normal'` é o modo que `render/viz-modes` declara
-    //     com `kind:'normal'` — o que não faz nada —, e passa a ser dito em vez de deduzido.
-    calmMode: 0,
-    viz: 'normal',
-});
-// --- modoCego: MODO CEGO (A12e auditiva). Só as ajudas de áudio — bengala, sonar, guarda de beirada,
-//     narração —, sem tela preta; a simulação de cegueira do Modo Empatia é outra coisa e liga esta por cima.
-//
-//     Migrado do main.js (ADR-0027 passo 4 / #50). Era a variável com MAIS encanamento de injeção do projeto:
-//     dezesseis pontos em seis módulos passavam `getModoCego`/`setModoCego` por ctx, e a colisão a lia por
-//     closure. Estado que seis módulos consultam não é do composition root; e enquanto for, `createGame()` não
-//     pode existir sem capturá-la, que é justamente o teste de fronteira que o ADR-0027 quer rodar.
-//
-//     O SETTER FAZ TRÊS COISAS E SÓ TRÊS: grava, persiste, avisa. Os efeitos que o main.js pendurava no
-//     antigo `setModoCego` — refazer os extras do nível, refletir o painel, anunciar ao leitor de tela — NÃO
-//     entram aqui: são reação, e quem reage assina o evento. Um setter que sabe redesenhar a tela é um setter
-//     que nenhum teste consegue chamar. ---
-export let modoCego = store.getBool('incl_modocego', DEFAULTS.modoCego);
-export function setModoCegoValue(on) {
-    if (modoCego === on)
-        return; // a guarda VEM DO ORIGINAL: sem ela o anúncio repetiria a cada clique redundante
-    modoCego = on;
-    store.setBool('incl_modocego', on);
-    emit('modoCego', on);
-}
-export let letterCase = store.get(store.KEYS.letterCase, DEFAULTS.letterCase) === 'upper' ? 'upper' : 'mixed';
-export function setLetterCaseValue(c) {
-    if (letterCase === c)
-        return;
-    letterCase = c;
-    store.set(store.KEYS.letterCase, c);
-    emit('letterCase', c);
-}
-export let captionsOn = store.getBool(store.KEYS.captions, DEFAULTS.captionsOn);
-export function setCaptionsOnValue(on) {
-    const v = !!on;
-    if (captionsOn === v)
-        return;
-    captionsOn = v;
-    store.setBool(store.KEYS.captions, v);
-    emit('captionsOn', v);
-}
-// --- menuIndexOn: o "6 de 10" no fim do anuncio de cada item de menu (ADR-0044, item 3).
-//
-//     NASCE LIGADO, e a razao e a mesma do modo cego nascer com TTS e sonar: quem precisa do indice para se
-//     orientar nao tem como saber que ele existe se ele vier desligado. Quem NAO precisa descobre o ajuste
-//     lendo o menu, que e justamente a coisa que essa pessoa consegue fazer.
-//
-//     PERSISTE em `incl_menuindex` (escopo da CRIANCA, ADR-0027): a preferencia segue com ela de jogo em jogo.
-export let menuIndexOn = store.getBool(store.KEYS.menuIndex, DEFAULTS.menuIndexOn);
-export function setMenuIndexOnValue(on) {
-    const v = !!on;
-    if (menuIndexOn === v)
-        return;
-    menuIndexOn = v;
-    store.setBool(store.KEYS.menuIndex, v);
-    emit('menuIndexOn', v);
-}
-// --- cbSafe: PALETA SEGURA PARA DALTONISMO (Okabe-Ito). Não é um filtro sobre a imagem — é a escolha das
-//     cores de origem, aplicada IN-PLACE em PCOLOR para que todo mundo que já referencia a array veja a troca. ---
-export let cbSafe = store.getBool(store.KEYS.cbsafe, DEFAULTS.cbSafe);
-export function setCbSafeValue(on) {
-    const v = !!on;
-    if (cbSafe === v)
-        return;
-    cbSafe = v;
-    store.setBool(store.KEYS.cbsafe, v);
-    emit('cbSafe', v);
-}
-// --- ownerColors: no multijogador, cada item aparece na cor de QUEM pode pegá-lo. Desligado, todos veem a cor
-//     original — o que é preferível para quem não distingue as cores dos donos. ---
-export let ownerColors = store.getBool(store.KEYS.ownercolors, DEFAULTS.ownerColors);
-export function setOwnerColorsValue(on) {
-    const v = !!on;
-    if (ownerColors === v)
-        return;
-    ownerColors = v;
-    store.setBool(store.KEYS.ownercolors, v);
-    emit('ownerColors', v);
-}
-const nivelContorno = (v) => Math.max(0, Math.min(2, v | 0));
-// --- hcOutlineFg / hcOutlineBg: CONTORNOS do alto contraste, e são dois porque servem a critérios diferentes.
-//     `fg` contorna o primeiro plano — personagem e itens — e atende a WCAG 2.4.7 (foco visível). `bg` contorna
-//     o perímetro externo de plataforma, água e lava, delimitando navegável × não-navegável, e atende a
-//     WCAG 1.4.11 (contraste de componente ≥ 3:1). Confundi-los apagaria uma das duas garantias.
-//
-//     A saturação em 0..2 vem do original e é dupla: no boot (contra um localStorage corrompido) e na escrita
-//     (contra um chamador). No main.js isso obrigava a declarar com um valor provisório e reatribuir na linha
-//     seguinte, porque a leitura saturada não cabia no mesmo `let`; aqui a função a resolve de uma vez. ---
-export let hcOutlineFg = nivelContorno(store.getNum(store.KEYS.outfg, DEFAULTS.hcOutlineFg));
-export function setOutlineFgValue(v) {
-    const n = nivelContorno(v);
-    if (hcOutlineFg === n)
-        return;
-    hcOutlineFg = n;
-    store.set(store.KEYS.outfg, n);
-    emit('hcOutlineFg', n);
-}
-export let hcOutlineBg = nivelContorno(store.getNum(store.KEYS.outbg, DEFAULTS.hcOutlineBg));
-export function setOutlineBgValue(v) {
-    const n = nivelContorno(v);
-    if (hcOutlineBg === n)
-        return;
-    hcOutlineBg = n;
-    store.set(store.KEYS.outbg, n);
-    emit('hcOutlineBg', n);
-}
-// --- caneBlockDiv: espaçamento da batida da BENGALA, em blocos pisados. 1 = uma batida por bloco;
-//     2 = uma batida a cada meio bloco. Não é preferência de som: é a resolução com que uma criança cega
-//     mede a distância que andou, e por isso a colisão a lê a cada passo. ---
-export let caneBlockDiv = store.getNum('incl_cane_div', DEFAULTS.caneBlockDiv) || DEFAULTS.caneBlockDiv;
-export function setCaneBlockDivValue(div) {
-    const d = (+div) || 1; // o `|| 1` vem do original: um valor corrompido no localStorage viraria NaN e a
-    if (caneBlockDiv === d)
-        return; //  bengala pararia de bater, que é o modo de falha mais silencioso possível
-    caneBlockDiv = d;
-    store.set('incl_cane_div', d);
-    emit('caneBlockDiv', d);
-}
-// --- wheelchair: MODO CADEIRANTE. Muda a geometria do nível inteiro — degraus e escada viram rampas e
-//     elevadores, moedas descem para o chão, lava vira chão, e só voo e super-corrida sobrevivem como poderes.
-//     Por isso a colisão a lê: `isSolidType` responde diferente com ela ligada. ---
-export let wheelchair = store.getBool('incl_wheelchair', DEFAULTS.wheelchair);
-export function setWheelchairValue(on) {
-    if (wheelchair === on)
-        return;
-    wheelchair = on;
-    store.setBool('incl_wheelchair', on);
-    emit('wheelchair', on);
-}
-// --- oneButton: UM BOTÃO POR VEZ. Ignora combinações simultâneas, para quem não consegue pressionar duas
-//     teclas ao mesmo tempo. ---
-export let oneButton = store.getBool('incl_onebtn', DEFAULTS.oneButton);
-export function setOneButtonValue(on) {
-    if (oneButton === on)
-        return;
-    oneButton = on;
-    store.setBool('incl_onebtn', on);
-    emit('oneButton', on);
+    //     THE SETTER DOES THREE THINGS AND ONLY THREE: stores, persists, tells. Redrawing the level, reflecting a panel,
+    //     announcing to the screen reader are REACTIONS, and whoever reacts subscribes to the event. A setter that knows how
+    //     to redraw the screen is a setter no test can call. ---
+    let blindMode = port.getBool('incl_modocego', DEFAULTS.blindMode);
+    // --- letterCase: letters show in UPPER CASE or in their natural case. A pedagogical choice, not an aesthetic one:
+    //     Brazilian literacy usually starts in upper case, and a child past that stage needs the lower case.
+    //
+    // --- captionsOn: captions for sounds (deaf accessibility).
+    //
+    //     BOTH PERSIST (ADR-0028). The Dev's answer was wider than the question: EVERY settings panel persists, and every
+    //     panel ends with a control that restores its own defaults. The reason is accessibility, not convenience — a deaf
+    //     child who turns captions on and finds them off tomorrow pays that price every day, and whoever needs the panel
+    //     most has the least margin to lose it.
+    //
+    //     The values are 'mixed' | 'upper', a choice inside the AAC panel. A stored 'lower' reads as 'mixed': the Dev asked
+    //     for two options, upper and lower case together or upper case only, and the first is text in its NATURAL case, not
+    //     text forced to lower — forcing lower case on a proper noun teaches wrong.
+    //
+    //     THE DERIVATION MATTERS: there is no `aacMode` yet, on purpose. While only the two letter cases can be chosen, a
+    //     second variable for the same question would be a duplicate state (#54). When a pictogram set can be chosen,
+    //     `aacMode` is born and `letterCase` derives from it. ---
+    let letterCase = port.get(port.KEYS.letterCase, DEFAULTS.letterCase) === 'upper' ? 'upper' : 'mixed';
+    let captionsOn = port.getBool(port.KEYS.captions, DEFAULTS.captionsOn);
+    // --- menuIndexOn: the "6 of 10" at the end of each menu item's announcement (ADR-0044, item 3).
+    //
+    //     BORN ON, for the reason blind mode is born with speech and sonar: whoever needs the index to find their way has
+    //     no way to know it exists if it arrives off. Whoever does NOT need it finds the setting by reading the menu,
+    //     which is exactly what that person can do.
+    //
+    //     STORED in `incl_menuindex` (the CHILD's scope, ADR-0027): the preference follows them from game to game. ---
+    let menuIndexOn = port.getBool(port.KEYS.menuIndex, DEFAULTS.menuIndexOn);
+    // --- cbSafe: the COLOUR-BLIND SAFE PALETTE (Okabe-Ito). Not a filter over the image — the choice of the source colours,
+    //     applied IN PLACE so everyone who already references the palette sees the change. ---
+    let cbSafe = port.getBool(port.KEYS.cbsafe, DEFAULTS.cbSafe);
+    // --- ownerColors: in multiplayer, each item shows in the colour of WHO can take it. Off, everyone sees the original
+    //     colour — preferable for whoever cannot tell the owners' colours apart. ---
+    let ownerColors = port.getBool(port.KEYS.ownercolors, DEFAULTS.ownerColors);
+    // --- hcOutlineFg / hcOutlineBg: the high-contrast OUTLINES, two because they serve different criteria. `fg` outlines
+    //     the foreground — character and items — for WCAG 2.4.7 (focus visible). `bg` outlines the outer edge of what can
+    //     and cannot be walked, for WCAG 1.4.11 (component contrast ≥ 3:1). Merging them would erase one of the guarantees.
+    //
+    //     Saturating to 0..2 happens twice: at load (against corrupted storage) and on write (against a caller). ---
+    let hcOutlineFg = toOutlineLevel(port.getNum(port.KEYS.outfg, DEFAULTS.hcOutlineFg));
+    let hcOutlineBg = toOutlineLevel(port.getNum(port.KEYS.outbg, DEFAULTS.hcOutlineBg));
+    // --- caneBlockDiv: the CANE's tap spacing, in blocks walked. 1 = one tap per block; 2 = one tap every half block. Not a
+    //     sound preference: it is the resolution at which a blind child measures how far they walked. ---
+    let caneBlockDiv = port.getNum('incl_cane_div', DEFAULTS.caneBlockDiv) || DEFAULTS.caneBlockDiv;
+    // --- wheelchair: WHEELCHAIR MODE, a game's answer to a child who plays seated: steps and ladders become ramps and lifts
+    //     in a game that has them. The engine stores and announces it; what it changes is the game's to decide. ---
+    let wheelchair = port.getBool('incl_wheelchair', DEFAULTS.wheelchair);
+    // --- oneButton: «um botão por vez», an EMPATHY SIMULATION (ADR-0181): while one game key is held, a second is never
+    //     accepted. It was described as an accommodation; the Dev: it simulates a motor difficulty. ---
+    let oneButton = port.getBool('incl_onebtn', DEFAULTS.oneButton);
+    // --- noGripStrength: «sem força para segurar botão», the second motor empathy simulation (ADR-0181): any sustained contact of a
+    //     game key reads as one tap. Stored like the other simulations, off by default. ---
+    let noGripStrength = port.getBool('incl_sem_forca', DEFAULTS.noGripStrength);
+    // --- inputCooldown: a tremor is not a second press (ADR-0217, GAG Advanced/Motor). MILLISECONDS, and 0 is off — the rule reads
+    //     the number, so «how long» and «whether» are one value and cannot disagree. Off by default: a child with no tremor would
+    //     lose half a second between every two presses, which in a game of reaction is the game. ---
+    let inputCooldown = toCooldown(port.getNum('incl_input_cooldown', DEFAULTS.inputCooldown));
+    // --- switchScan: PLAYING WITH ONE BUTTON, the third position of the quick bar's ☝️ (ADR-0218, issue #201). The scan offers the
+    //     game's declared positions one at a time and any press takes the one showing (`input/switch-scan`).
+    //     📌 ONE KEY FOR THE WHOLE ENGINE, and not one per seat like the latch beside it: this describes the CHILD'S BODY and not
+    //     the game — the switch she has in the platformer she also has in the quiz — while the latch answers «does THIS transport
+    //     need me to hold», which is why that one is kept per seat and per transport (ADR-0113).
+    //     ⚠️ NOT `oneButton` ABOVE, and the two names are a debt worth seeing: that one is the empathy SIMULATION «um botão por
+    //     vez» (ADR-0181), which makes play harder on purpose, and this is the ACCOMMODATION of the same catalogue id. The Dev
+    //     named the confusion on 2026-09-21; renaming the simulation crosses into a cartridge (`p.oneButton` in game-soccer) and
+    //     waits for its own commit. ---
+    let switchScan = port.getBool('incl_switch_scan', DEFAULTS.switchScan);
+    // --- voiceControl: PLAYING BY SPEAKING, the quick bar's 👄 (ADR-0189, ADR-0193; issue #184). The child says a word of the
+    //     game and the position it names is pressed. ONE key for the whole engine, like the camera's: it describes the CHILD, and
+    //     a voice she has in one game she has in the next. Off by default, because it opens a MICROPHONE and nothing may do that
+    //     by itself; a stored value that is not a yes reads as off. ---
+    let voiceControl = port.getBool('incl_voice_control', DEFAULTS.voiceControl);
+    // --- cameraControl: playing through the webcam, the quick bar's 📷 (ADR-0215). ONE key, so one camera mode at a time holds by
+    //     construction (ADR-0197); every playing position draws its lines. Kept on the device; the positions, their order and the
+    //     sanitiser live in `core/camera-cycle`. ---
+    let cameraControl = toCameraControl(port.get('incl_camera_control', DEFAULTS.cameraControl));
+    // --- gameSpeed: the game speed the quick bar's hourglass cycles (ADR-0180); a game hands it to `core/loop.startLoop` as its
+    //     `speed` port (ADR-0232), which multiplies the frame time by it. Stored and carried between games; a stored value
+    //     outside the steps reads as 100%. ---
+    let gameSpeed = isGameSpeed(port.getNum('incl_game_speed', DEFAULTS.gameSpeed));
+    // --- captionPpm: the child's caption reading rate, words a minute (ADR-0183 §4): how long a sound caption stays. One of
+    //     125, 145, 175; anything else reads as 125. ---
+    let captionPpm = isCaptionRate(port.getNum('incl_caption_ppm', DEFAULTS.captionPpm));
+    // --- speechPpm: the child's speech rate, words a minute (ADR-0183 §1; issue #179): each engine measures its voice and plays at
+    //     the ratio (`core/speech-rate`). One of 254…504 by 50; anything else reads as 254, the normal speed (ADR-0196). ---
+    let speechPpm = isSpeechRate(port.getNum('incl_speech_ppm', DEFAULTS.speechPpm));
+    return {
+        get vizMode() { return vizMode; },
+        get blindMode() { return blindMode; },
+        get letterCase() { return letterCase; },
+        get captionsOn() { return captionsOn; },
+        get menuIndexOn() { return menuIndexOn; },
+        get cbSafe() { return cbSafe; },
+        get ownerColors() { return ownerColors; },
+        get hcOutlineFg() { return hcOutlineFg; },
+        get hcOutlineBg() { return hcOutlineBg; },
+        get caneBlockDiv() { return caneBlockDiv; },
+        get wheelchair() { return wheelchair; },
+        get oneButton() { return oneButton; },
+        get noGripStrength() { return noGripStrength; },
+        get inputCooldown() { return inputCooldown; },
+        get switchScan() { return switchScan; },
+        get voiceControl() { return voiceControl; },
+        get cameraControl() { return cameraControl; },
+        get gameSpeed() { return gameSpeed; },
+        get captionPpm() { return captionPpm; },
+        get speechPpm() { return speechPpm; },
+        initVizMode(mode) { vizMode = mode; },
+        setVizModeValue(mode) { port.set('incl_viz', mode); vizMode = mode; emit('vizMode', mode); },
+        setBlindModeValue(on) {
+            if (blindMode === on)
+                return; // without this guard the announcement would repeat on every redundant click
+            port.setBool('incl_modocego', on);
+            blindMode = on;
+            emit('blindMode', on);
+        },
+        setLetterCaseValue(c) {
+            if (letterCase === c)
+                return;
+            port.set(port.KEYS.letterCase, c);
+            letterCase = c;
+            emit('letterCase', c);
+        },
+        setCaptionsOnValue(on) {
+            const v = !!on;
+            if (captionsOn === v)
+                return;
+            port.setBool(port.KEYS.captions, v);
+            captionsOn = v;
+            emit('captionsOn', v);
+        },
+        setMenuIndexOnValue(on) {
+            const v = !!on;
+            if (menuIndexOn === v)
+                return;
+            port.setBool(port.KEYS.menuIndex, v);
+            menuIndexOn = v;
+            emit('menuIndexOn', v);
+        },
+        setCbSafeValue(on) {
+            const v = !!on;
+            if (cbSafe === v)
+                return;
+            port.setBool(port.KEYS.cbsafe, v);
+            cbSafe = v;
+            emit('cbSafe', v);
+        },
+        setOwnerColorsValue(on) {
+            const v = !!on;
+            if (ownerColors === v)
+                return;
+            port.setBool(port.KEYS.ownercolors, v);
+            ownerColors = v;
+            emit('ownerColors', v);
+        },
+        setOutlineFgValue(v) {
+            const n = toOutlineLevel(v);
+            if (hcOutlineFg === n)
+                return;
+            port.set(port.KEYS.outfg, n);
+            hcOutlineFg = n;
+            emit('hcOutlineFg', n);
+        },
+        setOutlineBgValue(v) {
+            const n = toOutlineLevel(v);
+            if (hcOutlineBg === n)
+                return;
+            port.set(port.KEYS.outbg, n);
+            hcOutlineBg = n;
+            emit('hcOutlineBg', n);
+        },
+        setCaneBlockDivValue(div) {
+            const d = (+div) || 1; // the `|| 1`: a corrupted stored value would become NaN and the cane
+            if (caneBlockDiv === d)
+                return; //  would stop tapping, which is the most silent failure there is
+            port.set('incl_cane_div', d);
+            caneBlockDiv = d;
+            emit('caneBlockDiv', d);
+        },
+        setWheelchairValue(on) {
+            if (wheelchair === on)
+                return;
+            port.setBool('incl_wheelchair', on);
+            wheelchair = on;
+            emit('wheelchair', on);
+        },
+        setOneButtonValue(on) {
+            if (oneButton === on)
+                return;
+            port.setBool('incl_onebtn', on);
+            oneButton = on;
+            emit('oneButton', on);
+        },
+        setNoGripStrengthValue(on) {
+            const v = !!on;
+            if (noGripStrength === v)
+                return;
+            port.setBool('incl_sem_forca', v);
+            noGripStrength = v;
+            emit('noGripStrength', v);
+        },
+        setInputCooldownValue(ms) {
+            const v = toCooldown(ms);
+            if (inputCooldown === v)
+                return;
+            port.set('incl_input_cooldown', v);
+            inputCooldown = v;
+            emit('inputCooldown', v);
+        },
+        setSwitchScanValue(on) {
+            const v = !!on;
+            if (switchScan === v)
+                return;
+            port.setBool('incl_switch_scan', v);
+            switchScan = v;
+            emit('switchScan', v);
+        },
+        setVoiceControlValue(on) {
+            const v = !!on;
+            if (voiceControl === v)
+                return;
+            port.setBool('incl_voice_control', v);
+            voiceControl = v;
+            emit('voiceControl', v);
+        },
+        setCameraControlValue(v) {
+            const valid = toCameraControl(v);
+            if (cameraControl === valid)
+                return;
+            port.set('incl_camera_control', valid);
+            cameraControl = valid;
+            emit('cameraControl', valid);
+        },
+        setGameSpeedValue(v) {
+            const isValidSpeed = isGameSpeed(v);
+            if (gameSpeed === isValidSpeed)
+                return;
+            port.set('incl_game_speed', isValidSpeed);
+            gameSpeed = isValidSpeed;
+            emit('gameSpeed', isValidSpeed);
+        },
+        setCaptionPpmValue(ppm) {
+            const isValidRate = isCaptionRate(ppm);
+            if (captionPpm === isValidRate)
+                return;
+            port.set('incl_caption_ppm', isValidRate);
+            captionPpm = isValidRate;
+            emit('captionPpm', isValidRate);
+        },
+        setSpeechPpmValue(ppm) {
+            const isValidRate = isSpeechRate(ppm);
+            if (speechPpm === isValidRate)
+                return;
+            port.set('incl_speech_ppm', isValidRate);
+            speechPpm = isValidRate;
+            emit('speechPpm', isValidRate);
+        },
+        on, off, emit,
+    };
 }