@the-inclusionist/engine 6.36.1

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

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { PlayerView, ControlledPlayer } from '../core/entity.js';
+import type { AudioSonar, PlayerAudioOut, PlayerCtxOut } from './audio-sonar.js';
+export type { PlayerCtxOut };
+/**
+ * O jogador visto pela BENGALA e pelo NADO. `facing` e `wnT` são desta metade; a outra não os usa.
+ *
+ * A saída dedicada (`_ac`/`_acOut`) entra por INTERSECÇÃO com o tipo do dono, `PlayerAudioOut` de
+ * `platform/audio-sonar` — não por uma redeclaração local.
+ *
+ * ⚠️ A JUSTIFICATIVA QUE ESTAVA AQUI ERA FALSA e vale corrigi-la em vez de apagá-la, senão o próximo leitor
+ * a re-deriva: dizia que `core/` "não pode importar tipos de Web Audio". Não há importação a fazer — o
+ * `tsconfig.json` tem `"lib": ["ES2022", "DOM", "DOM.Iterable"]`, então `AudioContext` e `GainNode` são
+ * globais ambientes em qualquer arquivo desta árvore. O motivo verdadeiro é de CAMADA: `_ac` e `_acOut` não
+ * são da entidade da engine, e por isso o `core/entity` deixou de mencioná-los (ADR-0039, opção A1).
+ */
+type Player = PlayerView<'x' | 'y' | 'facing' | 'viz' | 'i' | 'audioSink' | 'wnT' | 'guideT' | 'pad'> & PlayerAudioOut & Pick<ControlledPlayer, 'ctrl'>;
+export interface AudioNavCtx {
+    tileAt: (x: number, y: number) => number;
+    solidAt: (x: number, y: number) => boolean;
+    held: (pl: Player, act: string) => boolean;
+    tonePan: (freq: number, dur: number, cat: string, pan?: number | null, vol?: number, type?: OscillatorType, pc?: PlayerCtxOut | null) => void;
+    noiseHit: (mat: string, pan?: number, pc?: PlayerCtxOut | null) => void;
+    BOX: {
+        w: number;
+        h: number;
+    };
+    TILE: number;
+    getCenario: () => string;
+    /**
+     * A NAVEGAÇÃO SONORA, pronta (`platform/audio-sonar`). Entra por injeção e não por importação: é o que
+     * permite empacotar o sonar sem levar a bengala junto — e é a diferença entre "dois arquivos" e "dois
+     * módulos". Onze coisas do ctx antigo saíram com ela.
+     */
+    sonar: AudioSonar;
+}
+export interface AudioNav {
+    playerCtx: (pl: Player) => PlayerCtxOut | null;
+    caneProbe: (pl: Player) => string;
+    caneTap: (pl: Player) => void;
+    waterNav: (pl: Player) => void;
+    panFor: (wx: number, pl: Player) => number;
+    needsAudioCues: (pl: Player) => boolean;
+    sonar: (pl: Player) => void;
+    updateGuide: () => void;
+    readonly caneCount: number;
+    readonly waterNavCount: number;
+    readonly sonarCount: number;
+    readonly guideCount: number;
+}
+export declare function createAudioNav(ctx: AudioNavCtx): AudioNav;

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

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/audio-nav — BENGALA e NADO CEGO: as pistas sonoras que só existem onde há MUNDO (item 19).
+//
+// ========================= ESTE MÓDULO ERA DOIS =========================
+// O achado 9 do segundo consumidor: "o módulo é DOIS módulos com um nome só — `caneProbe`/`caneTap`/
+// `waterNav` são bengala e natação, isto é, plataforma; `sonar`/`panFor`/`needsAudioCues` são navegação
+// sonora, que serve a qualquer jogo". A navegação sonora saiu para `platform/audio-sonar` e recebe o
+// CONTRATO em vez de tiles; aqui ficou a metade que lê o mundo, e que lê sem disfarce.
+//
+// O QUE SOBROU É PLATAFORMA, e é bom que o nome não esconda isso:
+//   caneProbe(pl) — material À FRENTE (água/vazio/madeira/chão do tema), lendo tile e chão.
+//   caneTap(pl)   — batida da bengala no material adiante (ou tom grave oco no vazio).
+//   waterNav(pl)  — nado cego: contato com paredes/chão/superfície (cordas).
+//
+// A bengala precisa de `facing`, `BOX.w` e `TILE` para saber o que é "à frente"; o nado precisa de `solidAt`
+// em três alturas. Nada disso é traduzível para um jogo sem corpo e sem mundo, e por isso NÃO foi traduzido:
+// o corte separa o que viaja do que não viaja, em vez de fingir que tudo viaja.
+//
+// ========================= A METADE QUE VIAJOU CONTINUA SAINDO DAQUI =========================
+// `playerCtx`, `panFor`, `needsAudioCues`, `sonar` e `updateGuide` seguem no retorno, delegados ao
+// `AudioSonar` injetado. Não é preguiça de mexer no chamador: a bengala PRECISA do `playerCtx` (a batida sai
+// no dispositivo do jogador) e o `main.js` monta um objeto só de navegação. O que mudou é que este módulo
+// deixou de IMPLEMENTAR a metade genérica — ele a repassa, e quem quiser só ela importa o outro arquivo.
+// Extraído do game.js. Ver docs/5-Refactoring/plano-modularizacao-mapa.md (Tier 2, áudio rodada 3).
+export function createAudioNav(ctx) {
+    const SURF_MAT = { cidade: 'piso', campo: 'grama', floresta: 'grama', cemiterio: 'terra', espaco: 'pedra', classico: 'pedra' }; // chão por tema
+    let _caneCount = 0, _waterNavCount = 0;
+    const som = ctx.sonar; // a metade que viaja, injetada
+    const playerCtx = (pl) => som.playerCtx(pl);
+    function caneProbe(pl) {
+        const dir = pl.facing < 0 ? -1 : 1;
+        const ax = Math.floor((pl.x + dir * (ctx.BOX.w / 2 + ctx.TILE * 0.6)) / ctx.TILE), footTy = Math.floor((pl.y + 1) / ctx.TILE);
+        if (ctx.tileAt(ax, footTy) === 3 || ctx.tileAt(ax, footTy - 1) === 3)
+            return 'agua'; // água à frente
+        let gty = -1;
+        for (let ty = footTy; ty <= footTy + 1; ty++) {
+            if (ctx.solidAt(ax, ty)) {
+                gty = ty;
+                break;
+            }
+        } // chão (pé ou 1 abaixo = degrau/rampa)
+        if (gty < 0)
+            return 'vazio'; // sem chão → fosso
+        if (ctx.tileAt(ax, gty) === 4)
+            return 'madeira'; // escada
+        return SURF_MAT[ctx.getCenario()] || 'pedra';
+    }
+    function caneTap(pl) {
+        const mat = caneProbe(pl), dir = pl.facing < 0 ? -1 : 1, pan = dir * 0.5, pc = playerCtx(pl);
+        _caneCount++;
+        if (mat === 'vazio') {
+            ctx.tonePan(150, 0.18, 'guard', pan, 0.16, 'sine', pc);
+            return;
+        } // vazio = tom grave oco
+        ctx.noiseHit(mat, pan, pc); // batida no material adiante (no dispositivo do jogador)
+    }
+    function waterNav(pl) {
+        // dir tipado como number (não 1|-1) DE PROPÓSITO: o original usa `dir!==0` (sempre true aqui, pois facing é ±1) —
+        // preservo essa guarda sempre-verdadeira exatamente; alargar o tipo satisfaz o tsc sem mudar o comportamento.
+        const dir = pl.facing < 0 ? -1 : 1, tx = Math.floor(pl.x / ctx.TILE), tyF = Math.floor((pl.y - 1) / ctx.TILE), tyH = Math.floor((pl.y - ctx.BOX.h) / ctx.TILE);
+        const wallAhead = ctx.solidAt(tx + dir, tyF) || ctx.solidAt(tx + dir, tyH); // parede lateral (azulejo)
+        const floorBelow = ctx.solidAt(tx, tyF + 1); // chão (fundo)
+        const openAbove = ctx.tileAt(tx, tyH - 1) !== 3 && !ctx.solidAt(tx, tyH - 1); // acima da cabeça é ar → dá p/ subir/sair
+        const moving = (dir !== 0) || ctx.held(pl, 'up') || ctx.held(pl, 'down'), pc = playerCtx(pl);
+        pl.wnT = (pl.wnT || 0) + 1;
+        if (pl.wnT < 18)
+            return;
+        let played = true;
+        if (openAbove && wallAhead)
+            ctx.noiseHit('parede', dir * 0.5, pc); // superfície + parede = batida (fim da corda)
+        else if (openAbove && moving)
+            ctx.tonePan(560, 0.09, 'guide', dir * 0.4, 0.12, 'sine', pc); // corda livre: "dá p/ subir"
+        else if (wallAhead && dir !== 0)
+            ctx.noiseHit('parede', dir * 0.5, pc); // parede submersa à frente
+        else if (floorBelow && ctx.held(pl, 'down'))
+            ctx.noiseHit('areia', 0, pc); // fundo (chão)
+        else
+            played = false;
+        if (played) {
+            pl.wnT = 0;
+            _waterNavCount++;
+        }
+        else
+            pl.wnT = 17; // sem contato = SEM som (pronto p/ tocar ao encostar)
+    }
+    return {
+        playerCtx, caneProbe, caneTap, waterNav,
+        // Delegação PURA para a metade que viajou. Sem lógica no meio: um adaptador que decidisse alguma coisa
+        // seria uma terceira implementação escondida entre as duas.
+        panFor: (wx, pl) => som.panFor(wx, pl),
+        needsAudioCues: (pl) => som.needsAudioCues(pl),
+        sonar: (pl) => som.sonar(pl),
+        updateGuide: () => som.updateGuide(),
+        get caneCount() { return _caneCount; },
+        get waterNavCount() { return _waterNavCount; },
+        get sonarCount() { return som.sonarCount; },
+        get guideCount() { return som.guideCount; },
+    };
+}

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

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type Spot, type Topology, type Speakable } from '../core/contract.js';
+export type SinkAC = AudioContext & {
+    setSinkId?: (id: string) => Promise<void>;
+};
+/**
+ * O jogador visto pela navegação sonora. É a fatia MÍNIMA, e ela encolheu com o corte: `facing` ficou com a
+ * bengala (é ela que bate "à frente") e `wnT` com o nado. Sobrou identidade, posição, visão e o dispositivo.
+ */
+export interface SonarPlayer extends PlayerAudioOut {
+    readonly i: number;
+    readonly x: number;
+    readonly y: number;
+    readonly viz: string;
+    readonly audioSink?: string | null;
+    guideT?: number;
+}
+/**
+ * A SAÍDA DEDICADA de um jogador, e este módulo é o DONO dela: é aqui que os dois campos NASCEM
+ * (`new AC()` + `createGain()`, logo abaixo). Pelo ADR-0039 o dono declara onde o campo nasce, e o
+ * `core/entity` não os menciona — eles não são da entidade da engine, são rascunho que o áudio pendura
+ * no jogador.
+ *
+ * `_acOut` admite `null` porque `ui/settings-audio` escreve `null` nos dois ao trocar de dispositivo.
+ * Enquanto o `core/entity` dizia `unknown`, essa escrita passava sem que ninguém visse que o dono
+ * declarava `GainNode` sem nulo — as duas descrições discordavam e o `unknown` era o que as escondia.
+ */
+export interface PlayerAudioOut {
+    _ac?: SinkAC | null;
+    _acOut?: GainNode | null;
+}
+export interface PlayerCtxOut {
+    ac: AudioContext;
+    out: GainNode;
+}
+type VizDef = {
+    kind?: string;
+} | undefined;
+export interface SonarCtx {
+    /** Campo 1: a métrica. Função, porque um jogo com fases troca de topologia entre elas. */
+    topology: () => Topology;
+    /** Campo 5, metade "alvo": onde estão os alvos ainda válidos deste jogador. Vazio = nada a apontar. */
+    targetsOf: (playerIndex: number) => readonly Spot[];
+    /** Campo 3: como se chama o que está ali. `null` = sem nome, e o anúncio cai no genérico. */
+    nameAt: (at: Spot) => Speakable | null;
+    tonePan: (freq: number, dur: number, cat: string, pan?: number | null, vol?: number, type?: OscillatorType, pc?: PlayerCtxOut | null) => void;
+    srSay: (text: string) => void;
+    narrate: (text: string) => void;
+    VIZ_BY_KEY: Record<string, VizDef>;
+    getModoCego: () => boolean;
+    /** Largura LÓGICA da tela. É do console, não do gênero — por isso ctx, e não campo de contrato. */
+    LOGICAL_W: number;
+    getPlayers: () => SonarPlayer[];
+    getNumPlayers: () => number;
+    getAudioCtx: () => AudioContext | null;
+    getSoundOn: () => boolean;
+    getAudioCat: () => Record<string, {
+        on: boolean;
+    }> | null;
+}
+export interface AudioSonar {
+    playerCtx: (pl: SonarPlayer) => PlayerCtxOut | null;
+    panFor: (wx: number, pl: SonarPlayer) => number;
+    needsAudioCues: (pl: SonarPlayer) => boolean;
+    sonar: (pl: SonarPlayer) => void;
+    updateGuide: () => void;
+    readonly sonarCount: number;
+    readonly guideCount: number;
+}
+export declare function createAudioSonar(ctx: SonarCtx): AudioSonar;
+export {};

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

