@the-inclusionist/engine 6.36.1

package/dist-pkg/render/viewports.d.ts

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { RenderizarEm } from './port.js';
+/** O que `pixiFilterFor` toca de um `PIXI.ColorMatrixFilter` — e só isso. */
+interface ColorMatrixLike {
+    matrix: number[];
+    brightness(b: number, multiply: boolean): void;
+    contrast(amount: number, multiply: boolean): void;
+}
+interface ColorMatrixCtor {
+    new (): ColorMatrixLike;
+}
+/** `PIXI.BlurFilter` é opaco aqui: só se constrói com a força e se entrega para o `filters` do sprite. */
+interface BlurCtor {
+    new (strength: number): unknown;
+}
+/** O sprite reaproveitado para carimbar o overlay de baixa visão — só a textura é trocada. */
+interface TexturedSprite {
+    texture: unknown;
+}
+/** `app.renderer` — só a passada extra em render-texture (`clear:false` = por cima da cena já desenhada). */
+export interface ViewportsCtx {
+    ColorMatrixFilter: ColorMatrixCtor | null | undefined;
+    BlurFilter: BlurCtor | null | undefined;
+    parallaxTexNormal: unknown[];
+    getTreeTexNormal: () => unknown;
+    getLvOverlaySpr: () => TexturedSprite;
+    renderizarEm: RenderizarEm;
+    getVpTex: () => unknown[];
+    cvdDefsHost: Element | null;
+}
+export interface ViewportsApi {
+    /** Camada de parallax `i` no `mode`: alto contraste recua o fundo (dessatura/escurece); resto = textura crua. */
+    parallaxTexFor(i: number, mode: string): unknown;
+    /** Decoração de fundo (árvore) no `mode`: mesma regra do parallax, cache próprio. */
+    treeTexFor(mode: string): unknown;
+    /** Quadro do jogador no `mode`: alto contraste ganha contorno escuro (salta do fundo recuado). */
+    playerVizTex(base: unknown, mode: string): unknown;
+    /** Filtro GPU do viewport para o `mode` (array de filtros, ou `null` quando o modo não usa filtro). */
+    pixiFilterFor(mode: string): unknown;
+    /** Canvas 320×180 do overlay de baixa visão (`haze`/`tunnel`/`macular`/`diabetic`). */
+    lvOverlayCanvas(lv: string): HTMLCanvasElement;
+    /** Textura do overlay de baixa visão (memoizada). `blur` não tem overlay — é filtro puro → `null`. */
+    lvOverlayTex(lv: string): unknown;
+    /** Carimba o overlay de baixa visão do jogador `i` DENTRO da render-texture do viewport, por cima da cena. */
+    renderVpOverlay(i: number, mode: string): void;
+    /** Invalida o cache de parallax recolorido — o cenário mudou, as texturas cruas são outras. */
+    clearParallaxTexCache(): void;
+    /** Invalida o cache de quadros do jogador com contorno (chamado por `rebakeDirect` em viz-setters). */
+    clearPlayerDirectCache(): void;
+}
+export declare function initViewports(ctx: ViewportsCtx): ViewportsApi;
+export {};

package/dist-pkg/render/viewports.js

