@the-inclusionist/engine 6.36.1

package/dist-pkg/input/transports.js

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/transports — O REGISTRO DE TRANSPORTES (ADR-0079). Módulo-folha: só tipos e aritmética.
+//
+// ========================= O QUE UM TRANSPORTE É =========================
+// Uma forma de alcançar as ações, e nada sobre significado. Ele declara o que OFERECE FISICAMENTE — quantos
+// lugares atribuíveis tem — e o jogador atribui a eles as ações do jogo. `TOUCH_DEFAULT` já era uma instância
+// disto antes de o modelo existir: uma atribuição padrão que a criança pode mudar.
+//
+// ========================= A GARANTIA MUDOU DE FORMA =========================
+// ⚠️ NÃO é «todo transporte alcança toda ação». É: **para os transportes disponíveis a esta criança, PELO
+// MENOS UM carrega o conjunto de ações deste jogo.** A diferença é o que permite um transporte estreito
+// existir — um acionador de dois toques, um piscar — sem que ele reprove o produto inteiro.
+//
+// ========================= E UM TRANSPORTE NUNCA REMOVE OUTRO =========================
+// Escolher o rato não desliga o teclado, o controle nem o toque. A engine OFERECE; quem escolhe é a criança
+// (ou quem a acompanha). Um método que exige coordenação fina não é exclusão enquanto os outros existirem —
+// a exclusão seria uma lista curta, não um item exigente numa lista longa.
+//
+// ========================= O QUE ESTE MÓDULO EXISTE PARA IMPEDIR =========================
+// ⚠️ Um jogo que precisa de doze ações e um transporte de nove lugares é uma combinação REAL — o controle de
+// tela tem nove slots desde sempre e o conjunto de ações passou a catorze em 2026-09-06. A resposta honesta é
+// UMA FRASE ANTES DE COMEÇAR, e não meia tela jogável: a criança que descobre no meio que não consegue
+// alcançar uma ação conclui que o jogo está partido, e ela não tem como saber que não está.
+import { ACTIONS } from '../core/actions.js';
+/**
+ * QUANTOS LUGARES CADA TRANSPORTE REAL TEM, e de onde cada número vem. Estavam medidos e viviam só no teste;
+ * um número que só existe num teste não chega a criança nenhuma.
+ *
+ *   · `gamepad: 17` — a Gamepad API «standard» declara dezassete botões. Não é escolha nossa.
+ *   · `toque: 9` — `TOUCH_DEFAULT` (input/devices) nomeia nove slots, e são nove desde sempre.
+ *   · `teclado: ACTIONS.length` — ⚠️ e este é o que precisou de decisão.
+ *
+ * ⚠️ O NÚMERO DO TECLADO NÃO É O NÚMERO DE TECLAS, e também não é o número de ligações do esquema atual. Não
+ * é o de teclas porque cem teclas não são cem lugares que uma criança encontra e lembra; não é o do esquema
+ * porque o esquema cresce, e o limite passaria a ser a configuração e não o aparelho.
+ *
+ * É `ACTIONS.length` porque o que limita um teclado, na prática deste produto, é O VOCABULÁRIO QUE A ENGINE
+ * SABE NOMEAR: um transporte que cobre todas as posições que existem não tem como ser o curto. Derivado e não
+ * escrito à mão de propósito — quando o vocabulário crescer (foi de nove para catorze em 2026-09-06), este
+ * número cresce com ele e nunca passa a mentir.
+ */
+export const LUGARES = Object.freeze({ gamepad: 17, toque: 9, teclado: ACTIONS.length });
+/**
+ * Os três transportes que esta engine sabe oferecer hoje.
+ *
+ * ⚠️ A DETECÇÃO DO TECLADO É IMPRECISA E ISSO É ACEITÁVEL — mas só porque a tela que consome isto INFORMA em
+ * vez de RECUSAR. Não há API que diga «há um teclado físico ligado»; o que o projeto já usa para a mesma
+ * pergunta é `pointer:coarse && hover:none` (o `isCoarsePointer` do `game/session`), e um tablet COM teclado
+ * responde «toque» a isso. Se a tela barrasse, esse tablet levaria uma recusa falsa num jogo que ele joga.
+ * Como ela apenas diz o que falta e deixa continuar, o erro custa uma frase a mais e nunca uma porta fechada.
+ */
+export function transportesPadrao(d) {
+    return [
+        { id: 'gamepad', slots: LUGARES.gamepad, available: d.gamepad },
+        { id: 'teclado', slots: LUGARES.teclado, available: d.teclado },
+        { id: 'toque', slots: LUGARES.toque, available: d.toque },
+    ];
+}
+/** Este transporte carrega este conjunto de ações? Aritmética, como o ADR-0079 §3 a descreve. */
+export function carries(t, acoes) {
+    return t.slots >= acoes.length;
+}
+/**
+ * Os transportes DISPONÍVEIS que carregam este conjunto.
+ *
+ * ⚠️ Disponibilidade e capacidade são conferidas nesta ordem de propósito: um transporte que caberia mas não
+ * está ligado não é resposta para uma criança que está à frente do aparelho agora.
+ */
+export function carriedBy(lista, acoes) {
+    return lista.filter((t) => t.available() && carries(t, acoes));
+}
+/**
+ * A garantia do ADR-0079 §3, como pergunta de sim ou não.
+ *
+ * ⚠️ CONJUNTO VAZIO DE AÇÕES DEVOLVE `false`, e não `true` por vacuidade. Um jogo que não declara ação
+ * nenhuma não é um jogo que qualquer transporte serve — é um jogo que ninguém consegue jogar, e
+ * `actionSetProblems` já o reprova. Devolver `true` aqui esconderia esse defeito atrás desta função.
+ */
+export function reachable(lista, acoes) {
+    return acoes.length > 0 && carriedBy(lista, acoes).length > 0;
+}
+/**
+ * Mede o alcance ANTES de a criança começar.
+ *
+ * ⚠️ Devolve DADO e não texto. A frase é da interface e tem de passar por `t()`; devolver português daqui
+ * repetiria o defeito que o `PADWIZ_STEPS` acabou de deixar de cometer.
+ */
+export function alcance(lista, acoes) {
+    const disponiveis = lista.filter((t) => t.available());
+    return {
+        ok: reachable(lista, acoes),
+        pedidas: acoes.length,
+        serviriamSeLigados: lista.filter((t) => !t.available() && carries(t, acoes)).map((t) => t.id),
+        curtos: disponiveis.filter((t) => !carries(t, acoes)).map((t) => ({ id: t.id, slots: t.slots })),
+    };
+}