@@ -0,0 +1,173 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/audio-sonar — NAVEGAÇÃO SONORA, a metade de `audio-nav` que serve a QUALQUER gênero (item 19).
+//
+// ========================= O ACHADO 9, VIRADO CORTE =========================
+// O segundo consumidor registrou, e não contornou:
+//
+//     "O SONAR NÃO PODE SER USADO POR QUEM NÃO É PLATAFORMA… O ctx de `platform/audio-nav` pede 19 coisas, e
+//      seis delas são de plataforma pura — `tileAt`, `solidAt`, `BOX`, `TILE`, `getCoins`, `getCenario`. Um
+//      quiz teria de inventar tiles falsos, uma caixa de colisão falsa e um cenário falso para pedir 'aponte
+//      a alternativa mais próxima'. E o módulo é DOIS módulos com um nome só."
+//
+// Estes são os dois. Aqui fica o que navega por SOM: apontar o alvo mais perto, o beacon em laço, o pan pela
+// posição relativa e a pergunta "esta criança precisa de pista sonora?". Em `audio-nav` ficam a BENGALA e o
+// NADO CEGO, que leem tile, chão e caixa de colisão — plataforma, e sem disfarce.
+//
+// ========================= O QUE SUBSTITUIU AS SEIS COISAS DE PLATAFORMA =========================
+// Nenhuma delas atravessou. O sonar perguntava ao jogo por um array de moedas e filtrava `taken`/`owner`;
+// agora ele recebe o CONTRATO (ADR-0030):
+//
+//   · `getCoins()` + o filtro  →  `targetsOf(i)`, a metade "alvo" do campo 5. O jogo entrega os pontos que
+//     ainda contam para aquele jogador, e nunca diz o que eles são.
+//   · `TILE` (a régua de "perto")  →  `topology()` + `distance()`, a métrica declarada no campo 1. Numa
+//     plataforma são pixels sobre `unit`; numa grade, passos de rei; num quiz, diferença de índice.
+//   · `t('sr.nav.coin')` (o nome do alvo)  →  `nameAt(spot)`, campo 3. É o que faz o anúncio dizer "moeda",
+//     "pergunta" ou "caixa" sem a engine conhecer nenhum dos três.
+//
+// Sobrou UMA constante de mundo: `LOGICAL_W`, usada só pelo pan. Ela é da TELA e não do gênero — todo jogo
+// deste console tem 320 px de largura lógica —, e por isso entra por ctx em vez de virar campo de contrato.
+//
+// ========================= SEM I/O NO IMPORT =========================
+// Nada aqui toca `window` fora de `playerCtx`, que é chamada e não importada. Roda no project `node`.
+import { distance, bearing } from '../core/contract.js';
+import { t } from '../core/i18n.js';
+export function createAudioSonar(ctx) {
+    let _sonarCount = 0, _guideCount = 0;
+    /** AudioContext do jogador (para o `setSinkId` no dispositivo dele), ou null → contexto global. */
+    function playerCtx(pl) {
+        if (!pl || !pl.audioSink)
+            return null;
+        try {
+            if (!pl._ac) {
+                const AC = window.AudioContext || window.webkitAudioContext;
+                if (!AC)
+                    return null;
+                pl._ac = new AC();
+                pl._acOut = pl._ac.createGain();
+                pl._acOut.connect(pl._ac.destination);
+                if (pl._ac.setSinkId)
+                    pl._ac.setSinkId(pl.audioSink).catch(() => { });
+            }
+            if (pl._ac.state === 'suspended')
+                pl._ac.resume();
+            return { ac: pl._ac, out: pl._acOut };
+        }
+        catch (e) {
+            return null;
+        }
+    }
+    function panFor(wx, pl) {
+        return Math.max(-1, Math.min(1, (wx - pl.x) / (ctx.LOGICAL_W * 0.55)));
+    }
+    /** Visão comprometida? Guarda e guia só existem quando a resposta é sim (ou no modo cego). */
+    function needsAudioCues(pl) {
+        if (ctx.getModoCego())
+            return true;
+        const m = ctx.VIZ_BY_KEY[pl.viz];
+        return !!(m && (m.kind === 'blind' || m.kind === 'lowvision'));
+    }
+    /**
+     * O alvo mais perto deste jogador, na MÉTRICA DECLARADA — e `null` se não houver nenhum.
+     *
+     * Era um laço sobre `getCoins()` com `if (cn.taken || cn.owner !== pl.i) continue` e `Math.hypot`. As três
+     * coisas que ele sabia sobre o jogo (que alvos são moedas, que moedas têm dono, que distância é euclidiana
+     * em pixels) viraram uma pergunta ao contrato e uma chamada a `distance`.
+     */
+    /**
+     * O RUMO EM PALAVRAS, na língua de quem joga e no referencial que o JOGO declarou.
+     *
+     * ⚠️ O QUE ISTO SUBSTITUI ERA UM DEFEITO DE ACESSIBILIDADE, não um detalhe de estilo. O sonar calculava o
+     * lado à mão, de `x` cru, com zona morta de ±4:
+     *
+     *     alvo.at.x < pl.x - 4 ? 'left' : alvo.at.x > pl.x + 4 ? 'right' : 'ahead'
+     *
+     * Três palavras onde o contrato tem oito — e MISTURANDO REFERENCIAIS: *esquerda/direita* é relativo à TELA,
+     * *à frente* é relativo ao CORPO, e quem ouve não tem como saber de que origem cada uma fala. Pior: tudo o
+     * que estivesse acima ou abaixo da criança virava «à frente», que é justamente a informação que mais falta
+     * a quem não vê a tela — apagada por uma zona morta.
+     *
+     * ⚠️ E O REFERENCIAL É DO JOGO. Num tabuleiro diz-se «a nordeste»; numa plataforma 2D vista de lado, norte
+     * não quer dizer nada, e o que se diz é «às 2 horas».
+     */
+    function emPalavras(r) {
+        if (r.kind === 'none')
+            return t('sr.nav.here');
+        // Uma chave com `{h}` e não doze — mas a forma do singular é sua, porque «às 1 horas» não é português
+        // (nem «a las 1» é espanhol). Em inglês as duas coincidem, e coincidir não é motivo para não a ter.
+        if (r.kind === 'clock')
+            return r.hour === 1 ? t('sr.nav.clockOne') : t('sr.nav.clock', { h: r.hour });
+        return t('sr.nav.dir.' + r.heading);
+    }
+    function alvoMaisProximo(pl) {
+        const topo = ctx.topology();
+        const aqui = { x: pl.x, y: pl.y };
+        let melhor = null, bd = Infinity;
+        for (const alvo of ctx.targetsOf(pl.i)) {
+            const d = distance(topo, aqui, alvo);
+            if (d < bd) {
+                bd = d;
+                melhor = alvo;
+            }
+        }
+        return melhor ? { at: melhor, d: bd } : null;
+    }
+    /**
+     * "Perto" em PASSOS da métrica declarada, e não em pixels.
+     *
+     * Os limiares de 4 e 9 tiles do original viram 4 e 9 UNIDADES: numa plataforma com `unit = TILE` a conta é
+     * a mesma de antes, letra por letra; numa grade são quatro e nove casas; num quiz, quatro e nove itens de
+     * distância na lista. É a mesma frase para a criança em qualquer gênero, que é o ponto do contrato.
+     */
+    const chaveDeDistancia = (d) => d < 4 ? 'sr.nav.veryClose' : d < 9 ? 'sr.nav.close' : 'sr.nav.far';
+    function sonar(pl) {
+        _sonarCount++;
+        const pc = playerCtx(pl);
+        const alvo = alvoMaisProximo(pl);
+        // A chave era `sr.nav.noCoinNear` — "Nenhuma moeda por perto." Um sonar que não sabe mais o que é o alvo
+        // não pode dizer o nome dele no caso em que NÃO HÁ alvo nenhum: virou "Nada por perto.", que é verdade em
+        // qualquer gênero. Foi o gate de fixtures que cobrou, ao acusar a palavra dentro do teste novo.
+        if (!alvo) {
+            ctx.tonePan(300, 0.2, 'sonar', 0, 0.2, 'sine', pc);
+            ctx.srSay(t('sr.nav.noTargetNear'));
+            return;
+        }
+        const pan = panFor(alvo.at.x, pl), near = Math.max(0, 1 - alvo.d / 12);
+        ctx.tonePan(380 + 740 * near, 0.16, 'sonar', pan, 0.26, 'sine', pc); // mais perto = mais agudo
+        // O NOME vem do jogo (campo 3). Antes era `t('sr.nav.coin')` — a engine dizia "moeda" porque só conhecia
+        // moedas. O fallback existe para o jogo que declara alvo sem nome: melhor "alvo" do que uma chave crua.
+        const nome = ctx.nameAt(alvo.at);
+        const corpo = t('sr.nav.sonarFound', {
+            alvo: nome ? nome.text : t('sr.nav.target'),
+            lado: emPalavras(bearing(ctx.topology(), { x: pl.x, y: pl.y }, alvo.at)),
+            dist: t(chaveDeDistancia(alvo.d)),
+        });
+        const msg = (ctx.getNumPlayers() > 1 ? t('sr.player.prefix', { n: pl.i + 1 }) : '') + corpo;
+        ctx.srSay(msg);
+        ctx.narrate(msg);
+    }
+    /** Beacon automático por quadro: o sonar contínuo de quem não vê a tela. */
+    function updateGuide() {
+        const cat = ctx.getAudioCat();
+        if (!ctx.getAudioCtx() || !ctx.getSoundOn() || !cat || !cat.guide || !cat.guide.on)
+            return;
+        for (const pl of ctx.getPlayers()) {
+            if (!needsAudioCues(pl))
+                continue;
+            pl.guideT = (pl.guideT || 0) + 1;
+            if (pl.guideT < 48)
+                continue;
+            pl.guideT = 0; // pinga ~0,8s
+            const alvo = alvoMaisProximo(pl);
+            if (!alvo)
+                continue;
+            const pan = panFor(alvo.at.x, pl), near = Math.max(0, 1 - alvo.d / 14);
+            ctx.tonePan(300 + 380 * near, 0.12, 'guide', pan, 0.11, 'triangle', playerCtx(pl));
+            _guideCount++;
+        }
+    }
+    return {
+        playerCtx, panFor, needsAudioCues, sonar, updateGuide,
+        get sonarCount() { return _sonarCount; },
+        get guideCount() { return _guideCount; },
+    };
+}

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

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+type CatState = {
+    on: boolean;
+    vol: number;
+};
+type PlayerCtx = {
+    ac: AudioContext;
+    out: AudioNode;
+};
+type ACWithCache = AudioContext & {
+    _noiseBuf?: AudioBuffer;
+};
+export declare let soundOn: boolean;
+export declare function setSoundOn(v: boolean): void;
+export declare let volume: number;
+export declare function setVolume(v: number): void;
+export declare let audioCtx: AudioContext | null;
+export declare function ensureAC(): AudioContext | null;
+export declare let hearingLoss: boolean;
+export declare function audioOut(): GainNode | null;
+export declare function setHearingLossGraph(on: boolean): void;
+export declare function setMasterMuted(muted: boolean): void;
+export declare let audioCat: Record<string, CatState> | null;
+export declare function initAudioMixer(): void;
+export declare function catNode(cat: string): GainNode | null;
+export declare function setCatGain(cat: string): void;
+export declare function tone(freq: number, dur: number, type?: OscillatorType, when?: number, vol?: number): void;
+export declare function tonePan(freq: number, dur: number, cat: string, pan?: number | null, vol?: number, type?: OscillatorType, pc?: PlayerCtx | null): void;
+export declare let _footCount: number;
+export declare function noiseBuffer(ac: ACWithCache): AudioBuffer;
+export declare function noiseHit(mat: string, pan?: number | null, pc?: PlayerCtx | null): void;
+export {};