@@ -0,0 +1,185 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/viewports — a FÁBRICA de imagem dos modos de visão acessível: como um MODO vira PIXEL.
+//
+// Par de render/viz-setters, que levou a POLÍTICA ("qual modo vale onde": por jogador, global, overlays, painéis).
+// Aqui mora a outra metade — a produção do pixel em si, que a política consome:
+//   · `pixiFilterFor`  — modo → filtro GPU do viewport (daltonismo, cegueira, baixa visão)
+//   · `parallaxTexFor` — camada de fundo i, recolorida (ou não) para o modo
+//   · `treeTexFor`     — decoração de fundo, idem
+//   · `playerVizTex`   — quadro do jogador com contorno escuro no alto contraste
+//   · `lvOverlay*` / `renderVpOverlay` — a névoa/túnel/mancha de baixa visão DENTRO da render-texture do viewport
+// Os quatro primeiros entravam em viz-setters por injeção (`parallaxTexFor`/`treeTexFor`/`playerVizTex`/
+// `pixiFilterFor` no `VizSettersCtx`) enquanto ainda moravam no game.js; a partir daqui quem os fornece é este
+// módulo. Ver docs/5-Refactoring/plano-modularizacao-mapa.md (B2).
+//
+// A DUPLICAÇÃO QUE ESTA EXTRAÇÃO CUROU: as seis matrizes de daltonismo estavam escritas duas vezes — como
+// `<feColorMatrix>` no app/index.html (caminho de tela única) e como `PIXI.ColorMatrixFilter` dentro de
+// `pixiFilterFor` (caminho multi-tela). Saíram para render/cvd-matrices (folha, zero deps); `pixiFilterFor` lê
+// de lá e `initViewports` GERA os `<filter>` do documento de lá também. O sintoma da divergência era silencioso
+// e de acessibilidade: a mesma pessoa daltônica veria cores diferentes em tela única e em multi-tela.
+//
+// Fronteiras que este módulo NÃO reabre:
+//  · `parallaxTexNormal` e `treeTexNormal` (as texturas CRUAS, fonte do recolor) continuam nascendo no game.js
+//    — a primeira é preenchida por `setCenario` (carrega PNG por tema), a segunda pelo desenho procedural da
+//    árvore. Entram injetadas. `parallaxTexNormal` é `const` cujos ELEMENTOS `setCenario` troca in place → entra
+//    por VALOR (o array é o mesmo objeto); `vpTex` é `let` que `configureRender` REATRIBUI a cada troca de nº de
+//    telas → entra por GETTER.
+//  · `lvOverlaySpr` e o renderer são objetos PIXI criados no game.js e entram por interface ESTRUTURAL, para o
+//    módulo rodar no project `node` sem importar PIXI. Mesmo precedente de render/scene-sky e game/traffic.
+//  · `_lastSharedViz` NÃO é daqui (é o registro do render estático, fica no game.js) — ver o topo de viz-setters.
+//
+// POR QUE `getTreeTexNormal`/`getLvOverlaySpr` são GETTERS e não valores, sendo os dois `const` no game.js:
+// não é reatribuição, é ORDEM DE BOOT. `clearParallaxTexCache` precisa existir dentro de `setCenario`, que o
+// game.js chama no topo do módulo (na restauração do cenário salvo) — bem ANTES de `treeTexNormal` e
+// `lvOverlaySpr` serem declarados. Com getters, `initViewports` pode ser chamado cedo o bastante para aquela
+// chamada não cair em TDZ; com valores, o `const` ainda não inicializado derrubaria a restauração do tema
+// dentro de um `try/catch` que apenas cai para 'cidade' — o jogador perderia o cenário escolhido em silêncio.
+//
+// SEM I/O no import: nada de makeCanvas/tex no corpo do módulo (precedente de render/textures). O único efeito
+// de `initViewports` é gerar os `<filter>` SVG, que é justamente o ponto da cura da duplicação.
+import { LOGICAL_W, LOGICAL_H } from '../core/constants.js';
+import { makeCanvas, tex } from './canvas.js';
+import { DIRECT_CFG, directBgTexture, directSpriteTexture } from './high-contrast.js';
+import { VIZ_BY_KEY } from './viz-modes.js';
+import { CVD_MATRIX, installCvdFilters } from './cvd-matrices.js';
+export function initViewports(ctx) {
+    // Gera os seis <filter> de daltonismo do documento a partir de render/cvd-matrices — a MESMA fonte que
+    // pixiFilterFor lê logo abaixo. É por isso que tela única e multi-tela não podem mais divergir.
+    installCvdFilters(ctx.cvdDefsHost);
+    /* ===================== fundo: parallax e decoração ===================== */
+    const _parallaxTexHC = {}; // {mode: [tex,tex,tex]}
+    function parallaxTexFor(i, mode) {
+        if (DIRECT_CFG[mode]) {
+            (_parallaxTexHC[mode] = _parallaxTexHC[mode] || []);
+            if (!_parallaxTexHC[mode][i])
+                _parallaxTexHC[mode][i] = directBgTexture(ctx.parallaxTexNormal[i], mode);
+            return _parallaxTexHC[mode][i]; // direto: fundo recua
+        }
+        return ctx.parallaxTexNormal[i];
+    }
+    function clearParallaxTexCache() { for (const k in _parallaxTexHC)
+        delete _parallaxTexHC[k]; }
+    const _treeTexHC = {};
+    function treeTexFor(mode) {
+        if (DIRECT_CFG[mode]) {
+            if (!_treeTexHC[mode])
+                _treeTexHC[mode] = directBgTexture(ctx.getTreeTexNormal(), mode);
+            return _treeTexHC[mode]; // direto: decoração recua
+        }
+        return ctx.getTreeTexNormal();
+    }
+    /* ===================== frente: o jogador ===================== */
+    // {mode: Map<texturaBase, texturaComContorno>} — chaveado pela textura de ORIGEM porque o jogador troca de
+    // quadro toda frame; um Map por modo evita recontornar o mesmo quadro a cada volta da animação.
+    let _playerDirect = {};
+    function playerVizTex(base, mode) {
+        if (!base)
+            return base;
+        if (DIRECT_CFG[mode]) {
+            const mm = (_playerDirect[mode] = _playerDirect[mode] || new Map());
+            if (!mm.has(base))
+                mm.set(base, directSpriteTexture(base, mode));
+            return mm.get(base); // direto: player com contorno escuro → salta
+        }
+        return base;
+    }
+    function clearPlayerDirectCache() { _playerDirect = {}; }
+    /* ===================== o filtro do viewport ===================== */
+    // Cacheado por MODO e por identidade: o mesmo array de filtros volta sempre, então trocar de viewport não
+    // reconstrói o filtro (nem invalida o shader do PIXI). Guarda `null` também — `mode in cache` e não
+    // `cache[mode]` — para que modo sem filtro (normal, hc-*) não seja reprocessado a cada frame.
+    const _vpFilterCache = {};
+    function pixiFilterFor(mode) {
+        if (mode in _vpFilterCache)
+            return _vpFilterCache[mode];
+        let f = null;
+        const CM = ctx.ColorMatrixFilter, BL = ctx.BlurFilter;
+        const cvd = CVD_MATRIX[mode]; // fonte única: os MESMOS números que geram o <feColorMatrix> do HTML
+        if (cvd && CM) {
+            const c = new CM();
+            c.matrix = cvd.slice();
+            f = [c];
+        } // slice: o filtro não fica com o array do módulo
+        else if (mode === 'blind' && CM) {
+            const c = new CM();
+            c.brightness(0, false);
+            f = [c];
+        }
+        else if (mode === 'lv-blur' && BL) {
+            f = [new BL(5)];
+        }
+        else if (mode === 'lv-haze' && CM) {
+            const c = new CM();
+            c.contrast(-0.45, false);
+            c.brightness(1.12, true);
+            f = [c];
+        }
+        else if ((mode === 'lv-tunnel' || mode === 'lv-diabetic' || mode === 'lv-macular') && BL) {
+            f = [new BL(mode === 'lv-tunnel' ? 1.5 : 2)];
+        }
+        return _vpFilterCache[mode] = f;
+    }
+    /* ===================== baixa visão: o overlay como textura ===================== */
+    // O que o filtro GPU não sabe fazer: névoa de catarata, o túnel do glaucoma, a mancha central da degeneração
+    // macular e as manchas espalhadas da retinopatia. São desenho, não transformação de cor — vêm como textura.
+    function lvOverlayCanvas(lv) {
+        const W = LOGICAL_W, H = LOGICAL_H, cv = makeCanvas(W, H), c = cv.getContext('2d'), cx = W / 2, cy = H / 2;
+        if (lv === 'haze') {
+            c.fillStyle = 'rgba(244,246,250,0.42)';
+            c.fillRect(0, 0, W, H);
+        }
+        else if (lv === 'tunnel') {
+            const g = c.createRadialGradient(cx, cy, H * 0.12, cx, cy, H * 0.6);
+            g.addColorStop(0, 'rgba(0,0,0,0)');
+            g.addColorStop(.5, 'rgba(0,0,0,.55)');
+            g.addColorStop(1, 'rgba(0,0,0,.99)');
+            c.fillStyle = g;
+            c.fillRect(0, 0, W, H);
+        }
+        else if (lv === 'macular') {
+            const g = c.createRadialGradient(cx, cy, 2, cx, cy, H * 0.34);
+            g.addColorStop(0, 'rgba(12,12,15,.95)');
+            g.addColorStop(.55, 'rgba(12,12,15,.5)');
+            g.addColorStop(1, 'rgba(12,12,15,0)');
+            c.fillStyle = g;
+            c.fillRect(0, 0, W, H);
+        }
+        else if (lv === 'diabetic') {
+            for (const [fx, fy, fr] of [[.22, .3, .1], [.64, .22, .075], [.8, .58, .11], [.4, .7, .085], [.16, .8, .07], [.54, .48, .06]]) {
+                const x = fx * W, y = fy * H, r = fr * W, g = c.createRadialGradient(x, y, 1, x, y, r);
+                g.addColorStop(0, 'rgba(10,10,14,.95)');
+                g.addColorStop(.5, 'rgba(10,10,14,.7)');
+                g.addColorStop(1, 'rgba(10,10,14,0)');
+                c.fillStyle = g;
+                c.fillRect(x - r, y - r, 2 * r, 2 * r);
+            }
+        }
+        return cv;
+    }
+    const _lvOverlayTex = {};
+    function lvOverlayTex(lv) {
+        if (lv === 'blur')
+            return null; // desfoque é filtro puro, não tem o que carimbar
+        if (!_lvOverlayTex[lv])
+            _lvOverlayTex[lv] = tex(lvOverlayCanvas(lv));
+        return _lvOverlayTex[lv];
+    }
+    // Overlay DENTRO da render-texture (a bolinha indicadora do viewport fica por cima, FORA do filtro — é por
+    // isso que ela continua visível no modo cegueira; ver updateVpDots em render/viz-setters).
+    function renderVpOverlay(i, mode) {
+        const m = VIZ_BY_KEY[mode];
+        if (!m || m.kind !== 'lowvision')
+            return;
+        const t = lvOverlayTex(m.lv);
+        if (t) {
+            const spr = ctx.getLvOverlaySpr();
+            spr.texture = t;
+            ctx.renderizarEm(spr, ctx.getVpTex()[i], false);
+        }
+    }
+    return {
+        parallaxTexFor, treeTexFor, playerVizTex, pixiFilterFor,
+        lvOverlayCanvas, lvOverlayTex, renderVpOverlay,
+        clearParallaxTexCache, clearPlayerDirectCache,
+    };
+}

