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

package/dist-pkg/platform/voice-plan.js

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/voice-plan.ts — O PLANO DAS VOZES NEURAIS (ADR-0110), na metade PURA.
+//
+// ========================= O QUE ESTE MÓDULO É =========================
+// O catálogo das quatro vozes que a engine GARANTE, a ordem por que se buscam, e — a parte que mais importa —
+// a resposta honesta a «o que é que esta criança está a ouvir AGORA». Sem rede, sem cache, sem tempo. Quem
+// busca de facto é a outra metade; quem decide O QUE buscar e o que DIZER é esta.
+//
+// ⚠️ POR QUE O CATÁLOGO VIVE AQUI E NÃO NO `TTS_SOURCES`. A tabela do `platform/tts` é indexada por idioma e
+// tem UMA voz por idioma; este catálogo tem QUATRO vozes para TRÊS idiomas, porque o en-US tem duas. Ligá-las
+// hoje mudaria comportamento: o `loadTTS` passaria a pedir `en_US-ryan-medium` à PORTA DO CARTUCHO
+// (ADR-0094), que pode não ter essa voz. A tabela liga-se a isto quando o buscador existir, e nem um dia
+// antes — uma lista ligada a um fornecedor que não a conhece é pior do que uma lista à espera.
+//
+// ⚠️ E QUAL DAS DUAS VOZES EN-US A CRIANÇA OUVE POR PADRÃO NÃO SE DECIDE AQUI. O ADR-0110 deixa-o
+// explicitamente em aberto, e a ORDEM DESTE ARRAY NÃO É UMA PREFERÊNCIA — é a ordem em que o Dev as nomeou.
+// Ler ordem como escolha seria decidir por omissão, que é o defeito que este projeto persegue.
+/**
+ * AS QUATRO QUE A ENGINE GARANTE (ADR-0110), decididas pelo Dev em 2026-09-08.
+ *
+ * ⚠️ TODAS `vits-piper` E NENHUMA `ncnn`, que o ADR-0065 §5 já proibia: `ncnn` é outro MOTOR DE INFERÊNCIA —
+ * modelos `.param`/`.bin` e não `.onnx` — e este projeto corre sherpa-onnx. Dois dos links que chegaram em
+ * 2026-09-08 apontavam para os espelhos `ncnn`, e é por isso que a proibição tem gate e não só um comentário.
+ * ⚠️ E NENHUMA `int8`, pela razão MEDIDA do mesmo §5: no backend WASM o int8 corre ~3× MAIS LENTO que o fp32
+ * (RTF 5,6 contra 2,5, do log do próprio Dev) e produz saída incorrecta ou muda. Quantizar não encurta a
+ * espera aqui — alonga-a.
+ */
+export const VOZES_NEURAIS = Object.freeze([
+    Object.freeze({ locale: 'pt-BR', engine: 'piper', voice: 'pt_BR-faber-medium' }),
+    Object.freeze({ locale: 'en-US', engine: 'piper', voice: 'en_US-ryan-medium' }),
+    Object.freeze({ locale: 'en-US', engine: 'piper', voice: 'en_US-amy-medium' }),
+    Object.freeze({ locale: 'es-MX', engine: 'piper', voice: 'es_MX-claude-high' }),
+]);
+/**
+ * DE ONDE VÊM OS MODELOS (ADR-0114), num sítio só.
+ *
+ * 📏 MEDIDO EM 2026-09-08, e não escolhido: o `piper.ttstool.com` — que o Dev nomeou ao perguntar — serve o
+ * próprio runtime da própria origem e busca os modelos aqui. As quatro vozes deste catálogo respondem 200
+ * neste endereço, com `Access-Control-Allow-Origin: *`, logo um PWA pode buscá-las de outra origem.
+ *
+ * ⚠️ UM SÍTIO SÓ É A METADE QUE O REGISTO PEDE. Um endereço repetido no ponto de uso é como o CDN do
+ * WebGazer chegou ao `ui/webcam` — escrito à mão, sem política, e sem ninguém a poder mudá-lo de uma vez.
+ *
+ * ========================= 🔴 MUDOU DE ESPELHO EM 2026-09-09, E A REGRA É «BUSCAR DE ONDE O LEITOR LÊ» ====
+ * Era `rhasspy/piper-voices`, medido a 08/09 como o espelho que o `piper.ttstool.com` usa. Depois de o
+ * `platform/pesados` passar a descer os modelos no primeiro carregamento, mediu-se o outro lado — o
+ * `@mintplex-labs/piper-tts-web@1.0.4` INSTALADO, lido do bundle e não do README — e ele busca em
+ * `diffusionstudio/piper-voices`, com uma guarda que recusa qualquer URL fora de `huggingface.co`.
+ *
+ * 🎯 ENDEREÇOS DIFERENTES SIGNIFICAM CACHE DIFERENTE: a Cache Storage é indexada pela URL do pedido, logo os
+ * 241 MB que desciam no primeiro dia NÃO ERAM LIDOS POR NINGUÉM, e a biblioteca descarregava tudo outra vez
+ * no dia em que a voz fosse pedida. Até 482 MB num link de escola para uma voz.
+ *
+ * 📏 E OS DOIS ESPELHOS SERVEM OS MESMOS BYTES — 63 201 294 para o `pt_BR-faber-medium`, caminhos idênticos,
+ * `Access-Control-Allow-Origin: *` nos dois. Medido nos dois no mesmo minuto, o que torna esta troca uma
+ * correcção de facto e não uma preferência entre fornecedores.
+ *
+ * ⚠️ A CLÁUSULA DO ADR-0114 NÃO SE MEXE: o host continua nomeado num ponto só. O que mudou foi QUAL, e a
+ * regra que decide isso passa a estar escrita para não voltar a divergir — **busca-se de onde o LEITOR lê**.
+ * No dia em que a engine for dona do runtime (ADR-0124 cláusula 2), o leitor passa a ser ela e é ela que
+ * escolhe; até lá, o único leitor é a porta do cartucho.
+ */
+export const HOST_DOS_MODELOS = 'https://huggingface.co/diffusionstudio/piper-voices/resolve/main/';
+/**
+ * O CAMINHO DO MODELO, DERIVADO DO IDENTIFICADOR — e não uma segunda tabela.
+ *
+ * `pt_BR-faber-medium` diz tudo o que o caminho precisa: `pt/pt_BR/faber/medium/pt_BR-faber-medium.onnx`.
+ * 🎯 DERIVAR EM VEZ DE TABELAR é a decisão inteira desta função: uma tabela de caminhos ao lado da tabela
+ * de vozes seria o mesmo facto escrito duas vezes, e este repositório já pagou isso três vezes — o
+ * `DomQuery`, os rótulos de movimento reduzido, as chaves de armazenamento. Duas listas divergem, e
+ * divergem uma entrada de cada vez.
+ *
+ * ⚠️ Devolve `null` para um identificador que não tenha a forma esperada, em vez de montar um caminho
+ * torto: uma URL inventada dá 404 na escola, e um `null` dá para reportar antes de sair de casa.
+ */
+export function caminhoDoModelo(v) {
+    const partes = v.voice.split('-');
+    if (partes.length !== 3)
+        return null;
+    const [locale, nome, qualidade] = partes;
+    const idioma = locale.split('_')[0];
+    if (!idioma || !nome || !qualidade || idioma === locale)
+        return null;
+    return `${idioma}/${locale}/${nome}/${qualidade}/${v.voice}.onnx`;
+}
+/** O endereço completo do modelo. `null` quando o identificador não se deixa ler. */
+export function urlDoModelo(v) {
+    const caminho = caminhoDoModelo(v);
+    return caminho === null ? null : HOST_DOS_MODELOS + caminho;
+}
+/**
+ * A CONFIGURAÇÃO da voz, que o motor lê junto com o modelo.
+ *
+ * 📌 `.onnx.json` e não um segundo caminho: é o mesmo ficheiro com outro sufixo, medido a responder 200 no
+ * mesmo sítio. Escrevê-lo como derivação mantém a regra de que o identificador é a única fonte.
+ */
+export function urlDaConfig(v) {
+    const url = urlDoModelo(v);
+    return url === null ? null : url + '.json';
+}
+export const estadoDe = (estados, v) => estados[v.voice] ?? 'ausente';
+/**
+ * A ORDEM POR QUE SE BUSCAM: primeiro as do idioma corrente, depois as outras, cada grupo na ordem do
+ * catálogo. Só entram as que ainda não estão prontas nem em curso.
+ *
+ * ⚠️ O IDIOMA CORRENTE PRIMEIRO É A REGRA INTEIRA, e ela é sobre uma criança e não sobre eficiência: as
+ * outras são para «conforme interesse do jogador», mas a dela é a que ela precisa AGORA. Buscar em ordem de
+ * catálogo faria uma criança brasileira esperar por duas vozes inglesas na rede de uma escola.
+ *
+ * 📌 `falhou` VOLTA À FILA. Uma escola perde a rede a meio da manhã e recupera-a; uma voz marcada como
+ * falhada para sempre seria uma criança sem voz até alguém recarregar a página. Quem chama decide QUANDO
+ * tentar de novo — este módulo só diz que ainda há o que buscar.
+ */
+export function ordemDeBusca(estados, localeCorrente, catalogo = VOZES_NEURAIS) {
+    const porBuscar = catalogo.filter((v) => {
+        const e = estadoDe(estados, v);
+        return e === 'ausente' || e === 'falhou';
+    });
+    return [
+        ...porBuscar.filter((v) => v.locale === localeCorrente),
+        ...porBuscar.filter((v) => v.locale !== localeCorrente),
+    ];
+}
+/**
+ * QUEM ESTÁ A FALAR, E POR QUE — e esta função é o gate 3 do ADR-0110 em forma de código.
+ *
+ * ⚠️ O DEFEITO QUE ELA IMPEDE TEM NOME NESTE REPOSITÓRIO: «um recuo que se apresenta como a coisa real é a
+ * família do `reflectTTS`». Uma engine que dissesse «voz neural» enquanto o modelo ainda desce faria um adulto
+ * concluir que a qualidade que ouve É a qualidade final — e desistir de esperar por uma coisa que já vinha a
+ * caminho. Dizer `recuo` e dizer PORQUÊ custa uma linha e é a diferença entre informar e enganar.
+ *
+ * 📌 A PRIMEIRA VOZ PRONTA DO IDIOMA, e nada mais: onde há duas prontas, esta função NÃO escolhe entre elas —
+ * devolve a primeira do catálogo porque tem de devolver alguma, e qual delas a criança prefere é a pergunta
+ * que o ADR-0110 deixou em aberto. Ver o cabeçalho.
+ */
+export function vozEmUso(estados, localeCorrente, catalogo = VOZES_NEURAIS) {
+    const doIdioma = catalogo.filter((v) => v.locale === localeCorrente);
+    if (doIdioma.length === 0)
+        return { tipo: 'recuo', porque: 'sem-voz-para-o-idioma' };
+    const pronta = doIdioma.find((v) => estadoDe(estados, v) === 'pronta');
+    if (pronta)
+        return { tipo: 'neural', voice: pronta.voice };
+    // A PRECEDÊNCIA DOS TRÊS RECUOS, e cada degrau tem a sua razão:
+    //
+    // ⚠️ «A BUSCAR» GANHA DE «FALHOU» quando as duas coexistem: enquanto alguma ainda vem a caminho, dizer
+    //    «falhou» seria anunciar uma derrota que ainda não aconteceu, e um adulto desligaria a espera cedo.
+    // ⚠️ E «AUSENTE» NÃO SE DISFARÇA DE «A BUSCAR», que era como esta função estava escrita à primeira. Nada
+    //    começou é diferente de está a caminho: o primeiro é uma engine que ainda não pediu — possivelmente
+    //    porque ninguém a mandou —, e chamar-lhe «a buscar» esconderia um buscador que nunca arrancou atrás de
+    //    uma frase tranquilizadora. É o mesmo defeito de forma que o `neuralDisponivel` já custou à #91.
+    if (doIdioma.some((v) => estadoDe(estados, v) === 'a-buscar'))
+        return { tipo: 'recuo', porque: 'a-buscar' };
+    if (doIdioma.some((v) => estadoDe(estados, v) === 'falhou'))
+        return { tipo: 'recuo', porque: 'falhou' };
+    return { tipo: 'recuo', porque: 'ausente' };
+}

