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

package/dist-pkg/platform/pesados-catalogo.js

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/pesados-catalogo.ts — O QUE É PESADO, DE ONDE VEM, E QUANTO PESA.
+//
+// 📌 SEPARADO DO BUSCADOR de propósito: a lista é DADO e muda por decisão registada; o buscador é regra e
+// muda por defeito encontrado. Juntos, cada correcção de uma URL mexeria no ficheiro que decide a ordem das
+// descargas, e cada correcção da ordem mexeria na lista que um registo governa.
+//
+// ========================= 🔴 A PRIMEIRA VERSÃO DESTE FICHEIRO COMETEU O DEFEITO QUE ELE SERVE =========================
+// Ela escrevia o host à mão (`const HF = 'https://huggingface.co/…'`), a lista das quatro vozes outra vez, e
+// uma segunda derivação do caminho `idioma/locale/nome/qualidade/…`. As três coisas JÁ EXISTEM no
+// `platform/voice-plan.ts`, que o ADR-0114 designou como o sítio ÚNICO onde o host é nomeado — e cujo próprio
+// comentário nomeia as três vezes que este repositório pagou por tabelas duplicadas (o `DomQuery`, os rótulos
+// de movimento reduzido, as chaves de armazenamento).
+//
+// 📏 QUEM APANHOU FOI O INVENTÁRIO, e não pela duplicação: o `nada-vem-de-fora` recusou uma URL nova sem razão
+// escrita. A URL era só a PROVA; declará-la teria feito o gate ficar verde com a duplicação lá dentro. ⚠️ É a
+// razão de a saída ser APAGAR a cópia e não desculpá-la — declarar duas vezes o mesmo endereço é precisamente
+// a cláusula que o `nada-de-cdn-a-mao` conta com um número.
+import { VOZES_NEURAIS, urlDoModelo, urlDaConfig } from './voice-plan.js';
+/** O nome da Cache Storage. Versionado: mudar o conteúdo do catálogo não deve servir bytes velhos. */
+export const CACHE_PESADOS = 'incl-pesados-v1';
+/**
+ * O PESO DE CADA VOZ, MEDIDO EM 2026-09-09 e não estimado — `Content-Length` do modelo e corpo da configuração.
+ *
+ * 📌 O PESO MORA AQUI E O ENDEREÇO MORA NO `voice-plan`, e a divisão não é arrumação: o `voice-plan` responde
+ * «que vozes a engine garante e onde estão», que é decisão do ADR-0110; isto responde «quanto custa descê-las
+ * hoje», que é uma medição com data e que muda quando o fornecedor recomprime um ficheiro.
+ *
+ * ⚠️ UMA VOZ NOVA NO `voice-plan` SEM MEDIÇÃO AQUI FICA SEM `bytes`, e o aviso de «faltam N MB» passaria a
+ * sub-reportar em silêncio. É por isso que o gate exige `bytes > 0` em toda entrada de voz COM url: o buraco
+ * é pequeno e mudo, que é a forma de defeito que este repositório persegue.
+ */
+const PESO_MEDIDO = Object.freeze({
+    'pt_BR-faber-medium': { modelo: 63_201_294, config: 4_855 },
+    'en_US-ryan-medium': { modelo: 63_201_294, config: 4_883 },
+    'en_US-amy-medium': { modelo: 63_201_294, config: 4_882 },
+    'es_MX-claude-high': { modelo: 63_122_309, config: 4_963 },
+});
+/**
+ * ⚠️ O `urlDoModelo` devolve `null` para um identificador que não se deixe ler, e a razão viaja com a entrada
+ * em vez de a entrada desaparecer. Uma URL inventada dá 404 na escola; um `null` COM razão dá para reportar
+ * antes de sair de casa, que é a regra que o `voice-plan` já escreve na própria função.
+ */
+const RAZAO_ID_TORTO = 'o identificador da voz não tem a forma `locale-nome-qualidade`, então o caminho no '
+    + 'fornecedor não se deixa derivar. Corrija o identificador no `platform/voice-plan.ts`.';
+/**
+ * AS DUAS ENTRADAS DE UMA VOZ. ⚠️ SÃO DUAS E NÃO UMA: o `.onnx` é o modelo e o `.onnx.json` é a configuração,
+ * e o piper recusa-se a falar sem a segunda. Um catálogo que só trouxesse a primeira produziria uma voz
+ * «baixada» que não fala — que é pior do que uma voz em falta, porque a primeira parece resolvida.
+ */
+function entradasDaVoz(v) {
+    const peso = PESO_MEDIDO[v.voice];
+    return [
+        { id: `voz:${v.voice}`, url: urlDoModelo(v), bytes: peso?.modelo, porQueNaoTemFonte: RAZAO_ID_TORTO },
+        { id: `voz:${v.voice}:cfg`, url: urlDaConfig(v), bytes: peso?.config, porQueNaoTemFonte: RAZAO_ID_TORTO },
+    ];
+}
+/**
+ * O RUNTIME DE VISÃO — **MediaPipe**, decidido pelo Dev em 2026-09-09 (ADR-0124): «piper-tts, mediapipe
+ * (webgazer não), e LPCP: devem acompanhar a engine».
+ *
+ * 🔴 ESTA ENTRADA DIZIA «a #129 ainda não escolheu o fornecedor» DEPOIS DE ELE TER ESCOLHIDO, e a linha
+ * sobreviveu ao registo que a contradizia. Não era só trabalho em falta: era uma afirmação FALSA a dirigir
+ * quem a lesse para uma issue já fechada. O Dev teve de perguntar três vezes.
+ *
+ * 📏 MEDIDO EM 2026-09-09, como as vozes e no mesmo minuto: os três ficheiros respondem 200 em jsDelivr com
+ * `Access-Control-Allow-Origin: *`, na versão FIXADA — 155 439 + 323 377 + 11 756 954 bytes.
+ *
+ * ⚠️ CDN FIXADA É PERMITIDA E O ADR-0116 DIZ PORQUÊ: o que o pilar 8 proíbe é depender da rede DEPOIS do
+ * primeiro dia. Isto desce na INSTALAÇÃO, com o resto — e é a diferença inteira para o WebGazer, que busca
+ * quando a criança liga o controle por olhar, logo a máquina que nunca o ligou fica sem ele para sempre.
+ * 📌 A versão vai na URL, que é o que o `check:precache` exige de qualquer entrada externa: bytes diferentes
+ * chegam por endereço diferente, e uma entrada fixada nunca congela.
+ *
+ * 🎯 SÃO OS TRÊS FICHEIROS E NÃO SÓ O `.wasm`: o `vision_bundle.mjs` é quem o carrega e o
+ * `vision_wasm_internal.js` é a cola do Emscripten. Baixar o wasm sozinho é a mesma armadilha do `.onnx` sem
+ * o `.onnx.json` — uma coisa «baixada» que não corre.
+ *
+ * ⬜ O que continua por fazer é a FIAÇÃO (issue #11): estes bytes descem e ainda ninguém os lê. O
+ * `tests/o-que-desce-tem-quem-leia.node.test.js` é onde essa dívida está declarada.
+ */
+const MP = 'https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@1.0.1';
+const MP_MODELOS = 'https://storage.googleapis.com/mediapipe-models';
+/**
+ * 🔴 A PRIMEIRA VERSÃO DESTA LISTA TRAZIA O RUNTIME E NENHUM MODELO, e o Dev apanhou-o ao perguntar o que
+ * tinha ficado de fora. 11,7 MB de WebAssembly sem um `.task` não reconhecem coisa nenhuma — é o `.onnx` sem
+ * o `.onnx.json` outra vez, no ficheiro que escreve essa lição doze linhas acima.
+ *
+ * 📏 MEDIDOS EM 2026-09-09, todos 200 com CORS aberto. `float16` e não `float32`: metade do peso, e a precisão
+ * que se perde é irrelevante para dizer onde está um íris num ecrã de 320×180.
+ */
+const MEDIAPIPE = Object.freeze([
+    { id: 'visao:runtime', url: `${MP}/vision_bundle.mjs`, bytes: 155_439 },
+    { id: 'visao:runtime:cola', url: `${MP}/wasm/vision_wasm_internal.js`, bytes: 323_377 },
+    { id: 'visao:runtime:wasm', url: `${MP}/wasm/vision_wasm_internal.wasm`, bytes: 11_756_954 },
+    { id: 'visao:modelo:rosto', url: `${MP_MODELOS}/face_landmarker/face_landmarker/float16/1/face_landmarker.task`, bytes: 3_758_596 },
+    { id: 'visao:modelo:gestos', url: `${MP_MODELOS}/gesture_recognizer/gesture_recognizer/float16/1/gesture_recognizer.task`, bytes: 8_373_440 },
+    { id: 'visao:modelo:maos', url: `${MP_MODELOS}/hand_landmarker/hand_landmarker/float16/1/hand_landmarker.task`, bytes: 7_819_105 },
+]);
+/**
+ * O WEBGAZER — **volta em 2026-09-09, ao lado do MediaPipe** (ADR-0132): «Traga o WebGazer de volta. Vamos
+ * usar ambos.»
+ *
+ * 🎯 ELES NÃO SE SOBREPÕEM ONDE IMPORTA, e é essa medição que produziu a decisão: o MediaPipe diz ONDE O ÍRIS
+ * ESTÁ — `FACE_LANDMARKS_LEFT_IRIS` são conjuntos de conexões sobre marcos —, e o WebGazer diz PARA ONDE A
+ * CRIANÇA OLHA NO ECRÃ, que é um modelo de regressão com calibração. Nenhuma das quinze tarefas do
+ * `tasks-vision` faz a segunda.
+ *
+ * ⚠️ E O DEFEITO DELE NUNCA FOI O FORNECEDOR: era ser PREGUIÇOSO. Buscado quando a criança liga o controle
+ * por olhar, a máquina que nunca o ligou fica sem ele, e numa escola sem rede não acontece nada — sem erro e
+ * sem explicação. Aqui desce na INSTALAÇÃO com tudo o resto, e o defeito desaparece com a capacidade intacta.
+ * 📌 Fica a dívida que o ADR-0132 nomeia: o `<script src>` do `ui/webcam.ts` tem de sair no mesmo commit em
+ * que a fiação o ler daqui, senão passam a existir dois caminhos para o mesmo ficheiro.
+ */
+const WEBGAZER = Object.freeze([
+    { id: 'visao:olhar', url: 'https://webgazer.cs.brown.edu/webgazer.js', bytes: 1_895_169 },
+]);
+/**
+ * O RUNTIME DE VOZ — **piper**, decidido no ADR-0127, e o Dev disse para que serve: «PiperTTS é o que será
+ * usado para ler para o usuário. Precisa ser carregado com a engine».
+ *
+ * 🔴 ATÉ AQUI ELE SÓ CHEGAVA PELA PORTA DO CARTUCHO (ADR-0094), e três dos seis jogos não a declaram — nesses,
+ * a engine descarregava 241 MB de modelos e não tinha com que os tocar. Descer os modelos sem o motor é a
+ * mesma armadilha do `.onnx` sem o `.onnx.json`, um nível acima.
+ *
+ * 📏 MEDIDO EM 2026-09-09 em jsDelivr, versões FIXADAS, todos 200 com `Access-Control-Allow-Origin: *`.
+ * ⚠️ SÃO CINCO FICHEIROS E NÃO UM: o `piper-tts-web.js` é só a entrada (23 KB) — os dois pedaços com hash no
+ * nome são o corpo e a tabela de vozes, e o `onnxruntime-web` é quem corre o modelo. Trazer só a entrada dá
+ * um módulo que importa o que não está lá.
+ * 📌 `ort-wasm-simd-threaded` e não o `jsep`: o jsep é o caminho WebGPU e pesa 21,7 MB contra 11,2 — e o
+ * hardware do pilar 1 não é onde a WebGPU se ganha.
+ */
+const PP = 'https://cdn.jsdelivr.net/npm/@mintplex-labs/piper-tts-web@1.0.5/dist';
+const ORT = 'https://cdn.jsdelivr.net/npm/onnxruntime-web@1.20.1/dist';
+const PIPER = Object.freeze([
+    { id: 'voz:runtime', url: `${PP}/piper-tts-web.js`, bytes: 23_646 },
+    { id: 'voz:runtime:corpo', url: `${PP}/piper-o91UDS6e.js`, bytes: 158_217 },
+    { id: 'voz:runtime:tabela', url: `${PP}/voices_static-D_OtJDHM.js`, bytes: 147_377 },
+    { id: 'voz:runtime:ort', url: `${ORT}/ort.min.js`, bytes: 446_284 },
+    { id: 'voz:runtime:ort-wasm', url: `${ORT}/ort-wasm-simd-threaded.wasm`, bytes: 11_246_032 },
+]);
+export const PESADOS = Object.freeze([
+    ...VOZES_NEURAIS.flatMap(entradasDaVoz),
+    ...PIPER,
+    /*
+     * 🔴 O RUNTIME DE VISÃO — decidido e SEM FONTE, e a ausência é medida.
+     *
+     * A issue #11 diz «MediaPipe» e o `ui/webcam.ts` faz WebGazer, buscado de `webgazer.cs.brown.edu` por um
+     * `<script src>` com preguiça no PRIMEIRO USO — sem SRI, sem `crossorigin`, e a falhar em silêncio numa
+     * escola sem rede. `git grep -i mediapipe` em `app/js` devolve ZERO (ADR-0119).
+     *
+     * ⚠️ NÃO PONHO AQUI A URL DO WEBGAZER. Trocar o fornecedor é decisão da #129, e escrevê-la aqui seria
+     * decidi-la de lado — a mesma coisa que o ADR-0119 apanhou: um subsistema que a engine DECLARA possuir e
+     * que na prática é outra coisa.
+     */
+    ...MEDIAPIPE,
+    ...WEBGAZER,
+    /*
+     * 🔴 O ACERVO DE ARTE — a quarta coisa pesada do ADR-0119, e a única SEM FONTE. Medido: `art/` tem DOIS
+     * ficheiros — um README e um `ATTRIBUTION.csv` de 40 bytes, só o cabeçalho. Zero arte.
+     *
+     * ⚠️ ATÉ 2026-09-09 ESTA LINHA CULPAVA A COISA ERRADA. Dizia que a quarentena estava vazia e que a arte
+     * era CC BY-SA 3.0 com autoria por recurso — descrevendo o Liberated Pixel Cup, que o ADR-0133 recusou:
+     * os dois braços dele são share-alike ou GPL, e nenhum está na lista fechada de quatro licenças.
+     *
+     * 📌 A razão de continuar sem fonte MUDOU e é mais simples: não há acervo escolhido. A arte entra sob
+     * CC0, CC BY 3.0, CC BY 4.0 ou OGA-BY, com uma linha de livro por recurso e a URL da origem — e nada
+     * disso é uma URL única que um buscador possa pedir. A fonte desta linha é o dia em que houver acervo.
+     */
+    {
+        id: 'arte:acervo',
+        url: null,
+        porQueNaoTemFonte: 'não há acervo escolhido: `art/` tem só README e cabeçalho do CSV. O ADR-0133 fechou '
+            + 'a lista em CC0, CC BY 3.0/4.0 e OGA-BY, e a arte entra recurso a recurso com autoria e URL de '
+            + 'origem — não por uma URL solta que este buscador possa pedir.',
+    },
+]);