package/dist-pkg/render/viz-axes.d.ts

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** O eixo do CONTRASTE. `padrao` não é ausência de tema: é o tema desenhado do jogo. */
+export type Tema = 'padrao' | 'hc3' | 'hc45' | 'hc7';
+/** O eixo da CORREÇÃO DE COR. `tricro` = visão tricromática, e é um nome, não uma ausência. */
+export type Correcao = 'tricro' | 'protan' | 'deuter' | 'tritan';
+/** A simulação, que NÃO é eixo. `null` = nenhuma a correr. */
+export type Simulacao = null | 'sim-protan' | 'sim-deuter' | 'sim-tritan' | 'lv-blur' | 'lv-haze' | 'lv-tunnel' | 'lv-macular' | 'lv-diabetic' | 'blind';
+/** O estado visual de UM jogador. Substitui a string única de `p.viz`. */
+export interface VisualState {
+    readonly tema: Tema;
+    readonly correcao: Correcao;
+    readonly simulacao: Simulacao;
+}
+export declare const PADRAO: VisualState;
+/**
+ * Os dois eixos estão no padrão?
+ *
+ * ⚠️ É A PERGUNTA QUE LIBERA A SIMULAÇÃO, e é por isso que ela é uma função e não um booleano guardado:
+ * guardar o resultado deixaria as duas coisas divergirem, e a divergência aqui significa uma demonstração a
+ * correr por cima de uma adaptação — que ensina uma coisa falsa.
+ */
+export declare function nosPadroes(v: VisualState): boolean;
+/**
+ * Esta simulação pode correr AGORA? E se não, por quê?
+ *
+ * ⚠️ DEVOLVE O MOTIVO E NÃO SÓ `false`. O ADR-0076 exige que a recusa seja VISÍVEL e explicada — nunca
+ * silenciosamente removida, nunca aceita e depois ignorada. E o motivo é um FACTO SOBRE A DEMONSTRAÇÃO, não
+ * uma repreensão a quem escolheu: quem ligou o alto contraste ligou-o porque precisa.
+ */
+export type MotivoIndisponivel = 'tema' | 'correcao' | 'ambos';
+export declare function simulacaoIndisponivel(v: VisualState): MotivoIndisponivel | null;
+/** A chave de modo DIRETO que este tema usa, ou `null` para o tema padrão. */
+export declare function temaDireto(v: VisualState): string | null;
+/**
+ * A chave de FILTRO CSS que este estado usa, ou `null`.
+ *
+ * ⚠️ SIMULAÇÃO VENCE CORREÇÃO AQUI, e não é uma regra de precedência escondida: as duas não podem coexistir
+ * porque `simulacaoIndisponivel` já as separa — uma simulação só corre com a correção no padrão. Este `??`
+ * é o que acontece quando alguém constrói um estado à mão que a interface não deixaria montar, e escolher a
+ * simulação é o menos errado dos dois: ela é a intenção mais recente e mais visível.
+ */
+export declare function filtroChave(v: VisualState): string | null;
+/**
+ * As DUAS coisas que a raiz precisa aplicar, num objeto só.
+ *
+ * ⚠️ Devolver os dois JUNTOS é o ponto da issue #104: enquanto eram um campo, aplicar um apagava o outro.
+ * Aqui um estado com tema `hc7` e correção `deuter` devolve os dois preenchidos, e é o que o gate afirma.
+ */
+export interface Aplicacao {
+    /** A chave do modo direto (alto contraste), ou `null`. */
+    readonly direto: string | null;
+    /** A chave do filtro CSS (correção ou simulação), ou `null`. */
+    readonly filtro: string | null;
+}
+export declare function aplicacao(v: VisualState): Aplicacao;
+/** Há uma simulação a correr? É a pergunta que `simulatesDisability` fazia à string. */
+export declare function ehSimulacao(v: VisualState): boolean;
+/** É a simulação de CEGUEIRA? O quiz e o sonar perguntam isto para se comportarem sem tela. */
+export declare function ehCego(v: VisualState): boolean;
+/** É uma das cinco simulações de BAIXA VISÃO? Elas pedem o overlay como textura, e não só um filtro. */
+export declare function ehBaixaVisao(v: VisualState): boolean;
+/** O tema está fora do padrão? Era o `/^hc-direto/.test(s.viz)` espalhado pela interface. */
+export declare function temAltoContraste(v: VisualState): boolean;
+/** Próximo TEMA no ciclo do ícone da barra rápida. Anda só no seu eixo, e não toca na correção. */
+export declare function proximoTema(v: VisualState): VisualState;
+/**
+ * Próxima CORREÇÃO no ciclo do ícone. Anda só no seu eixo, e não toca no tema.
+ *
+ * ⚠️ A ASSIMETRIA DO ORIGINAL FICA REGISTRADA E NÃO É COPIADA: `nextCvd` mapeava um valor desconhecido para
+ * o ÍNDICE 1 (`fix-protan`) enquanto `nextContrast` mapeava para 0. Era um comentário no ficheiro a explicar
+ * uma diferença que ninguém tinha decidido. Aqui as duas começam no padrão, porque um valor desconhecido é
+ * exatamente o caso em que não se sabe o que a criança queria — e o padrão é a única resposta que não
+ * escolhe por ela.
+ */
+export declare function proximaCorrecao(v: VisualState): VisualState;
+/**
+ * A chave que o sprite do jogador usa para escolher textura.
+ *
+ * ⚠️ É a SIMULAÇÃO quando há uma, e o TEMA quando não há — nesta ordem porque é a ordem do que a criança vê:
+ * uma cegueira simulada apaga a tela inteira, e nesse instante o tema não muda nada do que ela percebe.
+ */
+export declare function chaveDeTextura(v: VisualState): string;
+/**
+ * Traduz o valor salvo. Aceita o antigo (string) e o novo (objeto), e devolve sempre um estado válido.
+ *
+ * ⚠️ IDEMPOTENTE POR CONSTRUÇÃO: um objeto já migrado atravessa com os campos conferidos. Importa porque a
+ * leitura acontece por jogador e mais de uma vez por sessão.
+ *
+ * ⚠️ E DESCONHECIDO CAI NO PADRÃO EM VEZ DE ESTOURAR. O dado vem do navegador de uma criança e pode ser de
+ * uma versão futura, de outra máquina, ou lixo. Um `throw` aqui tiraria o jogo do ar por causa de uma
+ * preferência; o padrão apenas devolve o jogo como ele nasce.
+ */
+export declare function migrarVisual(salvo: unknown): VisualState;
+export declare const TEMAS: readonly Tema[];
+export declare const CORRECOES: readonly Correcao[];
+export declare const SIMULACOES: readonly Simulacao[];
+/** As chaves antigas que a migração conhece — exportada para o gate poder exigir que TODAS estejam cobertas. */
+export declare const CHAVES_ANTIGAS: readonly string[];

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