package/dist-pkg/input/vocabulary-migration.d.ts

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { KeyScheme } from '../core/entity.js';
+/**
+ * Nome de plataforma → posição abstrata. **ADR-0086 §2**, e não o ADR-0074.
+ *
+ * ⚠️ A DIFERENÇA ENTRE OS DOIS REGISTROS É A TECLA DA CRIANÇA. O ADR-0074 dizia `jump → action1` e
+ * `run → action4`; o ADR-0086 corrigiu para `run → action1` e `jump → action2`, medindo que a correção é a
+ * leitura CONSERVADORA — ela deixa cada verbo na tecla e no botão que já ocupava. Traduzir por engano pela
+ * tabela do 0074 não daria erro nenhum: moveria o pulo de `J` para `U` em silêncio.
+ */
+export declare const VOCABULARIO_ANTIGO: Readonly<Record<string, string>>;
+/**
+ * ⚠️ O SEGUNDO DADO SALVO, e ele quase passou. O mapa de toque (`incl_touchmap`) guarda SLOT → AÇÃO, ou seja
+ * o nome da ação está no VALOR e não na chave: `{ b0: 'jump', b1: 'especial' }`. O tradutor de esquemas de
+ * teclado, que traduz CHAVES, passaria por cima dele sem tocar em nada.
+ *
+ * ⚠️ E O DANO SERIA PIOR DO QUE NO TECLADO. `normalizeTouchMap` funde o guardado SOBRE o padrão, então um
+ * `b0: 'jump'` gravado sobrescreveria o `b0: 'action2'` correto — e o botão da tela deixaria de fazer
+ * qualquer coisa. Num tablet de escola pública o toque não é o caminho alternativo: é o único.
+ *
+ * Foi um teste de NAVEGADOR que o encontrou (`tests/touch.browser.test.js`), depois de a suíte `node` já
+ * estar verde — o que é o argumento para os dois projetos existirem.
+ */
+export declare function migrarMapaDeToque(mapa: Record<string, string> | null | undefined): Record<string, string> | null;
+/**
+ * ⚠️ O TERCEIRO DADO SALVO, encontrado por varredura e não por acidente. Depois de o segundo aparecer num
+ * teste de navegador, a pergunta certa deixou de ser «este está migrado?» e passou a ser «QUANTOS formatos
+ * persistidos existem?». São três, e este é o do assistente de controle: `incl_padmap_<id>` guarda
+ * AÇÃO → BINDING FÍSICO, `{ jump: { b: 0 }, run: { b: 2 } }`, um por modelo de controle.
+ *
+ * ⚠️ E ELE É O MAIS CARO DE PERDER DOS TRÊS. Um mapa desses existe porque a criança (ou quem a acompanha)
+ * passou por um assistente de nove passos apertando botão a botão, provavelmente porque o controle dela não
+ * é «standard» — controles genéricos e adaptados raramente são. Perdê-lo manda essa pessoa de volta ao
+ * assistente inteiro.
+ *
+ * `_skip` e qualquer chave desconhecida atravessam, pela mesma razão das outras duas migrações.
+ */
+export declare function migrarMapaDeControle<T>(mapa: Record<string, T> | null | undefined): Record<string, T> | null;
+/** O objeto salvo, tal como `input/keyboard` o persiste. `p34` é o formato mais antigo de todos. */
+export interface SavedKB {
+    solo?: KeyScheme;
+    p2?: KeyScheme[];
+    p3?: KeyScheme[];
+    p4?: KeyScheme[];
+    p34?: (KeyScheme | null)[];
+}
+/**
+ * Traduz UM esquema salvo do vocabulário antigo para o abstrato.
+ *
+ * ⚠️ CHAVE DESCONHECIDA ATRAVESSA INTACTA, e é decisão e não descuido: `up`, `down`, `left` e `right` nunca
+ * mudaram de nome, e um esquema pode carregar uma chave que este código não conhece — dado de uma versão
+ * futura, ou lixo. Apagá-la seria destruir dado que não entendemos, e é o que faria as quatro direções
+ * sumirem. É também o que torna esta função IDEMPOTENTE: aplicada sobre um esquema já migrado, nenhuma chave
+ * casa e o resultado é igual à entrada, o que importa porque `loadKB` pode correr mais de uma vez na sessão.
+ */
+export declare function migrarEsquema(esquema: KeyScheme | null | undefined): KeyScheme | null;
+/** Traduz o objeto salvo inteiro — o esquema solo e as listas por contagem de jogadores. */
+export declare function migrarSalvo(s: SavedKB | null | undefined): SavedKB | null;