package/dist-pkg/platform/vozes-prontas.d.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type EstadosDasVozes, type VozNeural } from './voice-plan.js';
+import type { RelatorioPesado } from './pesados.js';
+/**
+ * O ESTADO DE CADA VOZ A PARTIR DO QUE O BUSCADOR RELATOU.
+ *
+ * ⚠️ `emCurso` NÃO É COSMÉTICA, E É O QUE IMPEDE ESTA PONTE DE MENTIR NOS DOIS SENTIDOS. O relatório só
+ * contém o que JÁ resolveu, logo uma voz por relatar é ambígua: pode estar a caminho ou nunca ter sido
+ * pedida. O `voice-plan` recusa-se a confundir as duas por escrito — «ausente não se disfarça de a buscar»,
+ * porque isso esconderia um buscador que nunca arrancou atrás de uma frase tranquilizadora — e a única coisa
+ * que desfaz a ambiguidade é quem chamou saber se a descarga ainda corre.
+ *
+ * 📌 E o par contrário importa igualmente: com a descarga TERMINADA, uma voz por relatar é `ausente` e nunca
+ * `a-buscar`, senão a interface prometeria para sempre uma coisa que já não vem.
+ */
+export declare function estadosDasVozes(relatorio: readonly RelatorioPesado[], opcoes?: {
+    readonly emCurso?: boolean;
+}, catalogo?: readonly VozNeural[]): EstadosDasVozes;
+/**
+ * AS IDS DAS COISAS PESADAS QUE SÃO VOZ — para quem queira descê-las primeiro, sem adivinhar o formato da id.
+ *
+ * ⚠️ Existe porque a alternativa é o consumidor escrever `p.id.startsWith('voz:')` no ponto de uso, e aí o
+ * formato da id passa a ser contrato público sem nunca ter sido decidido como tal.
+ */
+export declare const idsDasVozes: (catalogo?: readonly VozNeural[]) => string[];
+/** Reexportado para quem faz a ponte não ter de importar de dois sítios para responder a uma pergunta. */
+export { vozEmUso, estadoDe } from './voice-plan.js';
+export type { VozEmUso, EstadosDasVozes } from './voice-plan.js';