@@ -0,0 +1,184 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/viz-axes — OS DOIS EIXOS, e a simulação que NÃO é um deles (ADR-0076). Módulo-folha, zero deps.
+//
+// ========================= O DEFEITO QUE ISTO CONSERTA =========================
+// Hoje o menu visual é UM rádio e `p.viz` guarda UMA string. Escolher `fix-deuter` desliga o contraste 7:1;
+// escolher um nível de contraste desliga a correção. ⚠️ UMA CRIANÇA COM DALTONISMO QUE TAMBÉM PRECISE DE
+// ALTO CONTRASTE NÃO PODE TER OS DOIS — e as duas necessidades coexistem numa mesma pessoa com frequência.
+//
+// ========================= POR QUE A SIMULAÇÃO NÃO É UM EIXO =========================
+// Correção e simulação são ambas implementadas como filtro e servem a PROPÓSITOS OPOSTOS: uma deixa uma
+// criança JOGAR, a outra deixa alguém SENTIR como é não conseguir. Agrupá-las pelo mecanismo já as fundiu
+// duas vezes — no ADR-0011 (as correções listadas no painel de Empatia, de modo que *«a criança que
+// PRECISAVA da correção tinha de a procurar no menu sobre fingir»*) e no ADR-0075.
+//
+// ⚠️ UM GRUPO DE AJUSTES CHAMA-SE PELO QUE ELE SERVE, NUNCA PELO COMO É IMPLEMENTADO.
+//
+// ========================= E POR QUE A SIMULAÇÃO É TRAVADA NOS DOIS PADRÕES =========================
+// De uma tela já corrigida, uma simulação não mostra nem a deficiência nem a correção; por cima de um tema
+// de alto contraste, mostra o que o tema faz e não o que a deuteranopia faz. Uma demonstração a correr em
+// cima de uma adaptação não é uma demonstração mais fraca — **ela ensina uma coisa falsa**.
+export const PADRAO = Object.freeze({ tema: 'padrao', correcao: 'tricro', simulacao: null });
+/**
+ * Os dois eixos estão no padrão?
+ *
+ * ⚠️ É A PERGUNTA QUE LIBERA A SIMULAÇÃO, e é por isso que ela é uma função e não um booleano guardado:
+ * guardar o resultado deixaria as duas coisas divergirem, e a divergência aqui significa uma demonstração a
+ * correr por cima de uma adaptação — que ensina uma coisa falsa.
+ */
+export function nosPadroes(v) {
+    return v.tema === 'padrao' && v.correcao === 'tricro';
+}
+export function simulacaoIndisponivel(v) {
+    const t = v.tema !== 'padrao';
+    const c = v.correcao !== 'tricro';
+    if (t && c)
+        return 'ambos';
+    if (t)
+        return 'tema';
+    if (c)
+        return 'correcao';
+    return null;
+}
+/* ===================== A COMPOSIÇÃO ===================== */
+//
+// ⚠️ ELA JÁ ERA MECANICAMENTE POSSÍVEL, e é isso que torna o defeito mais caro do que parecia: o TEMA de
+// alto contraste vai pela RENDERIZAÇÃO DIRETA (`DIRECT_CFG`/PIXI) e a CORREÇÃO vai por FILTRO CSS
+// (`url(#cvd-fix-*)`). São dois mecanismos que não colidem. O que impedia os dois de coexistir não era a
+// máquina — era o campo único que só cabia um valor.
+/** A chave de modo DIRETO que este tema usa, ou `null` para o tema padrão. */
+export function temaDireto(v) {
+    return v.tema === 'hc3' ? 'hc-direto'
+        : v.tema === 'hc45' ? 'hc-direto-45'
+            : v.tema === 'hc7' ? 'hc-direto-7'
+                : null;
+}
+/**
+ * A chave de FILTRO CSS que este estado usa, ou `null`.
+ *
+ * ⚠️ SIMULAÇÃO VENCE CORREÇÃO AQUI, e não é uma regra de precedência escondida: as duas não podem coexistir
+ * porque `simulacaoIndisponivel` já as separa — uma simulação só corre com a correção no padrão. Este `??`
+ * é o que acontece quando alguém constrói um estado à mão que a interface não deixaria montar, e escolher a
+ * simulação é o menos errado dos dois: ela é a intenção mais recente e mais visível.
+ */
+export function filtroChave(v) {
+    if (v.simulacao)
+        return v.simulacao;
+    return v.correcao === 'tricro' ? null : 'fix-' + (v.correcao === 'deuter' ? 'deuter' : v.correcao);
+}
+export function aplicacao(v) {
+    return { direto: temaDireto(v), filtro: filtroChave(v) };
+}
+/* ===================== O QUE OS LEITORES DE FACTO PERGUNTAM ===================== */
+//
+// ⚠️ ESTAS FUNÇÕES SAÍRAM DE UMA MEDIDA, e não de um desenho a priori. Os 31 leitores de `p.viz` foram
+// classificados pelo que PERGUNTAM, e a lista curta abaixo é o resultado — quatro perguntam o «kind», duas
+// se é simulação, uma a textura, e o resto é escrita. Um leitor que precise de algo fora daqui é sinal de
+// que a pergunta dele merecia um nome.
+//
+// ⚠️ E A MEDIDA TROUXE UM ACHADO: `ui/pause-icons` já tem `nextContrast` e `nextCvd`, cada uma a ciclar
+// DENTRO do seu eixo. A interface já pensava em dois eixos há muito tempo; era o ARMAZENAMENTO que os
+// colapsava num campo. As funções de ciclo abaixo são as mesmas duas, agora com onde guardar o resultado.
+/** Há uma simulação a correr? É a pergunta que `simulatesDisability` fazia à string. */
+export function ehSimulacao(v) {
+    return v.simulacao !== null;
+}
+/** É a simulação de CEGUEIRA? O quiz e o sonar perguntam isto para se comportarem sem tela. */
+export function ehCego(v) {
+    return v.simulacao === 'blind';
+}
+/** É uma das cinco simulações de BAIXA VISÃO? Elas pedem o overlay como textura, e não só um filtro. */
+export function ehBaixaVisao(v) {
+    return v.simulacao !== null && v.simulacao.startsWith('lv-');
+}
+/** O tema está fora do padrão? Era o `/^hc-direto/.test(s.viz)` espalhado pela interface. */
+export function temAltoContraste(v) {
+    return v.tema !== 'padrao';
+}
+/** Próximo TEMA no ciclo do ícone da barra rápida. Anda só no seu eixo, e não toca na correção. */
+export function proximoTema(v) {
+    const i = TEMAS.indexOf(v.tema);
+    return { ...v, tema: TEMAS[(i < 0 ? 0 : i + 1) % TEMAS.length] };
+}
+/**
+ * Próxima CORREÇÃO no ciclo do ícone. Anda só no seu eixo, e não toca no tema.
+ *
+ * ⚠️ A ASSIMETRIA DO ORIGINAL FICA REGISTRADA E NÃO É COPIADA: `nextCvd` mapeava um valor desconhecido para
+ * o ÍNDICE 1 (`fix-protan`) enquanto `nextContrast` mapeava para 0. Era um comentário no ficheiro a explicar
+ * uma diferença que ninguém tinha decidido. Aqui as duas começam no padrão, porque um valor desconhecido é
+ * exatamente o caso em que não se sabe o que a criança queria — e o padrão é a única resposta que não
+ * escolhe por ela.
+ */
+export function proximaCorrecao(v) {
+    const i = CORRECOES.indexOf(v.correcao);
+    return { ...v, correcao: CORRECOES[(i < 0 ? 0 : i + 1) % CORRECOES.length] };
+}
+/**
+ * A chave que o sprite do jogador usa para escolher textura.
+ *
+ * ⚠️ É a SIMULAÇÃO quando há uma, e o TEMA quando não há — nesta ordem porque é a ordem do que a criança vê:
+ * uma cegueira simulada apaga a tela inteira, e nesse instante o tema não muda nada do que ela percebe.
+ */
+export function chaveDeTextura(v) {
+    return v.simulacao ?? temaDireto(v) ?? 'normal';
+}
+/* ===================== A MIGRAÇÃO ===================== */
+//
+// ⚠️ ELA NÃO É OPCIONAL E VEM ANTES DA PRIMEIRA LEITURA DA FORMA NOVA. O ajuste salvo guarda o valor único
+// antigo; sem a tradução, o modo visual que cada criança já escolheu é DESCARTADO — e quem escolheu um
+// desses valores escolheu-o porque enxerga assim.
+/** O valor único antigo → o estado de dois eixos. Chave desconhecida cai no padrão, e nunca estoura. */
+const DE_CHAVE_UNICA = Object.freeze({
+    normal: PADRAO,
+    // Os três níveis de contraste viram TEMA, e a correção fica no padrão.
+    'hc-direto': { tema: 'hc3', correcao: 'tricro', simulacao: null },
+    'hc-direto-45': { tema: 'hc45', correcao: 'tricro', simulacao: null },
+    'hc-direto-7': { tema: 'hc7', correcao: 'tricro', simulacao: null },
+    // As três correções viram CORREÇÃO, e o tema fica no padrão.
+    'fix-protan': { tema: 'padrao', correcao: 'protan', simulacao: null },
+    'fix-deuter': { tema: 'padrao', correcao: 'deuter', simulacao: null },
+    'fix-tritan': { tema: 'padrao', correcao: 'tritan', simulacao: null },
+    // ⚠️ AS NOVE SIMULAÇÕES VOLTAM COM OS DOIS EIXOS NO PADRÃO, e não é perda de informação: uma simulação
+    // só era possível a partir do padrão de qualquer maneira, porque ela SUBSTITUÍA tudo o resto. O que a
+    // forma nova acrescenta é dizer isso em vez de o deixar implícito.
+    'sim-protan': { tema: 'padrao', correcao: 'tricro', simulacao: 'sim-protan' },
+    'sim-deuter': { tema: 'padrao', correcao: 'tricro', simulacao: 'sim-deuter' },
+    'sim-tritan': { tema: 'padrao', correcao: 'tricro', simulacao: 'sim-tritan' },
+    'lv-blur': { tema: 'padrao', correcao: 'tricro', simulacao: 'lv-blur' },
+    'lv-haze': { tema: 'padrao', correcao: 'tricro', simulacao: 'lv-haze' },
+    'lv-tunnel': { tema: 'padrao', correcao: 'tricro', simulacao: 'lv-tunnel' },
+    'lv-macular': { tema: 'padrao', correcao: 'tricro', simulacao: 'lv-macular' },
+    'lv-diabetic': { tema: 'padrao', correcao: 'tricro', simulacao: 'lv-diabetic' },
+    blind: { tema: 'padrao', correcao: 'tricro', simulacao: 'blind' },
+});
+/**
+ * Traduz o valor salvo. Aceita o antigo (string) e o novo (objeto), e devolve sempre um estado válido.
+ *
+ * ⚠️ IDEMPOTENTE POR CONSTRUÇÃO: um objeto já migrado atravessa com os campos conferidos. Importa porque a
+ * leitura acontece por jogador e mais de uma vez por sessão.
+ *
+ * ⚠️ E DESCONHECIDO CAI NO PADRÃO EM VEZ DE ESTOURAR. O dado vem do navegador de uma criança e pode ser de
+ * uma versão futura, de outra máquina, ou lixo. Um `throw` aqui tiraria o jogo do ar por causa de uma
+ * preferência; o padrão apenas devolve o jogo como ele nasce.
+ */
+export function migrarVisual(salvo) {
+    if (typeof salvo === 'string')
+        return DE_CHAVE_UNICA[salvo] ?? PADRAO;
+    if (salvo && typeof salvo === 'object') {
+        const o = salvo;
+        return {
+            tema: TEMAS.includes(o.tema) ? o.tema : PADRAO.tema,
+            correcao: CORRECOES.includes(o.correcao) ? o.correcao : PADRAO.correcao,
+            simulacao: SIMULACOES.includes(o.simulacao) ? o.simulacao : null,
+        };
+    }
+    return PADRAO;
+}
+export const TEMAS = ['padrao', 'hc3', 'hc45', 'hc7'];
+export const CORRECOES = ['tricro', 'protan', 'deuter', 'tritan'];
+export const SIMULACOES = [
+    null, 'sim-protan', 'sim-deuter', 'sim-tritan',
+    'lv-blur', 'lv-haze', 'lv-tunnel', 'lv-macular', 'lv-diabetic', 'blind',
+];
+/** As chaves antigas que a migração conhece — exportada para o gate poder exigir que TODAS estejam cobertas. */
+export const CHAVES_ANTIGAS = Object.keys(DE_CHAVE_UNICA);