package/dist-pkg/input/vocabulary-migration.js

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/vocabulary-migration — O ÚNICO SÍTIO DA ENGINE QUE PODE DIZER `jump`, E POR QUANTO TEMPO.
+//
+// ========================= POR QUE ESTE MÓDULO EXISTE SEPARADO =========================
+// O gate `action-vocabulary-boundary` reprova a engine por nomear os verbos do jogo, e estava certo ao
+// reprovar esta tabela quando ela nasceu dentro de `input/keyboard.ts`. Só que a tabela PRECISA de os nomear:
+// traduzir o vocabulário antigo é literalmente a função dela.
+//
+// ⚠️ E A SAÍDA NÃO FOI LEVANTAR O TETO. Levantar um teto que "só encolhe" é o afrouxamento que o gate existe
+// para impedir, e uma exceção sem endereço vira precedente para a próxima. A saída foi QUARENTENAR: o
+// acoplamento inteiro mora aqui, num ficheiro cujo nome diz que ele é histórico, com um teto próprio e uma
+// data de morte.
+//
+// ⚠️ QUANDO ISTO SE APAGA: quando não restar dado salvo no formato antigo. Não há como saber isso do lado do
+// código — o dado está no navegador de cada criança —, então o critério é de tempo e é do Dev. Enquanto
+// houver, apagar este ficheiro apaga o remapeamento de quem o fez.
+//
+// ========================= O QUE SE PERDE SE ISTO ESTIVER ERRADO =========================
+// Quem remapeou teclas normalmente remapeou por NECESSIDADE — alcance de mão, dedo que não estica, teclado
+// sem numpad. Um esquema salvo que deixe de casar não dá erro: as teclas simplesmente param de responder, e
+// a criança conclui que o jogo quebrou. É perda de uma adaptação, não de uma preferência.
+/**
+ * Nome de plataforma → posição abstrata. **ADR-0086 §2**, e não o ADR-0074.
+ *
+ * ⚠️ A DIFERENÇA ENTRE OS DOIS REGISTROS É A TECLA DA CRIANÇA. O ADR-0074 dizia `jump → action1` e
+ * `run → action4`; o ADR-0086 corrigiu para `run → action1` e `jump → action2`, medindo que a correção é a
+ * leitura CONSERVADORA — ela deixa cada verbo na tecla e no botão que já ocupava. Traduzir por engano pela
+ * tabela do 0074 não daria erro nenhum: moveria o pulo de `J` para `U` em silêncio.
+ */
+export const VOCABULARIO_ANTIGO = Object.freeze({
+    run: 'action1',
+    jump: 'action2',
+    especial: 'action3',
+    swap: 'action4',
+    // ⚠️ E UMA QUINTA ENTRADA QUE NÃO É UM VERBO DE PLATAFORMA. A camada de toque chamava `pause` a posição
+    // que todo o resto chama `start` — duas palavras para a mesma coisa, e a do toque era a única que não
+    // existia no conjunto abstrato. Um mapa de toque gravado antes disto tem `start: 'pause'` no slot do
+    // START, e sem esta linha esse botão deixaria de pausar: `decide()` passa a procurar `'start'` e
+    // receberia `'pause'`, que já não é nada — sem erro, sem aviso, e o único botão de pausa de um tablet.
+    pause: 'start',
+});
+/**
+ * ⚠️ O SEGUNDO DADO SALVO, e ele quase passou. O mapa de toque (`incl_touchmap`) guarda SLOT → AÇÃO, ou seja
+ * o nome da ação está no VALOR e não na chave: `{ b0: 'jump', b1: 'especial' }`. O tradutor de esquemas de
+ * teclado, que traduz CHAVES, passaria por cima dele sem tocar em nada.
+ *
+ * ⚠️ E O DANO SERIA PIOR DO QUE NO TECLADO. `normalizeTouchMap` funde o guardado SOBRE o padrão, então um
+ * `b0: 'jump'` gravado sobrescreveria o `b0: 'action2'` correto — e o botão da tela deixaria de fazer
+ * qualquer coisa. Num tablet de escola pública o toque não é o caminho alternativo: é o único.
+ *
+ * Foi um teste de NAVEGADOR que o encontrou (`tests/touch.browser.test.js`), depois de a suíte `node` já
+ * estar verde — o que é o argumento para os dois projetos existirem.
+ */
+export function migrarMapaDeToque(mapa) {
+    if (!mapa)
+        return null;
+    const saida = {};
+    for (const [slot, acao] of Object.entries(mapa)) {
+        saida[slot] = VOCABULARIO_ANTIGO[acao] ?? acao;
+    }
+    return saida;
+}
+/**
+ * ⚠️ O TERCEIRO DADO SALVO, encontrado por varredura e não por acidente. Depois de o segundo aparecer num
+ * teste de navegador, a pergunta certa deixou de ser «este está migrado?» e passou a ser «QUANTOS formatos
+ * persistidos existem?». São três, e este é o do assistente de controle: `incl_padmap_<id>` guarda
+ * AÇÃO → BINDING FÍSICO, `{ jump: { b: 0 }, run: { b: 2 } }`, um por modelo de controle.
+ *
+ * ⚠️ E ELE É O MAIS CARO DE PERDER DOS TRÊS. Um mapa desses existe porque a criança (ou quem a acompanha)
+ * passou por um assistente de nove passos apertando botão a botão, provavelmente porque o controle dela não
+ * é «standard» — controles genéricos e adaptados raramente são. Perdê-lo manda essa pessoa de volta ao
+ * assistente inteiro.
+ *
+ * `_skip` e qualquer chave desconhecida atravessam, pela mesma razão das outras duas migrações.
+ */
+export function migrarMapaDeControle(mapa) {
+    if (!mapa)
+        return null;
+    const saida = {};
+    for (const [chave, valor] of Object.entries(mapa)) {
+        saida[VOCABULARIO_ANTIGO[chave] ?? chave] = valor;
+    }
+    return saida;
+}
+/**
+ * Traduz UM esquema salvo do vocabulário antigo para o abstrato.
+ *
+ * ⚠️ CHAVE DESCONHECIDA ATRAVESSA INTACTA, e é decisão e não descuido: `up`, `down`, `left` e `right` nunca
+ * mudaram de nome, e um esquema pode carregar uma chave que este código não conhece — dado de uma versão
+ * futura, ou lixo. Apagá-la seria destruir dado que não entendemos, e é o que faria as quatro direções
+ * sumirem. É também o que torna esta função IDEMPOTENTE: aplicada sobre um esquema já migrado, nenhuma chave
+ * casa e o resultado é igual à entrada, o que importa porque `loadKB` pode correr mais de uma vez na sessão.
+ */
+export function migrarEsquema(esquema) {
+    if (!esquema)
+        return null;
+    const saida = {};
+    for (const [chave, teclas] of Object.entries(esquema)) {
+        const nova = VOCABULARIO_ANTIGO[chave] ?? chave;
+        // ⚠️ Esquema MEIO migrado (as duas chaves presentes): a UNIÃO, nunca a sobreposição. Perder uma tecla é
+        // o dano que este módulo existe para impedir; ter a mesma tecla duas vezes não é dano nenhum.
+        saida[nova] = saida[nova] ? [...new Set([...saida[nova], ...teclas])] : [...teclas];
+    }
+    return saida;
+}
+/** Traduz o objeto salvo inteiro — o esquema solo e as listas por contagem de jogadores. */
+export function migrarSalvo(s) {
+    if (!s)
+        return null;
+    const lista = (arr) => (Array.isArray(arr) ? arr.map((m) => migrarEsquema(m)) : undefined);
+    const out = {};
+    const solo = migrarEsquema(s.solo);
+    if (solo)
+        out.solo = solo;
+    for (const g of ['p2', 'p3', 'p4']) {
+        const v = lista(s[g]);
+        if (v)
+            out[g] = v;
+    }
+    // `p34` migra de VOCABULÁRIO aqui e de FORMA em `loadKB`, que já o fazia antes deste módulo existir.
+    // Sem esta linha, o dado mais velho de todos seria o único a perder-se.
+    if (Array.isArray(s.p34))
+        out.p34 = s.p34.map((m) => migrarEsquema(m));
+    return out;
+}