package/dist-pkg/platform/pesados.d.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { CACHE_PESADOS, PESADOS, type Pesado } from './pesados-catalogo.js';
+export { CACHE_PESADOS, PESADOS };
+export type { Pesado };
+/** O que aconteceu com cada entrada, para quem chama poder dizê-lo a uma pessoa. */
+export interface RelatorioPesado {
+    readonly id: string;
+    readonly estado: 'ja-tinha' | 'baixado' | 'falhou' | 'sem-fonte';
+    readonly bytes?: number;
+    readonly erro?: string;
+}
+export interface OpcoesDosPesados {
+    /** `caches` do navegador. Injectado para o gate não precisar de um. */
+    readonly cacheStorage?: CacheStorage;
+    /** `fetch`. Injectado pela mesma razão. */
+    readonly buscar?: typeof fetch;
+    /** Chamado a cada entrada resolvida — é o que deixa a interface dizer o que está a acontecer. */
+    readonly aoProgredir?: (r: RelatorioPesado) => void;
+    /** Só estas ids, se dado. Serve ao consumidor que quer as vozes e não o resto. */
+    readonly apenas?: readonly string[];
+}
+/**
+ * BAIXA O QUE FALTA, UM DE CADA VEZ, E DEVOLVE O QUE ACONTECEU COM CADA UM.
+ *
+ * ⚠️ AS ENTRADAS SEM `url` NÃO SÃO SALTADAS EM SILÊNCIO — devolvem `sem-fonte`. É a diferença entre «este
+ * subsistema ainda não tem de onde vir» e «este subsistema está tratado», e é exactamente a distinção que o
+ * ADR-0119 mediu em falta: a engine PROMETIA quatro coisas e entregava uma, sem nada a dizê-lo.
+ */
+export declare function baixarPesados(opcoes?: OpcoesDosPesados): Promise<RelatorioPesado[]>;
+/** O peso do que ainda falta, em bytes — para um aviso poder dizer «faltam 241 MB» antes de começar. */
+export declare function pesoPorBaixar(relatorio: readonly RelatorioPesado[]): number;