package/dist-pkg/platform/vozes-prontas.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/vozes-prontas.ts — A PONTE ENTRE O QUE DESCEU E O QUE A CRIANÇA OUVE (ADR-0110, gates 3 e 4).
+//
+// ========================= POR QUE ESTE MÓDULO EXISTE =========================
+// 📏 MEDIDO EM 2026-09-09: `vozEmUso` — a função que o ADR-0110 chama «o gate 3 em forma de código» — tinha
+// ZERO leitores em produção, e NADA no repositório produzia um `EstadosDasVozes`. O buscador que nasceu hoje
+// relata `RelatorioPesado[]`. São DUAS linguagens para o mesmo facto, e nenhuma falava com a outra.
+//
+// ⚠️ ISSO NÃO É UM ENCAIXE QUE FALTAVA, É A FORMA DE DEFEITO QUE ESTE REPOSITÓRIO PERSEGUE: um modelo aferido
+// e correcto, sem ninguém a lê-lo, ao lado de um mecanismo que produz a mesma verdade noutro vocabulário. O
+// `render/viz-axes` esteve exactamente assim — «é ÓRFÃO» — e o que isso custou foi a composição dos dois eixos
+// visuais a existir no papel e não na tela.
+//
+// ========================= 🎯 A REGRA QUE ESTE MÓDULO CARREGA, E É UMA SÓ =========================
+// **UMA VOZ SÓ ESTÁ PRONTA QUANDO OS DOIS FICHEIROS DESCERAM.** O piper recusa-se a falar sem o `.onnx.json`,
+// então uma voz com o modelo e sem a configuração é uma voz que NÃO FALA — e marcá-la `pronta` faria a engine
+// anunciar «voz neural» e ficar muda. É pior do que a voz em falta, porque a primeira parece resolvida, e é
+// literalmente a família do `reflectTTS` que o ADR-0110 nomeia ao pedir o gate 3.
+import { VOZES_NEURAIS } from './voice-plan.js';
+/** As duas ids que o catálogo dá a uma voz. Derivadas, não tabeladas — a tabela vive no catálogo. */
+const idsDe = (v) => [`voz:${v.voice}`, `voz:${v.voice}:cfg`];
+/**
+ * O ESTADO DE CADA VOZ A PARTIR DO QUE O BUSCADOR RELATOU.
+ *
+ * ⚠️ `emCurso` NÃO É COSMÉTICA, E É O QUE IMPEDE ESTA PONTE DE MENTIR NOS DOIS SENTIDOS. O relatório só
+ * contém o que JÁ resolveu, logo uma voz por relatar é ambígua: pode estar a caminho ou nunca ter sido
+ * pedida. O `voice-plan` recusa-se a confundir as duas por escrito — «ausente não se disfarça de a buscar»,
+ * porque isso esconderia um buscador que nunca arrancou atrás de uma frase tranquilizadora — e a única coisa
+ * que desfaz a ambiguidade é quem chamou saber se a descarga ainda corre.
+ *
+ * 📌 E o par contrário importa igualmente: com a descarga TERMINADA, uma voz por relatar é `ausente` e nunca
+ * `a-buscar`, senão a interface prometeria para sempre uma coisa que já não vem.
+ */
+export function estadosDasVozes(relatorio, opcoes = {}, catalogo = VOZES_NEURAIS) {
+    const porId = new Map(relatorio.map((r) => [r.id, r]));
+    const saida = {};
+    for (const v of catalogo) {
+        const partes = idsDe(v).map((id) => porId.get(id));
+        if (partes.some((p) => p && (p.estado === 'falhou' || p.estado === 'sem-fonte'))) {
+            // 📌 UMA METADE FALHADA CHEGA PARA A VOZ INTEIRA FALHAR, e é o mesmo argumento da regra do cabeçalho
+            // visto do outro lado: sem os dois ficheiros não há fala nenhuma, logo não há meia voz para oferecer.
+            saida[v.voice] = 'falhou';
+            continue;
+        }
+        if (partes.every((p) => p && (p.estado === 'baixado' || p.estado === 'ja-tinha'))) {
+            saida[v.voice] = 'pronta';
+            continue;
+        }
+        saida[v.voice] = opcoes.emCurso ? 'a-buscar' : 'ausente';
+    }
+    return Object.freeze(saida);
+}
+/**
+ * AS IDS DAS COISAS PESADAS QUE SÃO VOZ — para quem queira descê-las primeiro, sem adivinhar o formato da id.
+ *
+ * ⚠️ Existe porque a alternativa é o consumidor escrever `p.id.startsWith('voz:')` no ponto de uso, e aí o
+ * formato da id passa a ser contrato público sem nunca ter sido decidido como tal.
+ */
+export const idsDasVozes = (catalogo = VOZES_NEURAIS) => catalogo.flatMap((v) => [...idsDe(v)]);
+/** Reexportado para quem faz a ponte não ter de importar de dois sítios para responder a uma pergunta. */
+export { vozEmUso, estadoDe } from './voice-plan.js';

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

