@the-inclusionist/engine 7.0.0 → 8.0.0-rc.1

package/dist-pkg/platform/storage.js

@@ -123,6 +123,12 @@ export const KEYS = {
     ttsEngine: 'incl_tts_engine', ttsVoice: 'incl_tts_voice', lang: 'incl_lang', // audiocat_{k}
     // comunicação / legendas (ADR-0028: todo menu persiste)
     letterCase: 'incl_lettercase', captions: 'incl_captions',
+    // ⚠️ O NÍVEL TEA (calmo / silencioso) PASSOU A PERSISTIR EM 2026-09-07, e antes não persistia: era um
+    // `let calmMode = 0` em `ui/pause-icons`, com o comentário «deliberately NOT persisted — verbatim: game.js
+    // never wrote it to storage». O «verbatim» é a chave — foi PRESERVADO na extração do monólito, não
+    // decidido. O custo era da criança que mais precisa dele: quem usa o modo silencioso voltava a pô-lo a
+    // cada sessão, e é para quem o barulho inesperado custa mais. O ADR-0028 diz que todo menu persiste.
+    tea: 'incl_tea',
     menuIndex: 'incl_menuindex', // "6 de 10" no fim do anuncio de item (ADR-0044, item 3)
     // tipografia / controles / toque
     fontKey: 'incl_font_k', padDesign: 'incl_paddesign', padDir: 'incl_paddir', touchmap: 'incl_touchmap',
@@ -133,9 +139,38 @@ export const KEYS = {
     reducedMotion: 'inclusionist.reducedmotion.v1', toggleMoveLegacy: 'inclusionist.togglemove',
     // POR JOGADOR — parametrizadas pelo indice da tela. Eram sufixos '_p'+i montados a mao em varios
     // pontos do game.js; virar funcao aqui e o que impede que um deles escreva num nome torto.
+    /**
+     * @deprecated ⚠️ A CHAVE LEGADA do modo visual — UM valor, do tempo em que só cabia um (issue #104).
+     *
+     * Continua a ser LIDA, e é isso que impede a criança de perder o que já escolheu; continua a ser ESCRITA
+     * enquanto os controles ainda escreverem um valor de cada vez, porque um leitor antigo (o cartucho na
+     * versão publicada) faz `if (v && VIZ_BY_KEY[v])` e rejeitaria um JSON — escrever a forma nova AQUI
+     * apagaria o ajuste dela em silêncio, que é exactamente o defeito que a migração existe para não cometer.
+     */
     vizP: (i) => 'incl_viz_p' + i,
+    /**
+     * O ESTADO VISUAL de dois eixos, em JSON (ADR-0076, issue #104).
+     *
+     * ⚠️ CHAVE NOVA AO LADO DA VELHA, e não a mesma chave com conteúdo novo. É o mesmo desenho que o campo
+     * `visual` usa ao lado do `viz`: as duas formas coexistem enquanto houver leitores das duas, cada um lê a
+     * que entende, e a velha só morre quando não sobrar quem a leia. `migrarVisual` aceita as duas, então o
+     * recuo — chave nova ausente, chave velha presente — devolve exactamente o que a criança escolheu.
+     */
+    visualP: (i) => 'incl_visual_p' + i,
     sinkP: (i) => 'incl_sink_p' + i,
     easyP: (i) => 'incl_easy_p' + i,
+    /**
+     * ⚠️ AS DUAS DE BAIXO SÃO AS CHAVES LEGADAS desde 2026-09-08 (ADR-0104 §C, issue #114). Continuam a ser
+     * LIDAS — é o ajuste da criança, e a herança dele é o que a impede de o perder — e não voltam a ser
+     * escritas. O que se escreve é a chave COM TRANSPORTE, porque a alternância é do APARELHO e não da pessoa:
+     * ligá-la no controle de tela, onde ninguém segura um botão virtual com conforto, ligava-a também no
+     * teclado, onde segurar uma tecla é exactamente o que a criança sabe fazer.
+     *
+     * ⚠️ E A CHAVE NOVA NÃO MORA AQUI, de propósito. Ela é `chaveDaAlternancia`, em `input/latch-scope` — este
+     * ficheiro é módulo-FOLHA e `platform/` não importa de `input/`, que é a camada acima. Montá-la aqui
+     * exigiria ou uma aresta ao contrário ou uma segunda cópia do nome, e a segunda cópia é exactamente o que
+     * o comentário do bloco acima existe para impedir. O dono do nome é quem conhece a regra do transporte.
+     */
     toggleMoveP: (i) => 'incl_togglemove_p' + i,
     toggleRunP: (i) => 'incl_togglerun_p' + i, // alternância do botão de CORRER (irmã da de movimento)
     rmWalkP: (i) => 'incl_rmWalk_p' + i,

package/dist-pkg/platform/tts.js

@@ -10,7 +10,22 @@ import { t, bcp47 } from '../core/i18n.js';
 import { criarFalaInterrompivel } from './interruptible-speech.js';
 // ⚠️ MIGRAÇÃO PENDENTE (ADR-0022): a implementação neural de hoje é o @mintplex-labs/piper-tts-web e será SUBSTITUÍDA
 // por sherpa-onnx-wasm (loader universal, modelos VITS/Piper + Kokoro-multi-lang carregados de qq URL R2 em runtime via
-// FS.writeFile; lazy-fetch; eSpeak/Web Speech de fallback). @mintplex-labs foi descontinuado e só carrega 2 vozes pt-BR.
+// FS.writeFile; lazy-fetch; eSpeak/Web Speech de fallback).
+// 🔴 O MOTIVO ESCRITO AQUI ERA «@mintplex-labs foi descontinuado e só carrega 2 vozes pt-BR», E AS DUAS METADES
+// FORAM MEDIDAS FALSAS EM 2026-09-09 — não pela leitura de um registo, que é como elas se propagaram por seis
+// sítios, mas pelo registo npm e pelo pacote instalado:
+//   · DESCONTINUADO: nenhuma versão tem campo `deprecated`, e a 1.0.5 foi publicada em 2026-08-11 — depois de
+//     o ADR-0022 (2026-07-06) a dar por morta. A frase é de Julho e está atribuída ao Dev; o registo não a nega
+//     no passado, nega-a HOJE.
+//   · DUAS VOZES pt-BR: o `VoiceId` da 1.0.4 instalada traz 118 vozes, e entre elas as QUATRO exactas do
+//     ADR-0110 — `pt_BR-faber-medium`, `en_US-ryan-medium`, `en_US-amy-medium`, `es_MX-claude-high`.
+// ⚠️ O QUE CONTINUA VERDADEIRO, e é mais afiado do que o motivo velho: o bundle prende `HF_BASE` a
+// `huggingface.co/diffusionstudio/piper-voices` COM UMA GUARDA (`if (!url.match("https://huggingface.co")) return`),
+// logo nenhum espelho de escola é alcançável por ele; e ele busca o PRÓPRIO runtime de cdnjs/jsDelivr por
+// omissão, que é o que o ADR-0114 retira. A montante, o Piper mudou para `OHF-Voice/piper1-gpl` e a Open Home
+// Foundation procura mantenedores — o risco existe, mas está noutro sítio.
+// 📌 A ESCOLHA CONTINUA A SER A #129, e este comentário não a toma: descreve o que foi medido para que o
+// próximo leitor não herde o motivo velho como se fosse medição.
 // ⚠️ E DESDE O ADR-0094 ESTE MÓDULO NÃO NOMEIA FORNECEDOR NENHUM — quem o nomeia é o JOGO, por `ctx.carregarVozNeural`.
 // O nome estava aqui num `import()` e o pacote em `devDependencies`, o que publicou uma engine que não compilava
 // (ADR-0093); pô-lo em `dependencies` consertava o build e obrigava todo consumidor a 135,4 MB de `onnxruntime-web`,

package/dist-pkg/platform/voice-plan.d.ts

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Uma voz do catálogo. `voice` é o identificador no fornecedor; `engine` é o motor que a lê. */
+export interface VozNeural {
+    readonly locale: string;
+    readonly engine: string;
+    readonly voice: string;
+}
+/**
+ * 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 declare const VOZES_NEURAIS: readonly VozNeural[];
+/**
+ * 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.
+ */
+export declare const HOST_DOS_MODELOS = "https://huggingface.co/rhasspy/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 declare function caminhoDoModelo(v: VozNeural): string | null;
+/** O endereço completo do modelo. `null` quando o identificador não se deixa ler. */
+export declare function urlDoModelo(v: VozNeural): string | null;
+/**
+ * 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 declare function urlDaConfig(v: VozNeural): string | null;
+/** Em que pé está cada voz. `falhou` é um estado e não uma excepção — ver `vozEmUso`. */
+export type EstadoDaVoz = 'ausente' | 'a-buscar' | 'pronta' | 'falhou';
+/** O que se sabe de cada voz, por identificador. Uma voz ausente do mapa é `ausente`. */
+export type EstadosDasVozes = Readonly<Record<string, EstadoDaVoz | undefined>>;
+export declare const estadoDe: (estados: EstadosDasVozes, v: VozNeural) => EstadoDaVoz;
+/**
+ * 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 declare function ordemDeBusca(estados: EstadosDasVozes, localeCorrente: string, catalogo?: readonly VozNeural[]): VozNeural[];
+/** O que a criança ouve agora. `recuo` é a voz do sistema — eSpeak ou Web Speech. */
+export type VozEmUso = {
+    readonly tipo: 'neural';
+    readonly voice: string;
+} | {
+    readonly tipo: 'recuo';
+    readonly porque: 'a-buscar' | 'sem-voz-para-o-idioma' | 'falhou' | 'ausente';
+};
+/**
+ * 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 declare function vozEmUso(estados: EstadosDasVozes, localeCorrente: string, catalogo?: readonly VozNeural[]): VozEmUso;

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

@@ -0,0 +1,137 @@
+// 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.
+ */
+export const HOST_DOS_MODELOS = 'https://huggingface.co/rhasspy/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/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 {};