package/dist-pkg/platform/audio.js

@@ -0,0 +1,191 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/audio.ts — base do áudio: ciclo do AudioContext (ensureAC) + definições de SFX (dados). Módulo-folha.
+// O grafo (master/mixer), soundOn/volume e as sínteses (tone/noiseHit/tonePan/sfx) ainda ficam no game.js —
+// migram numa rodada dedicada (injeção de dependência). audioCtx é binding vivo; só ensureAC o (re)cria. (Fase 2)
+import { loadAudioCat, saveAudioCat } from './audio-mixer.js'; // mixer por categoria (dados + persistência)
+// Som mestre: liga/desliga + volume (0..1). Sessão-only (sem persistência). Bindings vivos: as sínteses
+// (tone/noiseHit/…) e a narração leem soundOn/volume; o botão/slider mestre do game.js escreve pelos setters.
+export let soundOn = true;
+export function setSoundOn(v) { soundOn = v; }
+export let volume = 0.6;
+export function setVolume(v) { volume = v; }
+export let audioCtx = null;
+export function ensureAC() {
+    if (!audioCtx) {
+        const AC = window.AudioContext || window.webkitAudioContext;
+        if (AC)
+            audioCtx = new AC();
+    }
+    if (audioCtx && audioCtx.state === 'suspended')
+        audioCtx.resume();
+    return audioCtx;
+}
+// ===== Nó MESTRE: master gain → (filtro de perda auditiva opcional) → destino. =====
+export let hearingLoss = false;
+let _masterGain = null, _hlChain = null;
+export function audioOut() { const ac = ensureAC(); if (!ac)
+    return null; if (!_masterGain) {
+    _masterGain = ac.createGain();
+    wireMaster();
+} return _masterGain; }
+function buildHearingChain(ac) {
+    const lp = ac.createBiquadFilter();
+    lp.type = 'lowpass';
+    lp.frequency.value = 1400;
+    lp.Q.value = 0.7; // agudos primeiro
+    const sp = ac.createScriptProcessor(512, 1, 1);
+    const TH = 0.06, RED = 0.12; // frame < limiar → ×0.12 (contrário de aparelho auditivo)
+    sp.onaudioprocess = (e) => { const inp = e.inputBuffer.getChannelData(0), out = e.outputBuffer.getChannelData(0); let s = 0; for (let i = 0; i < inp.length; i++)
+        s += inp[i] * inp[i]; const g = Math.sqrt(s / inp.length) < TH ? RED : 1; for (let i = 0; i < inp.length; i++)
+        out[i] = inp[i] * g; };
+    lp.connect(sp);
+    sp.connect(ac.destination);
+    return { input: lp };
+}
+function wireMaster() {
+    const ac = audioCtx;
+    if (!ac || !_masterGain)
+        return;
+    try {
+        _masterGain.disconnect();
+    }
+    catch (e) { /* noop */ }
+    if (hearingLoss) {
+        if (!_hlChain)
+            _hlChain = buildHearingChain(ac);
+        _masterGain.connect(_hlChain.input);
+    }
+    else
+        _masterGain.connect(ac.destination);
+}
+// Empatia de perda auditiva: liga/desliga o filtro no nó mestre. A persistência + srSay ficam no game.js.
+export function setHearingLossGraph(on) { hearingLoss = on; if (audioCtx) {
+    audioOut();
+    wireMaster();
+} }
+// Mute mestre (pausa/título silenciam tudo; volta ao jogar). Só age se o nó mestre já existe (não o cria à toa).
+export function setMasterMuted(muted) { if (!_masterGain || !audioCtx)
+    return; try {
+    _masterGain.gain.setTargetAtTime(muted ? 0 : 1, audioCtx.currentTime, 0.04);
+}
+catch (e) { /* noop */ } }
+// ===== Mixer por categoria: cada categoria tem seu gain (liga/desliga + volume), pendurado no nó mestre. =====
+// audioCat é a fonte viva do estado do mixer (mutada pela UI/calmMode no game.js — objeto, nunca reatribuído
+// APÓS init). NULL até initAudioMixer(): o import fica PURO (não lê localStorage). initAudioMixer é chamado no
+// boot do game.js — todos os leitores de audioCat (mixer/ambiente/narração) rodam depois. (Fase 2.25)
+export let audioCat = null;
+// Carrega o estado do mixer (defaults do audio-mixer.js + o que estiver salvo). I/O EXPLÍCITO, idempotente.
+export function initAudioMixer() { if (!audioCat)
+    audioCat = loadAudioCat(); }
+const _catNodes = {};
+export function catNode(cat) { const ac = ensureAC(); if (!ac || !audioCat)
+    return null; const out = audioOut(); if (!out)
+    return null; if (!_catNodes[cat]) {
+    const g = ac.createGain();
+    g.gain.value = audioCat[cat].on ? audioCat[cat].vol : 0;
+    g.connect(out);
+    _catNodes[cat] = g;
+} return _catNodes[cat]; }
+export function setCatGain(cat) { if (!audioCat)
+    return; const g = _catNodes[cat]; if (g && audioCtx)
+    g.gain.setTargetAtTime(audioCat[cat].on ? audioCat[cat].vol : 0, audioCtx.currentTime, 0.02); saveAudioCat(cat, audioCat[cat]); }
+// ===== Sínteses de oscilador (earcons/melodias). Leem soundOn/volume; roteiam pelo mixer→mestre. =====
+// pc = contexto de áudio por-jogador (opcional; o game.js o passa p/ rotear a pista ao dispositivo do jogador).
+export function tone(freq, dur, type, when, vol) {
+    if (!soundOn || volume <= 0)
+        return;
+    try {
+        const ac = ensureAC();
+        if (!ac)
+            return;
+        const o = ac.createOscillator(), g = ac.createGain(), t = ac.currentTime + (when || 0);
+        o.type = type || 'square';
+        o.frequency.setValueAtTime(freq, t);
+        g.gain.setValueAtTime(0.0001, t);
+        g.gain.exponentialRampToValueAtTime(Math.max(0.02, (vol || 0.22) * volume), t + 0.01);
+        g.gain.exponentialRampToValueAtTime(0.0001, t + dur);
+        o.connect(g).connect(catNode('earcons') || audioOut() || ac.destination);
+        o.start(t);
+        o.stop(t + dur + 0.02);
+    }
+    catch (e) { /* noop */ }
+}
+export function tonePan(freq, dur, cat, pan, vol, type, pc) {
+    if (!soundOn || volume <= 0)
+        return;
+    const ac = pc ? pc.ac : ensureAC();
+    if (!ac)
+        return;
+    try {
+        const o = ac.createOscillator(), g = ac.createGain(), t = ac.currentTime;
+        o.type = type || 'sine';
+        o.frequency.value = freq;
+        g.gain.setValueAtTime(0.0001, t);
+        g.gain.exponentialRampToValueAtTime(Math.max(0.02, (vol || 0.2) * volume), t + 0.01);
+        g.gain.exponentialRampToValueAtTime(0.0001, t + dur);
+        let node = g;
+        if (pan != null && ac.createStereoPanner) {
+            const p = ac.createStereoPanner();
+            p.pan.value = Math.max(-1, Math.min(1, pan));
+            g.connect(p);
+            node = p;
+        }
+        o.connect(g);
+        node.connect(pc ? pc.out : (catNode(cat) || audioOut() || ac.destination));
+        o.start(t);
+        o.stop(t + dur + 0.02);
+    }
+    catch (e) { /* noop */ }
+}
+// ===== Synth de RUÍDO (passos por material, bengala). noiseBuffer cacheia por-contexto (suporta AC por jogador). =====
+export let _footCount = 0; // contador de passos/pancadas (estatística de a11y; o __incl do game.js lê via getter)
+export function noiseBuffer(ac) { if (ac._noiseBuf && ac._noiseBuf.length === ((ac.sampleRate * 0.2) | 0))
+    return ac._noiseBuf; const n = (ac.sampleRate * 0.2) | 0, b = ac.createBuffer(1, n, ac.sampleRate), d = b.getChannelData(0); for (let i = 0; i < n; i++)
+    d[i] = Math.random() * 2 - 1; return ac._noiseBuf = b; }
+const FOOT = { grama: { f: 'highpass', hz: 2000, d: 0.09, v: 0.10 }, piso: { f: 'bandpass', hz: 1200, d: 0.06, v: 0.15 }, pedra: { f: 'highpass', hz: 1600, d: 0.05, v: 0.19 },
+    areia: { f: 'lowpass', hz: 650, d: 0.13, v: 0.10 }, madeira: { f: 'bandpass', hz: 480, d: 0.08, v: 0.15 }, ferro: { f: 'bandpass', hz: 2600, d: 0.12, v: 0.16 }, parede: { f: 'highpass', hz: 3200, d: 0.10, v: 0.08 },
+    terra: { f: 'lowpass', hz: 520, d: 0.11, v: 0.12 }, agua: { f: 'lowpass', hz: 330, d: 0.15, v: 0.13 } };
+export function noiseHit(mat, pan, pc) {
+    if (!soundOn || volume <= 0)
+        return;
+    const ac = pc ? pc.ac : ensureAC();
+    if (!ac)
+        return;
+    const f = FOOT[mat] || FOOT.piso;
+    try {
+        const src = ac.createBufferSource();
+        src.buffer = noiseBuffer(ac);
+        const bq = ac.createBiquadFilter();
+        bq.type = f.f;
+        bq.frequency.value = f.hz;
+        bq.Q.value = 1.2;
+        const g = ac.createGain(), t = ac.currentTime;
+        g.gain.setValueAtTime(0.0001, t);
+        g.gain.exponentialRampToValueAtTime(Math.max(0.02, f.v * volume), t + 0.006);
+        g.gain.exponentialRampToValueAtTime(0.0001, t + f.d);
+        let node = g;
+        if (pan != null && ac.createStereoPanner) {
+            const p = ac.createStereoPanner();
+            p.pan.value = Math.max(-1, Math.min(1, pan));
+            g.connect(p);
+            node = p;
+        }
+        src.connect(bq).connect(g);
+        node.connect(pc ? pc.out : (catNode('interact') || audioOut() || ac.destination));
+        src.start(t);
+        src.stop(t + f.d + 0.03);
+        _footCount++;
+    }
+    catch (e) { /* noop */ }
+}
+/* A TABELA DE EARCONS SAIU daqui em 2026-08-25 (item 19) — está em `game/earcons`.
+ *
+ * De dez earcons, sete eram deste jogo: `coin`/`key`/`gate`/`power` são objetos deste mundo e
+ * `correct`/`wrong`/`place` são eventos da atividade. O gate acusava só a linha do `coin`, porque é a única
+ * com palavra que o casador conhece — e a linha acusada era a menos interessante das dez.
+ *
+ * As legendas eram pt-BR CRU (`'🔊 Coletou'`, `'🔊 Portão abriu'`): nove frases dentro de um módulo de
+ * plataforma, que o gate de i18n do `main.js` não alcança. Viraram CHAVES, e quem exibe resolve.
+ *
+ * O que ficou aqui é a SÍNTESE — oscilador, envelope, ruído, roteamento por categoria —, que serve a
+ * qualquer jogo. O que é 880 Hz de triangular por 0,14 s ao pegar uma moeda, não. */