@@ -65,7 +65,7 @@ interface PowerupWithSprite {
  * `sq`/`sqT` são o squash&stretch (amplitude e relógio, escritos por render/fx.setSquash); `easy` desenha a
  * hitbox de coleta tolerante translúcida; `viz` é o modo de visão, que recolore por viewport.
  */
-export type DrawPlayer = AnimPlayer & PlayerView<'i' | 'x' | 'y' | 'facing' | 'hurtTimer' | 'sq' | 'sqT' | 'easy' | 'viz' | 'sprite'>;
+export type DrawPlayer = AnimPlayer & PlayerView<'i' | 'x' | 'y' | 'facing' | 'hurtTimer' | 'sq' | 'sqT' | 'easy' | 'visual' | 'sprite'>;
 /** Flags de Movimento Reduzido que o DESENHO consulta (o objeto `rm` do game.js tem mais chaves). */
 export interface ReducedMotion {
     items?: boolean;

package/dist-pkg/render/draw.js

@@ -67,7 +67,7 @@ const rnd = rngDecoracao.rnd;
 import { JUICE, easeOut3, shakeAmp, drawFx } from './fx.js';
 import { criarCamera } from './camera.js';
 import { drawCane, drawRunCane, drawChair } from './wheelchair-sprites.js';
-import { VIZ_BY_KEY } from './viz-modes.js';
+import { chaveDeTextura, ehBaixaVisao } from './viz-axes.js';
 // (`game/powerups` e `game/coin-spawning` SAÍRAM daqui no item 19 — ver o bloco "ITENS DECLARADOS" abaixo.)
 import { drawWeather } from './weather.js';
 import { choosePlayerFrame } from './player-anim.js';
@@ -121,8 +121,11 @@ export function initDraw(ctx) {
             dt, dir, wheelchair: ctx.isWheelchair(), held: ctx.held, rnd, tex: ctx.playerTextures(),
         });
         // solo/default; no MP o drawFrame troca a textura por viewport (applySharedTextures)
+        // ⚠️ `chaveDeTextura` E NÃO A ASSINATURA DE `playerVizTex`. Medido na etapa 0 da #104: aquela função só
+        // age quando existe `DIRECT_CFG[mode]`, e devolve a textura como veio para todo o resto. Então o que
+        // muda é o CHAMADOR — a metade do estado que interessa à textura — e a porta fica onde estava.
         if (pl.sprite)
-            pl.sprite.texture = ctx.playerVizTex(tx, pl.viz);
+            pl.sprite.texture = ctx.playerVizTex(tx, chaveDeTextura(pl.visual));
         return tx;
     }
     /* ===================== o quadro ===================== */