package/dist-pkg/platform/audio-ambient.d.ts

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+interface Vec2 {
+    x: number;
+    y: number;
+}
+export interface AudioAmbientCtx {
+    ensureAC: () => AudioContext | null;
+    getAudioCtx: () => AudioContext | null;
+    catNode: (cat: string) => AudioNode | null;
+    audioOut: () => AudioNode | null;
+    noiseBuffer: (ac: AudioContext) => AudioBuffer;
+    getSoundOn: () => boolean;
+    getVolume: () => number;
+    getAudioCat: () => Record<string, {
+        on: boolean;
+    }> | null;
+    getPlayers: () => Vec2[];
+    tileAt: (x: number, y: number) => number;
+    TILE: number;
+    getRainLevel: () => number;
+}
+export interface AudioAmbient {
+    updateAmbient: () => void;
+    thunder: (inten: number) => void;
+}
+export declare function createAudioAmbient(ctx: AudioAmbientCtx): AudioAmbient;
+export {};

package/dist-pkg/platform/audio-ambient.js

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/audio-ambient — trilha de AMBIENTE sintetizada (loops de ruído filtrado) + trovão. Última rodada do Tier 2 de
+// áudio (r4). O clima VISUAL (updateWeather/drawWeather/chuva) fica no game.js e migra p/ render depois — aqui só o SOM.
+// Ponte com o clima: `_rainLevel` (0..1) é calculado por updateWeather (game.js) e LIDO aqui por getter → o volume da
+// chuva "segue o visual". Injeção por closure (padrão Tier 1).
+//   updateAmbient() — por frame: constrói a trilha 1x (lazy) e ajusta o ganho de ÁGUA (proximidade de tiles de água) e
+//                     de CHUVA (segue _rainLevel). Gated por audioCat.ambient.on.
+//   thunder(inten)  — rumor grave sintetizado (ruído passa-baixas), intensidade variável; chamado por updateWeather.
+// Extraído do game.js. Ver docs/5-Refactoring/plano-modularizacao-mapa.md (Tier 2, áudio rodada 4).
+export function createAudioAmbient(ctx) {
+    let _ambient = null;
+    function buildAmbient(ac) {
+        const cat = ctx.catNode('ambient');
+        if (!cat)
+            return null;
+        const n = (ac.sampleRate * 2) | 0, buf = ac.createBuffer(1, n, ac.sampleRate), d = buf.getChannelData(0);
+        let last = 0;
+        for (let i = 0; i < n; i++) {
+            const w = Math.random() * 2 - 1;
+            last = (last + 0.02 * w) / 1.02;
+            d[i] = last * 3.2;
+        } // ruído rosa em loop
+        const mk = (type, freq, q, vol) => {
+            const s = ac.createBufferSource();
+            s.buffer = buf;
+            s.loop = true;
+            const f = ac.createBiquadFilter();
+            f.type = type;
+            f.frequency.value = freq;
+            if (q)
+                f.Q.value = q;
+            const g = ac.createGain();
+            g.gain.value = vol;
+            s.connect(f).connect(g).connect(cat);
+            try {
+                s.start();
+            }
+            catch (e) { /* noop */ }
+            return g;
+        };
+        // trânsito/rumor · folhas/vento · água (proximidade) · chuva (ciclo)
+        return { hum: mk('lowpass', 480, 0, 0.055), wind: mk('highpass', 3200, 0, 0.028), water: mk('bandpass', 820, 1.4, 0), rain: mk('highpass', 1700, 0, 0) };
+    }
+    function updateAmbient() {
+        const ac = ctx.getAudioCtx(), cat = ctx.getAudioCat();
+        if (!ac || !ctx.getSoundOn() || !cat || !cat.ambient || !cat.ambient.on)
+            return;
+        if (!_ambient) {
+            _ambient = buildAmbient(ac);
+            if (!_ambient)
+                return;
+        }
+        const pl = ctx.getPlayers()[0], px = Math.floor(pl.x / ctx.TILE), py = Math.floor(pl.y / ctx.TILE);
+        let nearWater = 0;
+        for (let dx = -3; dx <= 3; dx++)
+            for (let dy = -3; dy <= 3; dy++) {
+                if (ctx.tileAt(px + dx, py + dy) === 3)
+                    nearWater = Math.max(nearWater, 1 - Math.hypot(dx, dy) / 4.2);
+            }
+        _ambient.water.gain.setTargetAtTime(0.15 * nearWater, ac.currentTime, 0.3);
+        _ambient.rain.gain.setTargetAtTime(0.09 * ctx.getRainLevel(), ac.currentTime, 0.5); // chuva segue _rainLevel; 0 = silêncio total
+    }
+    function thunder(inten) {
+        if (!ctx.getSoundOn() || ctx.getVolume() <= 0)
+            return;
+        const ac = ctx.ensureAC();
+        if (!ac)
+            return;
+        try {
+            const vol = ctx.getVolume();
+            const src = ac.createBufferSource();
+            src.buffer = ctx.noiseBuffer(ac);
+            src.loop = true;
+            const bq = ac.createBiquadFilter();
+            bq.type = 'lowpass';
+            bq.frequency.value = 140 + Math.random() * 220;
+            bq.Q.value = 0.7;
+            const g = ac.createGain(), t = ac.currentTime, dur = 0.7 + inten * 1.4;
+            g.gain.setValueAtTime(0.0001, t);
+            g.gain.exponentialRampToValueAtTime(Math.min(0.55, 0.2 * inten) * vol, t + 0.04);
+            g.gain.exponentialRampToValueAtTime(0.0001, t + dur);
+            src.connect(bq).connect(g).connect(ctx.catNode('ambient') || ctx.audioOut() || ac.destination);
+            src.start(t);
+            src.stop(t + dur + 0.1);
+        }
+        catch (e) { /* Web Audio indisponível */ }
+    }
+    return { updateAmbient, thunder };
+}

