@the-inclusionist/engine 7.0.1 → 8.0.0-rc.2

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

@@ -19,11 +19,14 @@
 // módulo rodar no project `node` sem importar PIXI. Mesmo precedente de render/scene-sky e game/traffic.
 // SEM I/O no import: initVizSetters(ctx) só fecha closures, não chama nada.
 import { VIZ_MODES, VIZ_BY_KEY, VIZ_FILTER, simulatesDisability } from './viz-modes.js';
+import { migrarVisual, filtroChave, chaveDeTextura, chaveLegada, ehSimulacao, ehBaixaVisao, ehCego, temAltoContraste, PADRAO, } from './viz-axes.js';
 import { t } from '../core/i18n.js'; // VIZ_MODES guarda CHAVE i18n desde o item 14; quem exibe resolve
+import { eixosHtml, escolhaDoBotao, ROTULO_DO_TEMA, ROTULO_DA_CORRECAO, } from '../ui/visual-axes-panel.js';
+import { recusaDaSimulacao } from '../ui/simulation-refusal.js';
 import { DIRECT_CFG, worldTexFor, spriteTexFor, clearWorldTexCache, clearSpriteTexCache } from './high-contrast.js';
 import { pupTexFor, resetPupTexCache } from './textures.js';
 import { lqFilter } from './lq-filter.js';
-import { setVizModeValue } from '../core/state.js';
+import { setVizModeValue, setModoCegoValue } from '../core/state.js';
 import * as store from '../platform/storage.js';
 /* ===================== PURO (sem PIXI, sem DOM) — o que rende teste de verdade ===================== */
 /**
@@ -38,6 +41,29 @@ export function alcanceDoModo(mode) {
 export function resolveViz(key) {
     return VIZ_BY_KEY[key] || VIZ_BY_KEY.normal;
 }
+/**
+ * O ESTADO VISUAL GUARDADO deste jogador, de qualquer das duas formas (issue #104).
+ *
+ * ⚠️ ESTA FUNÇÃO É A CAIXA «um ajuste salvo antes da divisão restaura o mesmo estado visível» da definition
+ * of done, e a ordem das duas leituras é a decisão inteira:
+ *
+ *   1. a chave NOVA (`visualP`), que é a única que sabe dizer dois eixos;
+ *   2. na falta dela, a chave VELHA (`vizP`), que guarda a string única — e é aqui que mora o ajuste de toda
+ *      criança que já jogou este jogo antes de hoje;
+ *   3. na falta das duas, o padrão.
+ *
+ * ⚠️ O RECUO NÃO É ZELO: sem ele, a primeira sessão depois da actualização apagaria o modo visual que ela
+ * escolheu — e quem escolheu `fix-deuter` ou `hc-direto-7` escolheu-o porque enxerga assim. É a diferença
+ * entre migrar e recomeçar.
+ *
+ * `migrarVisual` aceita as duas formas e é idempotente, então isto pode correr quantas vezes for preciso.
+ */
+export function lerVisualGuardado(i) {
+    const novo = store.getJSON(store.KEYS.visualP(i), null);
+    if (novo !== null)
+        return migrarVisual(novo);
+    return migrarVisual(store.get(store.KEYS.vizP(i), null));
+}
 /** É um dos três níveis de Renderização Direta (alto contraste)? Mesmo teste do original: `!!DIRECT_CFG[mode]`. */
 export function isDirectMode(mode) { return !!DIRECT_CFG[mode]; }
 /** Filtro CSS da canvas no SOLO: simulação/correção de visão + realce L→Q, compostos e sem vazios. */
@@ -116,20 +142,58 @@ export function initVizSetters(ctx) {
     }
     function applyVpFilters() {
         const spr = ctx.getVpSpr(), players = ctx.getPlayers();
+        // ⚠️ `filtroChave` E NÃO `p.viz` (#104). É a outra metade do par que a etapa 0 mediu: o TEMA vai pela
+        // textura (`playerVizTex`/`applySharedTextures`) e a CORREÇÃO ou SIMULAÇÃO vai pelo FILTRO — e é
+        // exactamente por serem dois caminhos que os dois eixos podem coexistir. `null` (sem filtro) entra como
+        // `'normal'`, que é a chave que o `pixiFilterFor` já usa para «nenhum», e ele cacheia por ela.
         for (let i = 0; i < ctx.getNumPlayers(); i++) {
+            const p = players[i];
             if (spr[i])
-                spr[i].filters = ctx.pixiFilterFor(players[i].viz);
+                spr[i].filters = ctx.pixiFilterFor((p.visual && filtroChave(p.visual)) || 'normal');
         }
     }