package/dist-pkg/platform/interruptible-speech.d.ts

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** O que o chamador precisa fornecer. Nada aqui conhece PIPER, Web Audio ou o navegador. */
+export interface MotorDeFala<Audio, Fonte> {
+    /** Texto → áudio. ASSÍNCRONO de propósito: é onde a síntese neural gasta o tempo dela. */
+    sintetizar(texto: string): Promise<Audio>;
+    /** Começa a tocar e devolve a fonte, para que ela possa ser parada. `null` = não deu para tocar agora. */
+    tocar(audio: Audio, aoTerminar: () => void): Fonte | null;
+    /** Cala a fonte. Chamado com o que `tocar` devolveu, e nunca com `null`. */
+    parar(fonte: Fonte): void;
+}
+export interface FalaInterrompivel {
+    /** Fala `texto`, CALANDO na hora o que estiver falando. Não enfileira: o último pedido é o que vale. */
+    falar(texto: string): void;
+    /** Cala e esquece. Usado ao fechar um menu ou ao desligar a narração. */
+    calar(): void;
+    /** Está tocando alguma coisa? Só para teste e depuração — a política não depende disto. */
+    falando(): boolean;
+}
+export declare function criarFalaInterrompivel<Audio, Fonte>(motor: MotorDeFala<Audio, Fonte>): FalaInterrompivel;