package/dist-pkg/platform/audio-earcons.d.ts

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+interface SfxDef {
+    t: OscillatorType;
+    f: number;
+    d: number;
+    cap?: string;
+}
+export interface AudioEarconsCtx {
+    SFX: Record<string, SfxDef | undefined>;
+    ensureAC: () => AudioContext | null;
+    catNode: (cat: string) => AudioNode | null;
+    audioOut: () => AudioNode | null;
+    noiseHit: (mat: string) => void;
+    getSoundOn: () => boolean;
+    getVolume: () => number;
+    getCaptionsOn: () => boolean;
+    showCaption: (txt: string) => void;
+}
+export interface AudioEarcons {
+    sfx: (name: string) => void;
+    doorSound: (mat: string) => void;
+}
+export declare function createAudioEarcons(ctx: AudioEarconsCtx): AudioEarcons;
+export {};

package/dist-pkg/platform/audio-earcons.js

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/audio-earcons — earcons (ícones sonoros) do jogo + a ponte com as LEGENDAS visuais (a11y surdez).
+// Tier 2 do áudio, rodada 2. Depende das primitivas de platform/audio (SFX/ensureAC/catNode/audioOut/noiseHit) e,
+// por injeção, do estado de legenda que VIVE no game.js (captionsOn é alternado pela UI; showCaption toca o #caption
+// e é reusado por win()). Injeção por closure (padrão Tier 1).
+//   sfx(name)      — toca o earcon da tabela SFX (oscilador) E, se as legendas estão ON e o earcon tem `.cap`, mostra a
+//                    legenda ANTES de checar o som → um jogador surdo "vê" o som mesmo com o áudio desligado.
+//   doorSound(mat) — porta: rangido (madeira, sawtooth) ou clangor (ferro, square) + baque de ruído (noiseHit).
+// Extraído do game.js. Ver docs/5-Refactoring/plano-modularizacao-mapa.md (Tier 2, áudio rodada 2).
+import { t } from '../core/i18n.js'; // item 19: `cap` guarda CHAVE, e quem exibe resolve
+export function createAudioEarcons(ctx) {
+    function sfx(name) {
+        const c = ctx.SFX[name];
+        if (!c)
+            return;
+        // LEGENDA primeiro (visual + aria-live via role=status) — e RESOLVIDA no ponto de uso: `cap` guarda a
+        // CHAVE desde o item 19, porque a tabela vive no jogo e uma tabela de `const` com texto congelaria no
+        // idioma do boot. Quem exibe resolve; é a mesma regra de `render/viz-modes`.
+        if (ctx.getCaptionsOn() && c.cap)
+            ctx.showCaption(t(c.cap));
+        if (!ctx.getSoundOn() || ctx.getVolume() <= 0)
+            return; // ...só então o som — surdez: a legenda já saiu
+        try {
+            const ac = ctx.ensureAC();
+            if (!ac)
+                return;
+            const o = ac.createOscillator(), g = ac.createGain();
+            o.type = c.t;
+            o.frequency.value = c.f;
+            g.gain.value = 0.0001;
+            o.connect(g).connect(ctx.catNode('earcons') || ctx.audioOut() || ac.destination);
+            const t = ac.currentTime, vol = ctx.getVolume();
+            g.gain.exponentialRampToValueAtTime(Math.max(0.02, 0.25 * vol), t + 0.01);
+            g.gain.exponentialRampToValueAtTime(0.0001, t + c.d);
+            o.start(t);
+            o.stop(t + c.d + 0.02);
+        }
+        catch (e) { /* Web Audio indisponível */ }
+    }
+    function doorSound(mat) {
+        if (!ctx.getSoundOn() || ctx.getVolume() <= 0)
+            return;
+        const ac = ctx.ensureAC();
+        if (!ac)
+            return;
+        try { // porta: rangido (madeira) ou clangor (ferro) + baque
+            const o = ac.createOscillator(), g = ac.createGain(), t = ac.currentTime, vol = ctx.getVolume();
+            o.type = mat === 'ferro' ? 'square' : 'sawtooth';
+            o.frequency.setValueAtTime(mat === 'ferro' ? 520 : 200, t);
+            o.frequency.exponentialRampToValueAtTime(mat === 'ferro' ? 300 : 110, t + 0.3);
+            g.gain.setValueAtTime(0.0001, t);
+            g.gain.exponentialRampToValueAtTime(0.14 * vol, t + 0.03);
+            g.gain.exponentialRampToValueAtTime(0.0001, t + 0.35);
+            o.connect(g).connect(ctx.catNode('interact') || ctx.audioOut() || ac.destination);
+            o.start(t);
+            o.stop(t + 0.4);
+            ctx.noiseHit(mat === 'ferro' ? 'ferro' : 'madeira');
+        }
+        catch (e) { /* Web Audio indisponível */ }
+    }
+    return { sfx, doorSound };
+}