+    /**
+     * O ESCRITOR DE VERDADE desde a etapa 4 da #104: recebe o ESTADO, não uma chave.
+     *
+     * ⚠️ E É AQUI QUE O ESPELHO MUDA DE SIGNIFICADO, o que estava previsto e escrito. Enquanto os controles
+     * escreviam um valor de cada vez, `viz` conseguia ser «o modo equivalente». Com dois eixos não há chave
+     * única que descreva `hc7 + fix-deuter`, então o espelho passa a ser exactamente o que ele ainda consegue
+     * ser com honestidade: **a CHAVE DE TEXTURA** — `simulação ?? tema ?? normal`, o que mais muda o que se vê.
+     *
+     * Isso não é uma perda escondida: é a mesma chave que o `setVizModeValue` já escreve, e o invariante do
+     * gate passou a afirmá-la nesses termos. Um leitor antigo continua a ver algo verdadeiro sobre a tela; o
+     * que ele deixa de ver é a metade que a forma antiga nunca soube dizer.
+     */
+    function setVisualDoJogador(i, v) {
+        const p = ctx.getPlayers()[i];
+        p.visual = v;
+        p.viz = chaveLegada(v);
+        store.set(store.KEYS.vizP(i), p.viz); // legada: um leitor antigo faria `VIZ_BY_KEY[v]` e recusaria JSON
+        store.setJSON(store.KEYS.visualP(i), v); // nova: os dois eixos, que a chave velha não sabe dizer
+        aplicarVisualDoJogador(i, v);
+    }
+    /** Muda SÓ o tema deste jogador. A correção e a simulação ficam onde estavam — é o ponto da #104. */
+    function setTemaDoJogador(i, tema) {
+        const p = ctx.getPlayers()[i];
+        setVisualDoJogador(i, { ...(p.visual ?? PADRAO), tema });
+    }
+    /** Muda SÓ a correção de cor deste jogador. O tema e a simulação ficam onde estavam. */
+    function setCorrecaoDoJogador(i, correcao) {
+        const p = ctx.getPlayers()[i];
+        setVisualDoJogador(i, { ...(p.visual ?? PADRAO), correcao });
+    }
+    /** A API antiga, por chave única. Continua a valer: um jogo que escolhe um modo inteiro passa por aqui. */
     function setPlayerViz(i, mode) {
-        const m = resolveViz(mode);
-        ctx.getPlayers()[i].viz = m.key;
-        store.set(store.KEYS.vizP(i), m.key);
+        setVisualDoJogador(i, migrarVisual(resolveViz(mode).key));
+    }
+    /** Os efeitos colaterais de ter mudado o visual de um jogador. Separados do ESCREVER de propósito: os dois
+     *  escritores por eixo e o antigo por chave partilham-nos, e uma cópia a mais seria uma cópia a divergir. */
+    function aplicarVisualDoJogador(i, v) {
         ctx.invalidateSharedViz();
-        if (m.kind === 'blind')
-            ctx.setModoCego(true); // empatia cegueira total liga o modo cego (áudio) por padrão
+        if (ehCego(v))
+            (ctx.setModoCego ?? setModoCegoValue)(true); // empatia cegueira total liga o modo cego (áudio) por padrão
         if (ctx.getNumPlayers() <= 1 && i === 0) {
-            applyVizGlobal(m.key);
+            applyVizGlobal(v);
         }
         else {
             applyVpFilters();
@@ -139,36 +203,60 @@ export function initVizSetters(ctx) {
         ctx.renderVisualPanel();
         ctx.renderEmpathyPanel();
     }
-    function applyVizGlobal(mode) {
-        const m = resolveViz(mode);
-        mode = m.key;
-        setVizModeValue(mode); // core/state: valor + persistência (incl_viz) + evento
+    /**
+     * ⚠️ AQUI É QUE OS DOIS EIXOS PASSAM A COEXISTIR (#104, ADR-0076), e a função nem cresceu — ela SEPAROU-SE.
+     *
+     * Enquanto o estado era uma chave só, cada linha abaixo perguntava a mesma coisa (`mode`, `m.kind`) e a
+     * resposta tinha de ser uma. Com dois eixos, as mesmas linhas dividem-se em três grupos que nunca se
+     * tocaram — e essa é a razão de a composição já ser mecanicamente possível, como o `viz-axes` regista:
+     *
+     *   · TEMA (contraste) → textura e classe de DOM. `chaveDeTextura` e `temAltoContraste`.
+     *   · CORREÇÃO ou SIMULAÇÃO → filtro CSS. `filtroChave`.
+     *   · SIMULAÇÃO → as classes do corpo, o overlay, os controles de toque, a bolinha.
+     *
+     * ⚠️ E O ALCANCE DO FILTRO CONTINUA A DEPENDER DE SIMULAR OU CORRIGIR, que é a distinção do ADR-0046: uma
+     * CORREÇÃO alcança os menus, porque a criança precisa dela para LER o menu; uma SIMULAÇÃO fica no mundo,
+     * porque quem simula tem de conseguir sair.
+     *
+     * `setVizModeValue` continua a escrever a chave ÚNICA legada, e a que ele escreve é a de TEXTURA — que é
+     * `simulação ?? tema ?? normal`, ou seja o que mais muda o que se vê. É espelho, não fonte: o estado a
+     * sério são os dois eixos, e esta linha sai quando o último leitor da chave velha sair.
+     */
+    function applyVizGlobal(v) {
+        const filtro = filtroChave(v);
+        const textura = chaveDeTextura(v);
+        // ⚠️ `chaveLegada` E NÃO `textura`: a de textura devolve `normal` para uma correção de cor, e escrevê-la
+        // aqui faria um leitor antigo da chave global perder a correção da criança. Ver a nota em `chaveLegada`.
+        setVizModeValue(chaveLegada(v)); // core/state: valor + persistência (incl_viz) + evento — espelho legado
         // ANTES daqui saía também `ctx.setHcMode(m.kind === 'hcnew')`, alimentando um `let hcMode` no game.js cujo
         // único leitor era o gancho window.__incl. Era `vizMode` reescrito com outro nome: derivar de VIZ_BY_KEY
         // custa uma comparação e não pode divergir. (O inicializador daquele `let` usava OUTRA fórmula,
         // `vizMode!=='normal'`, e discordava do setter — sem efeito, porque applyVizGlobal roda no boot antes de
         // o gancho existir, mas é o sintoma clássico de cópia de estado.)
-        ctx.aplicarFiltroCss(cssFilterFor(mode, lqFilter()), alcanceDoModo(mode));
-        ctx.aplicarAltoContrasteNoDom(m.kind === 'hcnew'); // não é filtro: ver `AplicarAltoContrasteNoDom` // sim. daltonismo/baixa-visão/cegueira + realce L/Q compostos
-        ctx.camera.filters = (m.kind === 'hcnew') ? ctx.pixiFilterFor(mode) : null; // solo: alto contraste experimental = filtro GPU na câmera
-        ctx.setFrontDim(!!DIRECT_CFG[mode]); // HC: frente (carros/placas/semáforo) escurece como fundo
-        ctx.worldSprite.texture = worldTexFor(mode); // alto contraste direto = Renderização Direta · resto=normal
-        ctx.parallaxLayers.forEach((ts, i) => { ts.texture = ctx.parallaxTexFor(i, mode); });
-        ctx.decoSprites.forEach((s) => { s.texture = ctx.treeTexFor(mode); });
+        // --- eixo CORREÇÃO/SIMULAÇÃO: o filtro CSS ---
+        ctx.aplicarFiltroCss(cssFilterFor(filtro ?? '', lqFilter()), ehSimulacao(v) ? 'mundo' : 'mundo-e-menus');
+        // --- eixo TEMA: DOM e textura. Não é filtro (ver `AplicarAltoContrasteNoDom`), e é por isso que compõe.
+        ctx.aplicarAltoContrasteNoDom(temAltoContraste(v));
+        ctx.camera.filters = temAltoContraste(v) ? ctx.pixiFilterFor(textura) : null; // solo: alto contraste na câmera
+        ctx.setFrontDim(temAltoContraste(v)); // HC: frente (carros/placas/semáforo) escurece como fundo
+        ctx.worldSprite.texture = worldTexFor(textura); // alto contraste direto = Renderização Direta · resto=normal
+        ctx.parallaxLayers.forEach((ts, i) => { ts.texture = ctx.parallaxTexFor(i, textura); });
+        ctx.decoSprites.forEach((s) => { s.texture = ctx.treeTexFor(textura); });
         ctx.rebuildExtras();
         ctx.rebuildCoins();
-        // baixa visão = névoa+manchas (overlay) + bolinha verde; cegueira = tela preta (filtro) + esconde controles + bolinha branca
-        ctx.body.classList.toggle('lowvision-mode', m.kind === 'lowvision');
-        ctx.body.classList.toggle('blind-mode', m.kind === 'blind');
+        // --- SIMULAÇÃO: baixa visão = névoa+manchas (overlay) + bolinha verde; cegueira = tela preta + esconde
+        //     controles + bolinha branca. Nenhuma delas olha para o tema, e é por isso que o tema não as apaga.
+        ctx.body.classList.toggle('lowvision-mode', ehBaixaVisao(v));
+        ctx.body.classList.toggle('blind-mode', ehCego(v));
         const ov = ctx.$('#viz-overlay');
         if (ov) {
-            ov.hidden = (m.kind !== 'lowvision');
-            ov.className = lvOverlayClassFor(m);
+            ov.hidden = !ehBaixaVisao(v);
+            ov.className = ehBaixaVisao(v) ? 'lv-' + String(v.simulacao).slice(3) : '';
         }
-        if (m.kind === 'blind') {
+        if (ehCego(v)) {
             ctx.hideTouchControls('cegueira');
         }
-        updateVizIndicator(m.kind);
+        updateVizIndicator(ehCego(v) ? 'blind' : ehBaixaVisao(v) ? 'lowvision' : 'normal');
         ctx.reflectVizButtons(); // (a guarda `typeof ...==='function'` do original morreu: era declaração de função, sempre verdadeira)
         ctx.renderVisualPanel();
         ctx.renderEmpathyPanel();
@@ -188,7 +276,7 @@ export function initVizSetters(ctx) {
     function reapplyVizAll() {
         ctx.invalidateSharedViz();
         if (ctx.getNumPlayers() <= 1) {
-            applyVizGlobal(ctx.getPlayers()[0].viz);
+            applyVizGlobal(ctx.getPlayers()[0].visual ?? PADRAO);
         }
         else {
             ctx.aplicarFiltroCss(lqFilter(), 'mundo-e-menus'); // realce L/Q é melhoria: alcança o menu
@@ -209,7 +297,7 @@ export function initVizSetters(ctx) {
         ctx.clearPlayerDirectCache();
         ctx.invalidateSharedViz();
         if (ctx.getNumPlayers() <= 1)
-            applyVizGlobal(ctx.getPlayers()[0].viz);
+            applyVizGlobal(ctx.getPlayers()[0].visual ?? PADRAO);
         else
             applyVpFilters();
     }
@@ -232,13 +320,81 @@ export function initVizSetters(ctx) {
             }));
         }
         const players = ctx.getPlayers(), sel = ctx.getSelVizPlayer();
-        const cur = players[sel] ? players[sel].viz : 'normal';
+        const v = players[sel]?.visual ?? PADRAO;
+        const cur = chaveLegada(v);
         el.innerHTML = vizGroupHtml(modes, cur);
-        el.querySelectorAll('button[data-viz]').forEach((btn) => btn.addEventListener('click', () => {
+        // ⚠️ A RECUSA DA SIMULAÇÃO (#104, ADR-0076 §4). Com qualquer dos dois eixos fora do padrão, uma
+        // demonstração não mostra a deficiência — mostra o AJUSTE por cima do qual ela corre, e isso ensina uma
+        // coisa falsa. A linha CONTINUA na tela, desabilitada e com o motivo: sumir ensinaria que a coisa não
+        // existe, e um adulto concluiria que ela foi tirada em vez de perceber que foi ele que ligou o contraste.
+        //
+        // A prosa entra num `.opt-hint`, que é o que a casca (`ui/settings-panel.fillExplain`) MOVE para o rodapé
+        // — a regra das três zonas do CLAUDE.md: a explicação mora no rodapé, nunca na linha.
+        //
+        // ⚠️ SÓ AS LINHAS QUE SIMULAM. Esta função desenha hoje a lista de simulações (o painel visual passou a
+        // usar o `renderEixosVisuais`), mas ela continua a receber os modos por parâmetro — e uma correção de
+        // cor nesta lista não deve ser recusada por causa do eixo dela própria.
+        const recusa = recusaDaSimulacao(v);
+        el.querySelectorAll('button[data-viz]').forEach((btn) => {
             const key = btn.dataset.viz;
-            setPlayerViz(ctx.getSelVizPlayer(), key);
-            ctx.srSay(vizGroupSay(ctx.getNumPlayers(), ctx.getSelVizPlayer(), t(VIZ_MODES.find((m) => m.key === key).nome)));
+            if (recusa && simulatesDisability(key)) {
+                btn.setAttribute('aria-disabled', 'true');
+                const dica = btn.closest('.ctrl-row')?.querySelector('.opt-hint');
+                if (dica)
+                    dica.textContent = `${dica.textContent} ${t(recusa.chave)}`.trim();
+                return; // sem ouvinte: aceitar o clique e ignorá-lo é a outra metade do que o ADR proíbe
+            }
+            btn.addEventListener('click', () => {
+                setPlayerViz(ctx.getSelVizPlayer(), key);
+                ctx.srSay(vizGroupSay(ctx.getNumPlayers(), ctx.getSelVizPlayer(), t(VIZ_MODES.find((m) => m.key === key).nome)));
+            });
+        });
+    }
+    /**
+     * OS DOIS EIXOS no painel VISUAL (#104). Irmão do `renderVizGroup`, e SEPARADO dele de propósito.
+     *
+     * ⚠️ QUASE FIZ ISTO DENTRO DO `renderVizGroup`, E TERIA PARTIDO O PAINEL DE EMPATIA. Aquela função serve os
+     * DOIS painéis — `#visual-modes` com os sete modos e `#empathy-list` com as nove simulações —, e trocar o
+     * corpo dela teria posto os dois eixos na lista de simulações. Ali o rádio único continua CERTO: as
+     * simulações são mesmo exclusivas entre si, e o que deixou de ser exclusivo foi outra coisa.
+     *
+     * ⚠️ E OS DOIS GRUPOS ENTRAM NO CONTENEDOR QUE JÁ EXISTE, sem markup nova do hospedeiro. Exigir um elemento
+     * a mais faria cada um dos 300 jogos ter de se lembrar dele — a forma de defeito que o ADR-0106 acabou de
+     * medir em cinco jogos sem barra de acessibilidade nenhuma.
+     */
+    function renderEixosVisuais(listSel, tabsSel) {
+        const el = ctx.$(listSel);
+        if (!el)
+            return;
+        if (ctx.getSelVizPlayer() >= ctx.getNumPlayers())
+            ctx.setSelVizPlayer(0);
+        const tabs = ctx.$(tabsSel);
+        if (tabs) {
+            tabs.hidden = true;
+            tabs.innerHTML = '';
+        }
+        const sel = ctx.getSelVizPlayer();
+        const v = ctx.getPlayers()[sel]?.visual ?? PADRAO;
+        el.innerHTML = eixosHtml(v, t);
+        el.querySelectorAll('button[data-eixo]').forEach((btn) => btn.addEventListener('click', () => {
+            const escolha = escolhaDoBotao(btn.dataset);
+            if (!escolha)
+                return; // botão de outro assunto, ou um `data-` editado à mão: não se adivinha
+            const i = ctx.getSelVizPlayer();
+            if (escolha.eixo === 'tema') {
+                setTemaDoJogador(i, escolha.valor);
+                ctx.srSay(vizGroupSay(ctx.getNumPlayers(), i, t(ROTULO_DO_TEMA[escolha.valor])));
+            }
+            else {
+                setCorrecaoDoJogador(i, escolha.valor);
+                ctx.srSay(vizGroupSay(ctx.getNumPlayers(), i, t(ROTULO_DA_CORRECAO[escolha.valor])));
+            }
         }));
     }
-    return { applySharedTextures, updateVpDots, applyVpFilters, setPlayerViz, applyVizGlobal, reapplyVizAll, updateVizIndicator, rebakeDirect, renderVizGroup };
+    return {
+        applySharedTextures, updateVpDots, applyVpFilters, setPlayerViz, applyVizGlobal, reapplyVizAll,
+        updateVizIndicator, rebakeDirect, renderVizGroup, renderEixosVisuais,
+        // Os DOIS escritores por eixo (#104): é o que um painel de dois controles chama.
+        setVisualDoJogador, setTemaDoJogador, setCorrecaoDoJogador,
+    };
 }

package/dist-pkg/render/wheelchair-sprites.d.ts

@@ -1,4 +1,5 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import { type VisualState } from './viz-axes.js';
 import type { PlayerView } from '../core/entity.js';
 /** Minimal PIXI.Graphics surface these draws use (structural → module stays PIXI-free for node tests). */
 export interface DrawGraphics {
@@ -10,10 +11,17 @@ export interface DrawGraphics {
     drawCircle(x: number, y: number, r: number): unknown;
 }
 /** Cadeira e bengala: onde o jogador está, para que lado olha, e em que modo de visão desenhar. */
-type DrawablePlayer = PlayerView<'facing' | 'x' | 'y' | 'viz'>;
-/** Cane color: green for low-vision, white otherwise (blind). */
+type DrawablePlayer = PlayerView<'facing' | 'x' | 'y' | 'visual'>;
+/**
+ * Cor da bengala: verde na baixa visão, branca no resto (cegueira).
+ *
+ * ⚠️ LÊ O `visual` E NÃO O `viz` desde a #104. A pergunta não mudou — «isto é baixa visão?» — mas quem a
+ * responde passou a ser o `ehBaixaVisao` do modelo de dois eixos, em vez de uma consulta ao `kind` da tabela
+ * antiga. É a mesma resposta para os dezasseis modos de hoje (a rede da etapa 0 afirma-o, chave a chave), e
+ * passa a ser a resposta CERTA para um estado que a tabela antiga não sabe exprimir.
+ */
 export declare function caneColor(pl: {
-    viz: string;
+    visual: VisualState;
 }): number;
 /** Rigid half-block cane (~8px): front-hand extension, fixed to the body (does not swing on its own). */
 export declare function drawCane(g: DrawGraphics, pl: DrawablePlayer): void;

package/dist-pkg/render/wheelchair-sprites.js

@@ -3,11 +3,17 @@
 // low-vision), the running cane (item), and the wheelchair. Stateless PIXI drawing (verbatim from game.js):
 // each takes a Graphics `g` + the player. The layers (caneLayer/chairLayer) stay in game.js and are passed in.
 // `caneColor` (pure) moves here too — it was only used by the cane draws. See docs/5-Refactoring/plano-modularizacao-mapa.md.
-import { VIZ_BY_KEY } from './viz-modes.js';
-/** Cane color: green for low-vision, white otherwise (blind). */
+import { ehBaixaVisao } from './viz-axes.js';
+/**
+ * Cor da bengala: verde na baixa visão, branca no resto (cegueira).
+ *
+ * ⚠️ LÊ O `visual` E NÃO O `viz` desde a #104. A pergunta não mudou — «isto é baixa visão?» — mas quem a
+ * responde passou a ser o `ehBaixaVisao` do modelo de dois eixos, em vez de uma consulta ao `kind` da tabela
+ * antiga. É a mesma resposta para os dezasseis modos de hoje (a rede da etapa 0 afirma-o, chave a chave), e
+ * passa a ser a resposta CERTA para um estado que a tabela antiga não sabe exprimir.
+ */
 export function caneColor(pl) {
-    const m = VIZ_BY_KEY[pl.viz];
-    return m && m.kind === 'lowvision' ? 0x35d06a : 0xf2f2f2;
+    return ehBaixaVisao(pl.visual) ? 0x35d06a : 0xf2f2f2;
 }
 /** Rigid half-block cane (~8px): front-hand extension, fixed to the body (does not swing on its own). */
 export function drawCane(g, pl) {

package/dist-pkg/ui/dom.js

@@ -13,8 +13,26 @@ import { t } from '../core/i18n.js';
 // seleciona. `Element` e o padrao do lib.dom porque `querySelector` tambem serve para SVG e MathML —
 // nenhum seletor deste projeto pega um desses (conferido). Quem precisar de um tipo mais estreito passa
 // o parametro: `$<HTMLSelectElement>('#pad-design')`.
-export const $ = (s) => document.querySelector(s);
-export const $$ = (s) => [...document.querySelectorAll(s)];
+/**
+ * ⚠️ RESOLVIDO POR `globalThis` E NÃO PELO GLOBAL CRU, e a diferença é entre devolver `null` e LANÇAR.
+ *
+ * `document.querySelector(...)` com `document` inexistente dá `ReferenceError` — não `undefined` —, e a
+ * assinatura destas duas funções promete `T | null`. Uma consulta que lança onde promete `null` é um defeito
+ * pela própria assinatura, e ele viajava longe: medido em 2026-09-08, o `core/a11y-sr.srAlert` chama o `$`
+ * daqui, e o `createGame` chama o `srAlert` ao mostrar o aviso de alcance — logo bootar a engine contra um
+ * documento INJECTADO (um iframe, um editor ao lado do jogo, um teste) rebentava o boot inteiro num anúncio.
+ *
+ * 📌 É o ACHADO 15 do `boot/create-game` outra vez, e sobreviveu pela mesma razão: enquanto toda raiz era um
+ * `main.ts` num navegador, o global ERA o documento certo. `globalThis.document` é a mesma coisa onde ele
+ * existe, e é `undefined` — em vez de explosão — onde não existe.
+ *
+ * ⚠️ E ELAS CONTINUAM A OLHAR PARA O GLOBAL, de propósito: quem precisa de consultar OUTRO documento injecta
+ * o seu (`create-game` tem um `$` próprio ligado ao `doc` do hospedeiro, e o `ui/pause-icons` tem o
+ * `docDaMontagem`). O que este conserto muda não é ONDE se procura — é o que acontece quando não há onde.
+ */
+const docGlobal = () => globalThis.document;
+export const $ = (s) => docGlobal()?.querySelector(s) ?? null;
+export const $$ = (s) => [...(docGlobal()?.querySelectorAll(s) ?? [])];
 /**
  * Reflects an on/off state onto a toggle button: the visual class AND `aria-pressed`.
  * Lives here because the two must never drift apart — a button that looks pressed but does not

package/dist-pkg/ui/fonts.d.ts

@@ -4,12 +4,42 @@
  * descrição, não o texto: mesma decisão de `VIZ_MODES` e `RM_LABEL`, e pelo mesmo motivo — uma tabela de
  * `const` com texto resolve uma vez, no import, e fica congelada no idioma do boot.
  */
+/**
+ * O PAPEL de uma face, e é a emenda do ADR-0012 (27/08) posta em dado (issue #87).
+ *
+ * ⚠️ NÃO É O MESMO QUE O GRUPO. O grupo (`sans`/`serif`/`hand`) é APARÊNCIA e serve para ler a lista; o papel
+ * é ONDE A FACE PODE SER USADA, e é regra:
+ *
+ *   · `geral` — em qualquer lugar. São as únicas que o menu de tipografia oferece.
+ *   · `caligrafica` — **só DENTRO das atividades escolares**, nunca no HUD nem nos menus, e por isso **não
+ *     aparecem no menu de fonte**. Elas existem para a criança APRENDER a ler letra cursiva, o que é matéria;
+ *     usá-las como interface é dar-lhe a matéria como obstáculo em todos os lugares onde ela só quer navegar.
+ *   · `jogo` — a face que o JOGO usa no HUD, no título e em rótulos curtos de arcade. Também não aparece no
+ *     menu, e pelo mesmo tipo de razão que as caligráficas: uma face de pixel de 8 bits é desenhada para
+ *     dizer POUCAS palavras em tamanho grande. Como face de interface ela contradiz o argumento que faz a
+ *     Atkinson Hyperlegible ser o padrão — pouca diferenciação entre letras, avanço largo, nenhuma variação
+ *     de altura. É certa no HUD de um jogo de pixel-art e errada num menu que a criança precisa de LER.
+ *
+ * ⚠️ E O CORTE NÃO É O GRUPO `hand`. O `comicneue` está lá por aparência — a face é de propósito geral e é
+ * frequentemente recomendada para dislexia. Tirá-la do menu removeria uma opção legitimamente acessível. A
+ * definição boa é a lista do item 2 da #87, que nomeia as caligráficas dando-lhes tamanho mínimo.
+ */
+export type FontRole = 'geral' | 'caligrafica' | 'jogo';
 export type FontItem = {
     k: string;
     fam: string;
     fb: string;
     d?: string;
     off?: string;
+    /** Ausente = `geral`. Só as caligráficas se declaram, porque são a excepção. */
+    papel?: FontRole;
+    /**
+     * O menor tamanho, em px, em que esta face ainda é legível (item 2 da #87, números do Dev).
+     *
+     * ⚠️ Abaixo disto a face deixa de ser DIFÍCIL e passa a ser ILEGÍVEL, que são coisas diferentes: a
+     * dificuldade é o exercício, a ilegibilidade é a criança a desistir. Por isso é gate e não recomendação.
+     */
+    minPx?: number;
 };
 /** Um grupo do catálogo. `g` também guarda CHAVE ('font.group.sans'), pelo mesmo motivo. */
 export type FontGroup = {
@@ -17,6 +47,34 @@ export type FontGroup = {
     items: FontItem[];
 };
 export declare const FONT_GROUPS: FontGroup[];
+/** O papel de uma face; ausente no catálogo quer dizer `geral`. */
+export declare function papelDaFonte(it: FontItem): FontRole;
+/**
+ * AS FAMÍLIAS QUE UMA FACE ACEITA, do `fam` que pode ser uma PILHA.
+ *
+ * 📌 A Ronde declara três (`'Ronde Script, OPTIFrench-Script, Merveille'`) porque qualquer uma delas serve —
+ * são três desenhos da mesma letra de mão, e um adulto instala a que encontrar. As outras faces declaram uma
+ * só, e para elas isto devolve uma lista de um.
+ */
+export declare function familiasDaFace(it: FontItem): string[];
+/**
+ * ESTA FACE PODE SER USADA AGORA? — o `off` deixa de ser uma sentença e passa a ser uma CONDIÇÃO.
+ *
+ * O ADR-0012 decidiu que a opção da ronde «fica DESABILITADA enquanto nenhuma fonte estiver presente», e o
+ * ADR-0108 §4 acrescentou o que ela diz. A palavra «enquanto» é o que esta função constrói: uma face `off`
+ * volta a ficar disponível no instante em que o adulto instala uma das que a mensagem nomeia.
+ *
+ * ⚠️ O DETECTOR É INJECTADO, e nunca `document.fonts` lido daqui: este módulo é o catálogo, corre em node nos
+ * gates, e ler um global do navegador aqui é o ACHADO 15 outra vez — o `srAlert` que rebentou o boot contra um
+ * documento injectado.
+ * 📌 E o PADRÃO É «não instalada», que é seguro por uma razão que não vale para todos os padrões deste
+ * repositório: sem detector a opção fica desabilitada COM a mensagem, e a mensagem diz ao adulto exactamente
+ * o que fazer. O silêncio não decide nada contra a criança — ele mantém o estado que já existia e que é
+ * accionável. É o oposto do `seguraTeclas`, onde os dois lados do padrão erravam.
+ */
+export declare function faceDisponivel(it: FontItem, instalada?: (familia: string) => boolean): boolean;
+/** As faces que o MENU pode oferecer: só as gerais (emenda do ADR-0012). */
+export declare const OFERECIVEIS: FontItem[];
 export declare const FONT_BY_KEY: Record<string, FontItem>;
 /** Narrow store shape these need — lets a caller inject a fake without touching real storage. */
 export interface FontStore {
@@ -34,7 +92,19 @@ export declare const FONT_KEY_LEGACY = "incl_fonte";
  * porque duas cópias de um padrão são duas chances de o reset devolver algo que o jogo nunca usou.
  */
 export declare const DEFAULT_FONT_KEY = "atkinson";
-/** Boot choice: validated persisted key (ignores .off fonts) -> legacy-key migration -> DEFAULT_FONT_KEY. */
+/**
+ * Boot choice: validated persisted key (ignores .off fonts) -> legacy-key migration -> DEFAULT_FONT_KEY.
+ *
+ * ⚠️ E UMA CALIGRÁFICA GUARDADA VOLTA AO PADRÃO (issue #87, 2026-09-07). Antes da emenda do ADR-0012 o menu
+ * oferecia as sete caligráficas, então há crianças com `pinyon` ou `ufmag` guardados — e o valor salvo
+ * continua a ser escolha delas, que não é nossa para desfazer sem motivo. O motivo existe: a emenda diz que
+ * uma caligráfica **não pode ser a face da interface**, e o menu deixou de a oferecer. Deixá-la valer daria
+ * uma interface inteira em letra cursiva a quem já não tem como sair dela pelo menu — uma armadilha, e das
+ * silenciosas.
+ *
+ * ⚠️ E UMA CHAVE APAGADA TAMBÉM VOLTA, pelo mesmo caminho: as quatro faces que saíram do roster já não estão
+ * no `FONT_BY_KEY`, então quem tinha `greatvibes` guardado cai no padrão em vez de ficar sem face nenhuma.
+ */
 export declare function resolveFontKey(s: FontStore): string;
 export declare function persistFontKey(s: FontStore, k: string): void;
 export declare function loadFontKey(): string;

package/dist-pkg/ui/fonts.js

@@ -8,6 +8,12 @@ export const FONT_GROUPS = [
             { k: 'lexend', fam: 'Lexend', fb: 'sans', d: 'font.desc.lexend' },
             { k: 'quattro', fam: 'iA Writer Quattro', fb: 'sans', d: 'font.desc.quattro' },
             { k: 'andika', fam: 'Andika', fb: 'sans', d: 'font.desc.andika' },
+            // ⚠️ A OPENDYSLEXIC ENTRA SEM NENHUMA ALEGAÇÃO DE EFICÁCIA, e a restrição é da issue #87 item 3 e do
+            // `docs/game-design/typography.md`, que diz por extenso: «Ofereça a Dyslexie e a OpenDyslexic apenas como
+            // escolha do usuário. A pesquisa não mostra ganho de leitura com elas.» A descrição dela fala do DESENHO
+            // (hastes pesadas em baixo), nunca do efeito — prometer leitura melhor seria vender a uma criança
+            // disléxica uma coisa que a evidência não sustenta, e ela é quem menos pode pagar por isso.
+            { k: 'opendyslexic', fam: 'OpenDyslexic', fb: 'sans', d: 'font.desc.opendyslexic' },
             { k: 'sourcesans', fam: 'Source Sans 3', fb: 'sans' },
             { k: 'inter', fam: 'Inter', fb: 'sans' },
             { k: 'opensans', fam: 'Open Sans', fb: 'sans' },
@@ -18,16 +24,101 @@ export const FONT_GROUPS = [
             { k: 'sourceserif', fam: 'Source Serif 4', fb: 'serif' },
             { k: 'newsreader', fam: 'Newsreader', fb: 'serif' }
         ] },
+    // ⚠️ QUATRO FACES SAÍRAM DAQUI EM 2026-09-07 (issue #87, item 3, decisão do Dev):
+    //   · `greatvibes` (44 KB) e `ufcook` (20 KB) — peso que o roster não paga;
+    //   · `learningcurve` e `kindergarten` — eram entradas `.off` SEM FICHEIRO, isto é, o menu oferecia-as
+    //     desabilitadas e nada existia por trás. Uma linha que só serve para dizer «ainda não» é uma linha que
+    //     a criança lê e não pode usar.
     { g: 'font.group.hand', items: [
-            { k: 'greatvibes', fam: 'Great Vibes', fb: 'cursive', d: 'font.desc.greatvibes' },
-            { k: 'pinyon', fam: 'Pinyon Script', fb: 'cursive', d: 'font.desc.pinyon' },
-            { k: 'ufcook', fam: 'UnifrakturCook', fb: 'cursive', d: 'font.desc.ufcook' },
-            { k: 'ufmag', fam: 'UnifrakturMaguntia', fb: 'cursive', d: 'font.desc.ufmag' },
+            { k: 'pinyon', fam: 'Pinyon Script', fb: 'cursive', d: 'font.desc.pinyon', papel: 'caligrafica', minPx: 24 },
+            { k: 'ufmag', fam: 'UnifrakturMaguntia', fb: 'cursive', d: 'font.desc.ufmag', papel: 'caligrafica', minPx: 20 },
+            // Fondamento entra pela emenda do ADR-0012 (#87 item 3) com o mínimo que o Dev fixou. Caligráfica, logo
+            // fora do menu — ela é para os botões DENTRO das atividades escolares, não para a interface.
+            { k: 'fondamento', fam: 'Fondamento', fb: 'cursive', d: 'font.desc.fondamento', papel: 'caligrafica', minPx: 20 },
+            // ⚠️ `comicneue` NÃO é caligráfica, e está neste grupo só por aparência: é uma face de propósito geral,
+            // frequentemente recomendada para dislexia. Marcá-la como caligráfica tirá-la-ia do menu — removendo uma
+            // opção legitimamente acessível pelo formato do grupo em vez de pelo papel.
             { k: 'comicneue', fam: 'Comic Neue', fb: 'cursive', d: 'font.desc.comicneue' },
-            { k: 'learningcurve', fam: 'Learning Curve', fb: 'cursive', d: 'font.desc.learningcurve', off: 'font.off.pending' },
-            { k: 'kindergarten', fam: 'Kindergarten Pro', fb: 'cursive', d: 'font.desc.kindergarten', off: 'font.off.negotiating' }
+            /*
+             * A RONDE FRANCESA — o item 4 da #87, decidido no ADR-0108 §4. Ela NUNCA é empacotada: as três faces são
+             * livres só para uso PESSOAL (ADR-0012), e distribuí-las seria distribuir o que não foi licenciado para
+             * distribuição. O que muda é que a opção passa a FALAR.
+             *
+             * ⚠️ E ISTO NÃO É A ENTRADA `.off` QUE ESTE CATÁLOGO JÁ REMOVEU. O cabeçalho acima tirou a `learningcurve`
+             * e a `kindergarten` com a razão certa — «uma linha que só serve para dizer "ainda não" é uma linha que a
+             * criança lê e não pode usar». A diferença é ACCIONABILIDADE, e é a razão que o ADR-0108 dá por extenso:
+             * aquelas diziam «ainda não», que ninguém pode resolver; esta diz QUAIS TRÊS FONTES INSTALAR, que um
+             * adulto resolve numa tarde. 📌 «Instale uma fonte ronde» seria o defeito de volta — um adulto não age
+             * sobre uma categoria —, e é por isso que a mensagem nomeia as três.
+             *
+             * ⚠️ `papel` AUSENTE, logo `geral`, e é deliberado apesar de a ronde ser caligráfica por natureza: as
+             * caligráficas são filtradas do menu (`papelDaFonte === 'geral'`), e uma linha filtrada não pode dizer
+             * nada a ninguém. Marcar o papel «certo» aqui apagaria a única coisa que este item existe para fazer.
+             */
+            /*
+             * AS OITO PLAYWRITE — o item 3 da #87, decidido no ADR-0108 §2 e entregue em 2026-09-09.
+             *
+             * ⚠️ `papel: caligrafica`, logo FORA DO MENU: elas são a mão que se aprende a escrever, para os botões
+             * DENTRO das atividades escolares, e não uma opção de interface. É a divisão do item 1 desta issue.
+             *
+             * 📌 `minPx: 20` é o mesmo piso que as outras três cursivas carregam. A lista de mínimos da #87 não
+             * nomeia a Playwrite — o número é o das irmãs, e não uma medição própria; corrigir-se com uma linha.
+             */
+            { k: 'pwbr', fam: 'Playwrite BR', fb: 'cursive', d: 'font.desc.pw.br', papel: 'caligrafica', minPx: 20 },
+            { k: 'pwustrad', fam: 'Playwrite US Trad', fb: 'cursive', d: 'font.desc.pw.ustrad', papel: 'caligrafica', minPx: 20 },
+            { k: 'pwusmod', fam: 'Playwrite US Modern', fb: 'cursive', d: 'font.desc.pw.usmod', papel: 'caligrafica', minPx: 20 },
+            { k: 'pwca', fam: 'Playwrite CA', fb: 'cursive', d: 'font.desc.pw.ca', papel: 'caligrafica', minPx: 20 },
+            { k: 'pwmx', fam: 'Playwrite MX', fb: 'cursive', d: 'font.desc.pw.mx', papel: 'caligrafica', minPx: 20 },
+            { k: 'pwar', fam: 'Playwrite AR', fb: 'cursive', d: 'font.desc.pw.ar', papel: 'caligrafica', minPx: 20 },
+            { k: 'pwcl', fam: 'Playwrite CL', fb: 'cursive', d: 'font.desc.pw.cl', papel: 'caligrafica', minPx: 20 },
+            { k: 'pwco', fam: 'Playwrite CO', fb: 'cursive', d: 'font.desc.pw.co', papel: 'caligrafica', minPx: 20 },
+            { k: 'ronde', fam: 'Ronde Script, OPTIFrench-Script, Merveille', fb: 'cursive',
+                d: 'font.desc.ronde', off: 'font.off.ronde' }
+        ] },
+    // ⚠️ A FACE DO JOGO, e ela tem grupo próprio porque não é nem sans, nem serifada, nem manuscrita — é uma
+    // face de PIXEL, e pô-la em qualquer um dos três diria a coisa errada sobre ela na lista.
+    //
+    // Ela NÃO aparece no menu (`papel:'jogo'`), e o ficheiro veio do `SP-the-inclusionist-whackwhack`, onde já
+    // estava verificado. Ver a nota do `@font-face` em `vendor/fonts.css`: o subconjunto errado desta família
+    // carrega, declara-se e reporta-se como certo, e não desenha uma única letra latina.
+    { g: 'font.group.arcade', items: [
+            { k: 'pressstart', fam: 'Press Start 2P', fb: 'monospace', d: 'font.desc.pressstart', papel: 'jogo' }
         ] },
 ];
+/** O papel de uma face; ausente no catálogo quer dizer `geral`. */
+export function papelDaFonte(it) { return it.papel ?? 'geral'; }
+/**
+ * AS FAMÍLIAS QUE UMA FACE ACEITA, do `fam` que pode ser uma PILHA.
+ *
+ * 📌 A Ronde declara três (`'Ronde Script, OPTIFrench-Script, Merveille'`) porque qualquer uma delas serve —
+ * são três desenhos da mesma letra de mão, e um adulto instala a que encontrar. As outras faces declaram uma
+ * só, e para elas isto devolve uma lista de um.
+ */
+export function familiasDaFace(it) {
+    return it.fam.split(',').map((f) => f.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
+}
+/**
+ * ESTA FACE PODE SER USADA AGORA? — o `off` deixa de ser uma sentença e passa a ser uma CONDIÇÃO.
+ *
+ * O ADR-0012 decidiu que a opção da ronde «fica DESABILITADA enquanto nenhuma fonte estiver presente», e o
+ * ADR-0108 §4 acrescentou o que ela diz. A palavra «enquanto» é o que esta função constrói: uma face `off`
+ * volta a ficar disponível no instante em que o adulto instala uma das que a mensagem nomeia.
+ *
+ * ⚠️ O DETECTOR É INJECTADO, e nunca `document.fonts` lido daqui: este módulo é o catálogo, corre em node nos
+ * gates, e ler um global do navegador aqui é o ACHADO 15 outra vez — o `srAlert` que rebentou o boot contra um
+ * documento injectado.
+ * 📌 E o PADRÃO É «não instalada», que é seguro por uma razão que não vale para todos os padrões deste
+ * repositório: sem detector a opção fica desabilitada COM a mensagem, e a mensagem diz ao adulto exactamente
+ * o que fazer. O silêncio não decide nada contra a criança — ele mantém o estado que já existia e que é
+ * accionável. É o oposto do `seguraTeclas`, onde os dois lados do padrão erravam.
+ */
+export function faceDisponivel(it, instalada) {
+    if (!it.off)
+        return true;
+    return !!instalada && familiasDaFace(it).some((f) => instalada(f));
+}
+/** As faces que o MENU pode oferecer: só as gerais (emenda do ADR-0012). */
+export const OFERECIVEIS = FONT_GROUPS.flatMap((g) => g.items).filter((it) => papelDaFonte(it) === 'geral');
 export const FONT_BY_KEY = {};
 FONT_GROUPS.forEach((g) => g.items.forEach((it) => { FONT_BY_KEY[it.k] = it; }));
 export const FONT_KEY = 'incl_font_k';
@@ -41,10 +132,22 @@ export const FONT_KEY_LEGACY = 'incl_fonte'; // pre-Fase-2: 'alfabetizacao' | 'd
  * porque duas cópias de um padrão são duas chances de o reset devolver algo que o jogo nunca usou.
  */
 export const DEFAULT_FONT_KEY = 'atkinson';
-/** Boot choice: validated persisted key (ignores .off fonts) -> legacy-key migration -> DEFAULT_FONT_KEY. */
+/**
+ * Boot choice: validated persisted key (ignores .off fonts) -> legacy-key migration -> DEFAULT_FONT_KEY.
+ *
+ * ⚠️ E UMA CALIGRÁFICA GUARDADA VOLTA AO PADRÃO (issue #87, 2026-09-07). Antes da emenda do ADR-0012 o menu
+ * oferecia as sete caligráficas, então há crianças com `pinyon` ou `ufmag` guardados — e o valor salvo
+ * continua a ser escolha delas, que não é nossa para desfazer sem motivo. O motivo existe: a emenda diz que
+ * uma caligráfica **não pode ser a face da interface**, e o menu deixou de a oferecer. Deixá-la valer daria
+ * uma interface inteira em letra cursiva a quem já não tem como sair dela pelo menu — uma armadilha, e das
+ * silenciosas.
+ *
+ * ⚠️ E UMA CHAVE APAGADA TAMBÉM VOLTA, pelo mesmo caminho: as quatro faces que saíram do roster já não estão
+ * no `FONT_BY_KEY`, então quem tinha `greatvibes` guardado cai no padrão em vez de ficar sem face nenhuma.
+ */
 export function resolveFontKey(s) {
     const k = s.get(FONT_KEY, null);
-    if (k && FONT_BY_KEY[k] && !FONT_BY_KEY[k].off)
+    if (k && FONT_BY_KEY[k] && !FONT_BY_KEY[k].off && papelDaFonte(FONT_BY_KEY[k]) === 'geral')
         return k;
     const leg = s.get(FONT_KEY_LEGACY, null);
     if (leg === 'alfabetizacao')