package/dist-pkg/platform/pesados.js

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/pesados.ts — AS COISAS PESADAS, BAIXADAS NO PRIMEIRO CARREGAMENTO (ADR-0110, ADR-0116, ADR-0119).
+//
+// ========================= O QUE ISTO É =========================
+// O pilar 8 diz «PWA no primeiro dia ONLINE, depois OFFLINE-FIRST», e o ADR-0116 tirou a contradição que
+// travava isto: instalar já é um acto de rede, logo buscar na instalação não viola nada. O que faltava era
+// alguém a buscar.
+//
+// 📏 MEDIDO EM 2026-09-09, e é o estado que este ficheiro existe para mudar: das quatro coisas pesadas que a
+// engine promete (fontes · voz neural · runtime de visão · arte do LCP), só as FONTES viajavam de verdade.
+// As vozes eram porta do cartucho, o runtime de visão era um `<script src>` de CDN buscado com preguiça no
+// PRIMEIRO USO, e a arte do LCP não existe.
+//
+// ⚠️ E ISTO NÃO BLOQUEIA O JOGO. A criança joga enquanto os 241 MB descem; o que não pode acontecer é ela
+// chegar ao segundo dia, sem rede, e descobrir que a voz nunca foi buscada.
+//
+// ========================= AS TRÊS REGRAS QUE A FORMA IMPÕE =========================
+//  1. **UM DE CADA VEZ.** Quatro descargas de 60 MB em paralelo num link de escola disputam a mesma banda e
+//     nenhuma acaba primeiro — e o jogo, que precisa da rede para as próprias imagens, fica atrás delas.
+//  2. **NUNCA LANÇA.** Uma falha de rede é REPORTADA e a lista continua. Um `throw` aqui derrubaria o
+//     arranque de um jogo por causa de um recurso que ele nem usa hoje.
+//  3. **IDEMPOTENTE.** O que já está na Cache Storage não é buscado outra vez — é o que torna isto seguro de
+//     chamar em todo arranque em vez de só «no primeiro», que ninguém sabe detectar com honestidade.
+import { CACHE_PESADOS, PESADOS } from './pesados-catalogo.js';
+export { CACHE_PESADOS, PESADOS };
+/**
+ * BAIXA O QUE FALTA, UM DE CADA VEZ, E DEVOLVE O QUE ACONTECEU COM CADA UM.
+ *
+ * ⚠️ AS ENTRADAS SEM `url` NÃO SÃO SALTADAS EM SILÊNCIO — devolvem `sem-fonte`. É a diferença entre «este
+ * subsistema ainda não tem de onde vir» e «este subsistema está tratado», e é exactamente a distinção que o
+ * ADR-0119 mediu em falta: a engine PROMETIA quatro coisas e entregava uma, sem nada a dizê-lo.
+ */
+export async function baixarPesados(opcoes = {}) {
+    const cs = opcoes.cacheStorage ?? (typeof caches !== 'undefined' ? caches : undefined);
+    const buscar = opcoes.buscar ?? (typeof fetch !== 'undefined' ? fetch : undefined);
+    const alvos = opcoes.apenas
+        ? PESADOS.filter((p) => opcoes.apenas.includes(p.id))
+        : PESADOS;
+    const out = [];
+    const conta = (r) => { out.push(r); opcoes.aoProgredir?.(r); };
+    if (!cs || !buscar) {
+        for (const p of alvos)
+            conta({ id: p.id, estado: 'falhou', erro: 'sem Cache Storage ou sem fetch' });
+        return out;
+    }
+    const cache = await cs.open(CACHE_PESADOS);
+    for (const p of alvos) {
+        if (!p.url) {
+            conta({ id: p.id, estado: 'sem-fonte', erro: p.porQueNaoTemFonte });
+            continue;
+        }
+        try {
+            if (await cache.match(p.url)) {
+                conta({ id: p.id, estado: 'ja-tinha' });
+                continue;
+            }
+            const resp = await buscar(p.url);
+            if (!resp.ok) {
+                conta({ id: p.id, estado: 'falhou', erro: `HTTP ${resp.status}` });
+                continue;
+            }
+            await cache.put(p.url, resp.clone());
+            conta({ id: p.id, estado: 'baixado', bytes: p.bytes });
+        }
+        catch (e) {
+            conta({ id: p.id, estado: 'falhou', erro: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    return out;
+}
+/** O peso do que ainda falta, em bytes — para um aviso poder dizer «faltam 241 MB» antes de começar. */
+export function pesoPorBaixar(relatorio) {
+    const feitos = new Set(relatorio.filter((r) => r.estado === 'ja-tinha' || r.estado === 'baixado').map((r) => r.id));
+    return PESADOS.filter((p) => p.url && !feitos.has(p.id)).reduce((s, p) => s + (p.bytes ?? 0), 0);
+}

package/dist-pkg/platform/storage.d.ts

@@ -62,6 +62,7 @@ export declare const KEYS: {
     lang: string;
     letterCase: string;
     captions: string;
+    tea: string;
     menuIndex: string;
     fontKey: string;
     padDesign: string;
@@ -74,9 +75,38 @@ export declare const KEYS: {
     padDpadMm: string;
     reducedMotion: string;
     toggleMoveLegacy: string;
+    /**
+     * @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: number) => string;
+    /**
+     * 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: number) => string;
     sinkP: (i: number) => string;
     easyP: (i: number) => string;
+    /**
+     * ⚠️ 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: number) => string;
     toggleRunP: (i: number) => string;
     rmWalkP: (i: number) => string;

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,109 @@
+// 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.
+ *
+ * ========================= 🔴 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 declare 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 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;