package/dist-pkg/platform/audio-jingles.d.ts

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+type ToneFn = (freq: number, dur: number, type?: OscillatorType, when?: number, vol?: number) => void;
+export interface AudioJinglesCtx {
+    tone: ToneFn;
+    ensureAC: () => AudioContext | null;
+    catNode: (cat: string) => AudioNode | null;
+    audioOut: () => AudioNode | null;
+    getSoundOn: () => boolean;
+    getVolume: () => number;
+}
+export interface AudioJingles {
+    playVictory: () => void;
+    playPuzzleSolved: () => void;
+    firework: (when?: number) => void;
+}
+export declare function createAudioJingles(ctx: AudioJinglesCtx): AudioJingles;
+export {};

package/dist-pkg/platform/audio-jingles.js

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/audio-jingles — recompensas sonoras (jingles) SEM estado de jogo: vitória, enigma resolvido e fogos.
+// Primeiro passo do Tier 2 (áudio): o cluster mais puro — só depende das primitivas de platform/audio (tone/ensureAC/
+// catNode/audioOut) + soundOn/volume vivos. Sem tiles, players, coins nem DOM. Injeção por closure (padrão Tier 1).
+//   playVictory      — jingle 8-bit ascendente (C5 E5 G5 C6 B5 E6) + 4 fogos de artifício.
+//   playPuzzleSolved — frase DOCE senoidal ascendente (E5 G5 B5 E6 + C6 de fundo), Zelda OoT; NUNCA agressiva (José).
+//   firework         — assobio subindo (sine 300→1200 Hz) + estouro/crepitar (5 osciladores square); usado por playVictory.
+// Extraído do game.js (linhas 625-633). Ver docs/5-Refactoring/plano-modularizacao-mapa.md (Tier 2, áudio rodada 1).
+export function createAudioJingles(ctx) {
+    // Fogos: só osciladores crus (não usam `tone`), então guardam soundOn/volume aqui e escalam o ganho pelo volume.
+    function firework(when) {
+        if (!ctx.getSoundOn() || ctx.getVolume() <= 0)
+            return;
+        try {
+            const ac = ctx.ensureAC();
+            if (!ac)
+                return;
+            const vol = ctx.getVolume(), t = ac.currentTime + (when || 0);
+            const o = ac.createOscillator(), g = ac.createGain();
+            o.type = 'sine';
+            o.frequency.setValueAtTime(300, t);
+            o.frequency.exponentialRampToValueAtTime(1200, t + 0.35); // assobio subindo
+            const out = ctx.catNode('earcons') || ctx.audioOut() || ac.destination;
+            g.gain.setValueAtTime(0.0001, t);
+            g.gain.exponentialRampToValueAtTime(0.12 * vol, t + 0.05);
+            g.gain.exponentialRampToValueAtTime(0.0001, t + 0.36);
+            o.connect(g).connect(out);
+            o.start(t);
+            o.stop(t + 0.4);
+            [0, 0.04, 0.09, 0.15, 0.22].forEach((dt, i) => {
+                const po = ac.createOscillator(), pg = ac.createGain(), tt = t + 0.36 + dt;
+                po.type = 'square';
+                po.frequency.setValueAtTime(180 + ((i * 131) % 520), tt);
+                pg.gain.setValueAtTime(0.18 * vol, tt);
+                pg.gain.exponentialRampToValueAtTime(0.0001, tt + 0.09);
+                po.connect(pg).connect(out);
+                po.start(tt);
+                po.stop(tt + 0.11);
+            });
+        }
+        catch (e) { /* Web Audio indisponível */ }
+    }
+    function playVictory() {
+        [[523, 0], [659, 0.12], [784, 0.24], [1047, 0.36], [988, 0.52], [1319, 0.64]]
+            .forEach(([f, w]) => ctx.tone(f, 0.16, 'square', w, 0.22));
+        [0.2, 0.8, 1.35, 1.9].forEach((w) => firework(w));
+    }
+    function playPuzzleSolved() {
+        [[659, 0], [784, 0.13], [988, 0.26], [1319, 0.42]]
+            .forEach(([f, w]) => ctx.tone(f, 0.32, 'sine', w, 0.12));
+        ctx.tone(1047, 0.6, 'sine', 0.42, 0.07);
+    }
+    return { playVictory, playPuzzleSolved, firework };
+}