@@ -187,12 +190,19 @@ export function initDraw(ctx) {
         }
         else {
             // Otimização: se TODOS estão no mesmo modo (caso comum), troca as texturas UMA vez; senão, por viewport.
-            const v0 = PLS[0].viz, allSame = PLS.every((p) => p.viz === v0);
-            const anyOverlay = PLS.some((p) => { const m = VIZ_BY_KEY[p.viz]; return !!m && m.kind === 'lowvision'; });
+            // ⚠️ A COMPARAÇÃO PASSOU A SER PELA CHAVE DE TEXTURA, e isso é output-preservador e mais barato ao
+            // mesmo tempo. `applySharedTextures` só usa o modo para escolher TEXTURA (`worldTexFor`,
+            // `parallaxTexFor`, `treeTexFor`, `spriteTexFor`, `pupTexFor`), e todas devolvem a base para o que não
+            // está em `DIRECT_CFG` — conferido em `high-contrast.worldTexFor`. Antes, dois jogadores em `normal` e
+            // `fix-deuter` contavam como modos DIFERENTES e disparavam uma re-aplicação de texturas que produzia
+            // exactamente as mesmas texturas. Agora contam como iguais, porque para a textura eles são.
+            const v0 = chaveDeTextura(PLS[0].visual);
+            const allSame = PLS.every((p) => chaveDeTextura(p.visual) === v0);
+            const anyOverlay = PLS.some((p) => ehBaixaVisao(p.visual));
             if (allSame)
                 ctx.applySharedTextures(v0);
             for (let i = 0, n = ctx.getNumPlayers(); i < n; i++) {
-                const viz = PLS[i].viz;
+                const viz = chaveDeTextura(PLS[i].visual);
                 if (!allSame)
                     ctx.applySharedTextures(viz); // só troca por viewport quando os modos diferem
                 const itens2 = ctx.getItemSprites();

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

@@ -80,6 +80,23 @@ export declare function proximaCorrecao(v: VisualState): VisualState;
  * 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;
+/**
+ * A CHAVE ÚNICA que melhor descreve este estado no vocabulário ANTIGO — para quem só sabe ler uma.
+ *
+ * ⚠️ NÃO É A `chaveDeTextura`, e a diferença custou um gate vermelho para aparecer. A de textura devolve
+ * `normal` para uma correção de cor, porque correção não muda textura nenhuma — e usá-la como espelho faria
+ * uma criança em `fix-deuter` passar a gravar `'normal'` na chave legada. **Um leitor antigo perderia a
+ * correção dela**, que é exactamente o estrago que a migração inteira existe para não cometer.
+ *
+ * A ordem é simulação → tema → correção → padrão, e ela preserva TODO ajuste que já existia: nenhum estado
+ * antigo tinha dois eixos, então nenhum deles perde nada aqui.
+ *
+ * ⚠️ O ÚNICO CASO COM PERDA É O NOVO — `hc7 + fix-deuter` só cabe como uma das duas metades, e a escolhida é
+ * o tema. Não há regressão possível nisso: esse estado NÃO EXISTIA antes, e um leitor que só entende uma
+ * chave nunca soube exprimi-lo. Quem quiser as duas metades lê a chave nova, que existe precisamente para
+ * isso.
+ */
+export declare function chaveLegada(v: VisualState): string;
 /**
  * Traduz o valor salvo. Aceita o antigo (string) e o novo (objeto), e devolve sempre um estado válido.
  *

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

@@ -122,6 +122,25 @@ export function proximaCorrecao(v) {
 export function chaveDeTextura(v) {
     return v.simulacao ?? temaDireto(v) ?? 'normal';
 }
+/**
+ * A CHAVE ÚNICA que melhor descreve este estado no vocabulário ANTIGO — para quem só sabe ler uma.
+ *
+ * ⚠️ NÃO É A `chaveDeTextura`, e a diferença custou um gate vermelho para aparecer. A de textura devolve
+ * `normal` para uma correção de cor, porque correção não muda textura nenhuma — e usá-la como espelho faria
+ * uma criança em `fix-deuter` passar a gravar `'normal'` na chave legada. **Um leitor antigo perderia a
+ * correção dela**, que é exactamente o estrago que a migração inteira existe para não cometer.
+ *
+ * A ordem é simulação → tema → correção → padrão, e ela preserva TODO ajuste que já existia: nenhum estado
+ * antigo tinha dois eixos, então nenhum deles perde nada aqui.
+ *
+ * ⚠️ O ÚNICO CASO COM PERDA É O NOVO — `hc7 + fix-deuter` só cabe como uma das duas metades, e a escolhida é
+ * o tema. Não há regressão possível nisso: esse estado NÃO EXISTIA antes, e um leitor que só entende uma
+ * chave nunca soube exprimi-lo. Quem quiser as duas metades lê a chave nova, que existe precisamente para
+ * isso.
+ */
+export function chaveLegada(v) {
+    return v.simulacao ?? temaDireto(v) ?? filtroChave(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

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

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { type VizMode } from './viz-modes.js';
+import { type Tema, type Correcao, type VisualState } from './viz-axes.js';
 import type { DomQuery } from '../core/dom-query.js';
 import type { ComFiltro, ComTextura, Visivel, DesenhoComCirculo, AplicarFiltroCss, AlcanceDoFiltro, AplicarAltoContrasteNoDom } from './port.js';
 /**
@@ -10,6 +11,24 @@ import type { ComFiltro, ComTextura, Visivel, DesenhoComCirculo, AplicarFiltroCs
 export declare function alcanceDoModo(mode: string): AlcanceDoFiltro;
 /** Modo por chave, com o fallback do original: chave desconhecida (ou nula) CAI em `normal`. */
 export declare function resolveViz(key: string | null | undefined): VizMode;
+/**
+ * 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 declare function lerVisualGuardado(i: number): VisualState;
 /** É um dos três níveis de Renderização Direta (alto contraste)? Mesmo teste do original: `!!DIRECT_CFG[mode]`. */
 export declare function isDirectMode(mode: string): boolean;
 /** Filtro CSS da canvas no SOLO: simulação/correção de visão + realce L→Q, compostos e sem vazios. */
@@ -44,6 +63,7 @@ interface ClassListHost {
 }
 interface Pl {
     viz: string;
+    visual?: VisualState;
     sprite?: Textured | null;
     _tx?: unknown;
 }
@@ -100,7 +120,7 @@ export interface VizSettersCtx {
     setFrontDim: (on: boolean) => void;
     rebuildExtras: () => void;
     rebuildCoins: () => void;
-    setModoCego: (on: boolean) => void;
+    setModoCego?: (on: boolean) => void;
     hideTouchControls: (reason?: string) => void;
     reflectVizButtons: () => void;
     renderVisualPanel: () => void;
@@ -115,8 +135,18 @@ export interface VizSettersApi {
     applyVpFilters(): void;
     /** Troca o modo de UM jogador: persiste, invalida o render estático e reaplica pelo caminho certo. */
     setPlayerViz(i: number, mode: string): void;
+    /**
+     * O ESTADO INTEIRO de um jogador, e os DOIS escritores por eixo (#104).
+     *
+     * ⚠️ Os dois de eixo existem separados porque é isso que um painel de dois controles precisa: mexer no
+     * TEMA sem tocar na correção, e vice-versa. Enquanto havia um campo só, «mexer num» significava
+     * inevitavelmente «apagar o outro» — e era o defeito, não a API.
+     */
+    setVisualDoJogador(i: number, v: VisualState): void;
+    setTemaDoJogador(i: number, tema: Tema): void;
+    setCorrecaoDoJogador(i: number, correcao: Correcao): void;
     /** Caminho SOLO: filtro CSS na canvas + texturas globais + overlay DOM + bolinha. */
-    applyVizGlobal(mode: string): void;
+    applyVizGlobal(v: VisualState): void;
     /** Reaplica tudo depois de uma mudança estrutural (cenário, nº de telas). */
     reapplyVizAll(): void;
     /** Bolinha global (#viz-indicator) para um `kind`. */
@@ -125,6 +155,8 @@ export interface VizSettersApi {
     rebakeDirect(): void;
     /** Grupo de rádios de modos visuais nos painéis (visual/empatia). */
     renderVizGroup(listSel: string, tabsSel: string, modes: readonly VizMode[]): void;
+    /** Os DOIS eixos do painel visual (#104). Irmão do de cima — ver a nota na implementação. */
+    renderEixosVisuais(listSel: string, tabsSel: string): void;
 }
 export declare function initVizSetters(ctx: VizSettersCtx): VizSettersApi;
 export {};