package/dist-pkg/render/viz-modes.d.ts

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * `sim` — este modo SIMULA uma deficiência em quem não a tem, em vez de CORRIGIR a tela para quem a tem.
+ *
+ * O `kind` não responde a isso e nunca respondeu: `sim-deuter` (simular daltonismo) e `fix-deuter` (corrigir
+ * daltonismo) compartilham `kind:'filter'`, ainda que sirvam a duas pessoas opostas. Enquanto ninguém
+ * precisava distinguir, a lacuna era inofensiva. Passou a não ser quando o menu de empatia ganhou um
+ * "restaurar padrões" (ADR-0028): desligar as simulações é o objetivo do botão, e desligar as correções junto
+ * seria tirar de uma criança daltônica a única correção que ela tem — a partir do menu que existe para quem
+ * NÃO tem a deficiência. Um reset que faz isso é pior que a armadilha que ele deveria desfazer.
+ *
+ * Só os 9 modos marcados simulam. Os 3 `fix-*` corrigem, os 3 `hc-direto*` corrigem, e `normal` não faz nada.
+ */
+/**
+ * Um modo de visão. `nome` e `desc` guardam CHAVE i18n, não texto — mesma decisão de `CenarioTema.nome` 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. Este menu é o que uma criança de baixa visão ou daltônica lê para configurar o
+ * PRÓPRIO jogo; deixá-lo em português numa build em inglês tira dela a única página que ela precisava ler.
+ *
+ * Quem EXIBE resolve (`render/viz-setters`, `consumer-quiz`), e por isso este módulo continua FOLHA: dado
+ * puro, sem dependência nenhuma, importável dos dois lados da fronteira.
+ */
+export type VizMode = {
+    key: string;
+    kind: string;
+    nome: string;
+    desc: string;
+    lv?: string;
+    sim?: true;
+};
+export declare const VIZ_MODES: VizMode[];
+export declare const VIZ_BY_KEY: Record<string, VizMode>;
+export declare const VIZ_FILTER: Record<string, string>;
+export declare const VIZ_CYCLE: string[];
+/**
+ * Este modo simula uma deficiência? Chave desconhecida (ou vazia) → false, porque a pergunta que o chamador
+ * está fazendo é "posso desligar isto sem tirar nada de ninguém?", e a resposta honesta diante do
+ * desconhecido é não.
+ */
+export declare function simulatesDisability(key: string): boolean;
+/**
+ * As CORREÇÕES de daltonismo: daltonizam a tela para quem TEM a condição. Derivadas do catálogo, nunca
+ * listadas à mão — são exatamente os filtros que não simulam.
+ *
+ * Existem como lista própria porque moram no menu de ACESSIBILIDADE VISUAL, e não no de empatia (decisão do
+ * Dev, issue #60). Ficaram anos no menu errado por um motivo que este arquivo agora conserta: `kind` não
+ * distinguia simular de corrigir, então o painel de empatia, que se recorta por `kind:'filter'`, arrastava as
+ * três junto. Dois públicos opostos na mesma lista — quem quer sentir como é ser daltônico e quem é.
+ */
+export declare const VIZ_CORRECTIONS: readonly VizMode[];
+/** Este modo precisa de um CANVAS de mundo para existir? Só os `hcnew` precisam: eles repintam texturas. */
+export declare function needsCanvas(key: string): boolean;
+/**
+ * Os modos que funcionam em QUALQUER jogo — os que se aplicam como filtro de CSS sobre um elemento.
+ *
+ * Derivada, nunca listada à mão: um modo novo entra na pilha certa por causa do `kind` que ele declara, e não
+ * porque alguém lembrou de acrescentá-lo aqui. É a mesma regra de `VIZ_CORRECTIONS`.
+ */
+export declare const VIZ_DOM_ONLY: readonly VizMode[];
+/** Os modos que EXIGEM mundo. Complemento exato de `VIZ_DOM_ONLY` — juntos, os 16, sem sobra nem repetição. */
+export declare const VIZ_CANVAS_ONLY: readonly VizMode[];