package/dist-pkg/platform/audio-mixer.d.ts

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+type AudioCat = {
+    k: string;
+    lbl: string;
+};
+type AudioCatState = {
+    on: boolean;
+    vol: number;
+};
+export declare const AUDIO_CATS: AudioCat[];
+export declare function defaultAudioCat(k: string): AudioCatState;
+export declare function loadAudioCat(): Record<string, AudioCatState>;
+export declare function saveAudioCat(k: string, obj: AudioCatState): void;
+export {};

package/dist-pkg/platform/audio-mixer.js

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/audio-mixer.ts — categorias do mixer de áudio (dados) + carga/persistência. Módulo-folha (storage).
+// O grafo de áudio (catNode/setCatGain/_catNodes/audioCtx) e o objeto audioCat VIVO ficam no game.js — aqui só
+// a lista das categorias, o estado inicial (com o default TTS-off) e o save por categoria. (Fase 2, áudio)
+import * as store from './storage.js';
+export const AUDIO_CATS = [
+    { k: 'music', lbl: 'Música' }, { k: 'ambient', lbl: 'Sons ambiente (água, rua, trânsito, folhas, chuva)' },
+    { k: 'interact', lbl: 'Efeitos de interação (passos, portas, escada)' }, { k: 'earcons', lbl: 'Earcons (pulo, moeda, dano…)' },
+    { k: 'other', lbl: 'Outros efeitos' }, { k: 'tts', lbl: 'Narração (TTS)' }, { k: 'sonar', lbl: 'Sonar' },
+    { k: 'guard', lbl: 'Guarda de beirada' }, { k: 'guide', lbl: 'Pista / guia auditivo' },
+];
+// Estado inicial por categoria. O que estiver SALVO sobrepõe o default — e isso é deliberado: um valor salvo
+// significa que alguém MEXEU naquele controle, e a escolha da criança não é minha para desfazer. Quem já
+// tinha ligado o guia continua com ele ligado.
+/**
+ * O estado de FÁBRICA de uma categoria. Existe com nome porque dois lugares precisam dele: a leitura do boot
+ * (quando nada foi salvo) e o "restaurar padrões" do menu auditivo (ADR-0028). Escrever `k !== 'tts'` e `0.8`
+ * nos dois seria a mesma cópia sem dono que este repositório já viu divergir — e aqui a divergência colocaria
+ * a criança num terceiro estado, nem o dela nem o de fábrica.
+ */
+/**
+ * As categorias que nascem DESLIGADAS, e o motivo de cada uma. Lista com razão escrita, e não um `k !== 'x'`
+ * pendurado numa expressão — a próxima que entrar precisa dizer por quê.
+ *
+ *  · `tts` — voz robótica irrita e sobrecarrega pessoas com TEA. Quem precisa liga no menu. (O TTS do
+ *    letramento é o `gameSay()`, independente disto e sempre ativo.)
+ *
+ *  · `guide` — o BEACON do guia auditivo, DESLIGADO desde 2026-08-26 por decisão do Dev, e é uma medida
+ *    PROVISÓRIA que não deve virar permanente sem alguém a rever.
+ *
+ *    O que ele faz hoje: um `triangle` de 0,12 s apontado para o alvo mais próximo, a cada 0,8 s, PARA
+ *    SEMPRE — sem depender de movimento, de tecla ou de nada ter mudado. No modo cego `needsAudioCues` é
+ *    sempre verdadeiro, então a criança que mais precisa de pistas é a que ouve o bipe a partida inteira.
+ *
+ *    O veredito do Dev: "um ping é a pior escolha possível, tenebroso para quem tem TEA". Não é a FREQUÊNCIA
+ *    que está errada — é o bipe. Reduzi-lo a "só andando" deixaria a mesma coisa doendo menos vezes.
+ *
+ *    O substituto que ele descreveu é maior que uma troca de som e por isso não entra junto: uma música que
+ *    fica mais intensa conforme se aproxima, e ANTES dela é preciso MAPEAR A ROTA — preencher o mapa com as
+ *    direções por onde há ar ou água, para que a pista siga um caminho navegável em vez de apontar em linha
+ *    reta para dentro de uma parede. Está registrado como issue; até ela existir, o silêncio é melhor que o
+ *    bipe, e a criança que quiser o bipe continua podendo ligá-lo no menu auditivo.
+ */
+const NASCEM_DESLIGADAS = new Set(['tts', 'guide']);
+export function defaultAudioCat(k) {
+    return { on: !NASCEM_DESLIGADAS.has(k), vol: 0.8 };
+}
+export function loadAudioCat() {
+    const cat = {};
+    AUDIO_CATS.forEach((c) => {
+        const d = defaultAudioCat(c.k);
+        let on = d.on, vol = d.vol;
+        const o = store.getJSON('incl_audiocat_' + c.k, null);
+        if (o) {
+            on = !!o.on;
+            vol = +o.vol;
+        }
+        cat[c.k] = { on, vol };
+    });
+    return cat;
+}
+export function saveAudioCat(k, obj) { store.setJSON('incl_audiocat_' + k, obj); }