@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/input/origem-sintetica.js

@@ -1,60 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-// input/origem-sintetica.ts — QUEM DESPACHOU ESTA TECLA, quando não foi um dedo num teclado (ADR-0109).
-//
-// ========================= O PONTO DIFÍCIL DA ARESTA, E ELE ESTAVA NOMEADO =========================
-// O crivo `tests/origem-da-tecla` carrega esta frase na entrada do `input/keydown` desde que o
-// estrangulamento começou: «a webcam despacha `KeyboardEvent` SINTÉTICO, entra pelo `keydown` e seria
-// carimbada `teclado` — a erasão a voltar pela porta da frente». O `ui/webcam` constrói um `KeyboardEvent` e
-// despacha-o na janela (`ui/webcam.ts`, `eyeSet`), e do lado de lá ele é indistinguível de uma tecla premida.
-//
-// `isTrusted` distingue PREMIDA de DESPACHADA — é a única propriedade que um script não consegue forjar — mas
-// não diz QUAL transporte assistido despachou. Isso tem de chegar DECLARADO, e é o que este módulo é.
-//
-// ⚠️ POR QUE O CARIMBO VIAJA NO EVENTO, e não num «qual é a fonte sintética agora?» injectado. A resposta
-// injectada é um estado GLOBAL, e a entrada não é global: uma criança que joga por olhar e tem um adulto a
-// carregar numa tecla ao lado produz as duas arestas no mesmo instante, e o estado global carimbaria as duas
-// como olhar. O evento não se confunde consigo próprio — a origem anda com a aresta a que pertence, que é a
-// mesma razão por que o `origemDaTecla` é um mapa por CÓDIGO e não um campo só.
-//
-// 📌 E é aditivo por construção: um evento sem carimbo continua a funcionar. Foi isso que permitiu migrar os
-// escritores um a um sem nenhum commit vermelho pelo meio.
-import { ehTransporte } from './transporte-em-uso.js';
-/**
- * A propriedade pendurada no evento.
- *
- * 📌 Prefixada e feia de propósito: é um expando num objecto que não é nosso, e um nome curto («origem»)
- * podia colidir com o de outra biblioteca sem que nada o dissesse.
- */
-export const CHAVE_DE_ORIGEM = '__vpOrigem';
-/**
- * DECLARA que este evento veio daquele aparelho. Devolve o próprio evento, para o despacho ficar numa linha.
- *
- * ⚠️ Carimba-se ANTES de despachar. Depois de `dispatchEvent` os ouvintes já correram, e o carimbo chegaria
- * a um evento que ninguém mais vai ler.
- */
-export function carimbarOrigem(ev, origem) {
-    ev[CHAVE_DE_ORIGEM] = origem;
-    return ev;
-}
-/**
- * QUEM PRODUZIU ESTE EVENTO? `undefined` quando não se sabe.
- *
- * A regra inteira, em três linhas e por esta ordem:
- *
- *   1. **Carimbo válido ganha.** Uma declaração explícita vence sempre uma inferência — inverter isto faria
- *      um evento REAL que alguém reatribuiu (um pedal, um interruptor de sopro que emite teclas de verdade)
- *      ser lido como teclado, apagando exactamente a informação que quem carimbou se deu ao trabalho de pôr.
- *   2. **Sem carimbo mas de confiança → `'teclado'`.** É o que `isTrusted` significa: o navegador viu a
- *      pessoa carregar. É a única inferência que este módulo faz, e fá-la sobre a propriedade que não se forja.
- *   3. **Sem carimbo e sem confiança → `undefined`.** Um evento sintético que ninguém assinou. Depois desta
- *      migração nada nesta engine produz um; quem o produz é código de fora, e código de fora não declarou.
- *      ⚠️ Devolver `'teclado'` aqui seria a erasão a voltar por outra porta, que é o defeito que o ADR-0109
- *      inteiro existe para fechar — e seria pior do que a erasão original, porque teria a forma de uma
- *      resposta.
- */
-export function origemDoEvento(ev) {
-    const declarada = ev[CHAVE_DE_ORIGEM];
-    if (ehTransporte(declarada))
-        return declarada;
-    return ev.isTrusted ? 'teclado' : undefined;
-}

package/dist-pkg/input/transporte-em-uso.d.ts

@@ -1,101 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-/** Os aparelhos por onde uma criança joga. Fechado: um transporte novo tem de decidir a sua regra aqui. */
-export type Transporte = 'teclado' | 'gamepad' | 'toque' | 'olhos' | 'rosto' | 'gestos' | 'fala';
-/**
- * A UNIÃO COMO VALOR, porque há um sítio onde ela tem de ser verificada em runtime.
- *
- * ⚠️ EXISTE POR CAUSA DE UMA FRONTEIRA, e é a única razão que a justifica: o `input/origem-sintetica` lê o
- * transporte de um EXPANDO pendurado num `KeyboardEvent` — um objecto que este código não construiu e que
- * qualquer script da página pode construir. Um valor que atravessa essa fronteira não é um `Transporte` por
- * o TypeScript o dizer; é uma `string` até alguém a conferir. Sem lista, `'olho'` entrava no mapa de origens
- * como transporte fantasma, e nada o diria.
- *
- * 📌 Não é o defeito da lista-ao-lado-da-união que este repositório já desfez três vezes (o `RM_KEYS`, os
- * rótulos de movimento reduzido, as chaves de armazenamento), porque a guarda abaixo é do COMPILADOR: as duas
- * não podem divergir. Uma cópia que não pode divergir é uma projecção, não uma segunda fonte.
- */
-export declare const TRANSPORTES: readonly ["teclado", "gamepad", "toque", "olhos", "rosto", "gestos", "fala"];
-/**
- * Isto que veio de fora é mesmo um transporte?
- *
- * ⚠️ A pergunta não é de segurança — os scripts desta página são todos da casa, e quem quisesse mentir usaria
- * um valor VÁLIDO. É de correcção: impede que um carimbo errado ou ausente vire uma entrada silenciosa no
- * `origemDaTecla`, que é a estrutura de que a alternância inteira depende.
- */
-export declare function ehTransporte(v: unknown): v is Transporte;
-/**
- * OS QUATRO QUE EXIGEM HABILITAÇÃO EXPLÍCITA e, uma vez habilitados, mandam em todos (regra 4).
- *
- * ⚠️ É a mesma lista do `UM_COMANDO_DE_CADA_VEZ` do `input/latch-scope`, e a coincidência não é acaso: são
- * os transportes de quem NÃO CONSEGUE SEGURAR NADA. O que o ADR-0109 acrescenta é que eles não ligam a
- * alternância só para si — ligam-na para o resto, porque quem usa a webcam pode também tocar na tela, e uma
- * alternância que se desliga ao mudar de aparelho é uma armadilha para exactamente essa pessoa.
- */
-export declare const EXIGEM_HABILITACAO: ReadonlySet<Transporte>;
-/** O transporte que liga a alternância por si só, sem prioridade nenhuma envolvida (regra 2). */
-export declare const COM_ALTERNANCIA_PROPRIA: ReadonlySet<Transporte>;
-export interface EstadoDaEntrada {
-    /** Qual aparelho está a ser usado AGORA por este jogador. */
-    readonly emUso: Transporte;
-    /**
-     * A câmera/microfone foi habilitada? ⚠️ Uma vez `true`, NUNCA volta a `false` por uma aresta — só uma
-     * decisão explícita a desliga, e o ADR-0109 §4 diz que a criança não tem essa decisão. Ver `desabilitar`.
-     */
-    readonly assistidaLigada: boolean;
-}
-/**
- * O ESTADO INICIAL: teclado, sem alternância.
- *
- * ⚠️ A regra 1 diz «controle E teclado, ambos sem alternância», e é por isso que o padrão pode nomear um só
- * sem mentir: entre os dois a resposta à única pergunta que este módulo faz — há alternância? — é a MESMA.
- * O `emUso` só passa a distingui-los quando alguém quiser MOSTRAR o aparelho corrente, que é outra questão
- * e o ADR-0109 deixa-a explicitamente por decidir.
- */
-export declare const PADRAO: EstadoDaEntrada;
-/**
- * HÁ ALTERNÂNCIA AGORA? — ⚠️ **NÃO PERGUNTE ISTO A ESTA FUNÇÃO.** Ver o parágrafo abaixo.
- *
- * ⚠️ A prioridade da assistida vem PRIMEIRO, e a ordem é a regra 4 inteira: enquanto ela estiver ligada,
- * nenhum outro aparelho a desliga — nem o teclado, que noutro caso a desligaria. Inverter estas duas linhas
- * é o defeito que trancaria uma criança fora do próprio jogo, e é silencioso.
- *
- * @deprecated 🔴 **ESTA FUNÇÃO IMPLEMENTA O MODELO QUE O ADR-0113 SUPERSEDEU**, e fica exportada por ser
- * superfície publicada (`./input/*.js`) e por o registo ter valor histórico — não por ser a resposta.
- *
- * O ADR-0109 decidia a alternância **só pelo aparelho**: assistida ligada → sim; toque → sim; todo o resto
- * → não. O ADR-0113 retirou essa cláusula, com a razão do Dev: a alternância é um **caps-lock guardado com
- * o mapeamento do controle**, e o valor que a criança gravou vale.
- *
- * 🔴 A DIVERGÊNCIA TEM UMA CRIANÇA CONCRETA, e é a que motivou o registo: quem tem dificuldade motora, joga
- * no TECLADO e gravou a alternância ligada. Esta função devolve `false` para ela — `teclado` não está em
- * `COM_ALTERNANCIA_PROPRIA` — e é exactamente o controle que lhe seria retirado. O `latch-scope.alternanciaDe`
- * devolve `true`, porque lê o que ela gravou.
- *
- * ⚠️ E A CLÁUSULA DO TOQUE TAMBÉM CAIU: sob o ADR-0113 o toque é um transporte como os outros — o valor dele
- * é escolha e fica guardado. Só olhos, rosto, gestos e fala podem recusar-se a DESLIGAR, e essa metade vive
- * em `latch-scope.alternanciaSempreLigada`, com um conjunto diferente deste e a responder a outra pergunta.
- *
- * **A resposta certa é `latch-scope.alternanciaDe(estado.emUso, leitura)`.** O papel que sobra a este
- * módulo é o que o nome dele diz: QUAL transporte está em uso — que é o que alimenta aquele primeiro
- * argumento. `tests/alternancia-por-transporte.node.test.js` afirma que esta função continua sem consumidor.
- */
-export declare function alternanciaAgora(estado: EstadoDaEntrada): boolean;
-/**
- * UMA ARESTA CHEGOU, com a sua origem. Devolve o estado NOVO.
- *
- * ⚠️ Uma aresta de um transporte assistido NÃO o habilita. Habilitar é um acto explícito (regra 4: «precisam
- * ser habilitados»), e deixar uma aresta fazê-lo significaria que um falso positivo da webcam — uma sombra,
- * um segundo rosto a passar — trancava a alternância de toda a gente sem ninguém ter pedido.
- */
-export declare function aposAresta(estado: EstadoDaEntrada, origem: Transporte): EstadoDaEntrada;
-/** A criança (ou quem a acompanha) habilitou câmera/microfone. Daqui em diante a alternância é lei. */
-export declare function habilitarAssistida(estado: EstadoDaEntrada): EstadoDaEntrada;
-/**
- * DESABILITAR a assistida. Existe, e o ADR-0109 diz de quem é: NÃO é da criança durante a partida.
- *
- * ⚠️ Fica exportada porque desligar a câmera tem de ser possível em algum lugar — trocar de utilizador,
- * fechar o jogo, um adulto a reconfigurar. O que o §4 proíbe é oferecê-la como um botão ao lado do jogo.
- * Uma função que existe e não é oferecida é diferente de uma função que não existe: a primeira diz onde a
- * decisão mora.
- */
-export declare function desabilitarAssistida(estado: EstadoDaEntrada): EstadoDaEntrada;

package/dist-pkg/input/transporte-em-uso.js

@@ -1,130 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-// input/transporte-em-uso — A ALTERNÂNCIA SEGUE O APARELHO EM USO (ADR-0109), na metade pura.
-//
-// ========================= O QUE ESTE MÓDULO É =========================
-// O autómato das quatro regras do ADR-0109 §1, sem DOM, sem armazenamento e sem eventos. Recebe ARESTAS com
-// origem e devolve estado; quem pergunta «há alternância agora?» pergunta ao estado.
-//
-//   1. Por padrão, controle e teclado, ambos SEM alternância.
-//   2. Clique de mouse ou toque na tela → controles de tela COM alternância.
-//   3. Apertar tecla devolve o teclado SEM alternância; usar o controle faz o mesmo.
-//   4. Câmera e microfone precisam ser habilitados; habilitados, ligam a alternância em TODOS os outros
-//      controles, SEM possibilidade de desligar. São prioridade.
-//
-// ⚠️ POR QUE ISTO É UM AUTÓMATO E NÃO UM VALOR GUARDADO — e é o que o ADR-0109 supersede do ADR-0104 §C. A
-// alternância era uma ESCOLHA guardada por transporte, e a issue #114 mediu que a fiação dela não era
-// escrevível: a origem da aresta é apagada à porta (`input/state.keys` é `Set<string>` de CÓDIGOS, e o toque
-// e a webcam escrevem lá dentro). O Dev decidiu o COMPORTAMENTO, e o comportamento escolhe o mecanismo.
-//
-// ⚠️ E A REGRA 3 É A RAZÃO DE PRECISAR DE DUAS COISAS, não de uma. «Apertar uma tecla devolve o teclado sem
-// alternância» são DOIS factos: um EVENTO cuja origem tem de ser conhecida, e um MODO que persiste até à
-// troca seguinte. Uma aresta não guarda estado; um modo guardado não detecta a própria troca. Nenhuma metade
-// exprime a regra; juntas exprimem. Este ficheiro é a segunda metade — o MODO.
-//
-// 📌 A imagem do Dev, mantida porque diz a coisa: é um CAPS-LOCK NUM TECLADO COM MEMÓRIA. Modo e não estado
-// momentâneo; lembrado por aparelho; trocar de aparelho não apaga o que o outro lembra.
-/**
- * A UNIÃO COMO VALOR, porque há um sítio onde ela tem de ser verificada em runtime.
- *
- * ⚠️ EXISTE POR CAUSA DE UMA FRONTEIRA, e é a única razão que a justifica: o `input/origem-sintetica` lê o
- * transporte de um EXPANDO pendurado num `KeyboardEvent` — um objecto que este código não construiu e que
- * qualquer script da página pode construir. Um valor que atravessa essa fronteira não é um `Transporte` por
- * o TypeScript o dizer; é uma `string` até alguém a conferir. Sem lista, `'olho'` entrava no mapa de origens
- * como transporte fantasma, e nada o diria.
- *
- * 📌 Não é o defeito da lista-ao-lado-da-união que este repositório já desfez três vezes (o `RM_KEYS`, os
- * rótulos de movimento reduzido, as chaves de armazenamento), porque a guarda abaixo é do COMPILADOR: as duas
- * não podem divergir. Uma cópia que não pode divergir é uma projecção, não uma segunda fonte.
- */
-export const TRANSPORTES = ['teclado', 'gamepad', 'toque', 'olhos', 'rosto', 'gestos', 'fala'];
-const _COBRE_OS_TRANSPORTES = true;
-void _COBRE_OS_TRANSPORTES;
-/**
- * Isto que veio de fora é mesmo um transporte?
- *
- * ⚠️ A pergunta não é de segurança — os scripts desta página são todos da casa, e quem quisesse mentir usaria
- * um valor VÁLIDO. É de correcção: impede que um carimbo errado ou ausente vire uma entrada silenciosa no
- * `origemDaTecla`, que é a estrutura de que a alternância inteira depende.
- */
-export function ehTransporte(v) {
-    return typeof v === 'string' && TRANSPORTES.includes(v);
-}
-/**
- * OS QUATRO QUE EXIGEM HABILITAÇÃO EXPLÍCITA e, uma vez habilitados, mandam em todos (regra 4).
- *
- * ⚠️ É a mesma lista do `UM_COMANDO_DE_CADA_VEZ` do `input/latch-scope`, e a coincidência não é acaso: são
- * os transportes de quem NÃO CONSEGUE SEGURAR NADA. O que o ADR-0109 acrescenta é que eles não ligam a
- * alternância só para si — ligam-na para o resto, porque quem usa a webcam pode também tocar na tela, e uma
- * alternância que se desliga ao mudar de aparelho é uma armadilha para exactamente essa pessoa.
- */
-export const EXIGEM_HABILITACAO = new Set(['olhos', 'rosto', 'gestos', 'fala']);
-/** O transporte que liga a alternância por si só, sem prioridade nenhuma envolvida (regra 2). */
-export const COM_ALTERNANCIA_PROPRIA = new Set(['toque']);
-/**
- * O ESTADO INICIAL: teclado, sem alternância.
- *
- * ⚠️ A regra 1 diz «controle E teclado, ambos sem alternância», e é por isso que o padrão pode nomear um só
- * sem mentir: entre os dois a resposta à única pergunta que este módulo faz — há alternância? — é a MESMA.
- * O `emUso` só passa a distingui-los quando alguém quiser MOSTRAR o aparelho corrente, que é outra questão
- * e o ADR-0109 deixa-a explicitamente por decidir.
- */
-export const PADRAO = Object.freeze({ emUso: 'teclado', assistidaLigada: false });
-/**
- * HÁ ALTERNÂNCIA AGORA? — ⚠️ **NÃO PERGUNTE ISTO A ESTA FUNÇÃO.** Ver o parágrafo abaixo.
- *
- * ⚠️ A prioridade da assistida vem PRIMEIRO, e a ordem é a regra 4 inteira: enquanto ela estiver ligada,
- * nenhum outro aparelho a desliga — nem o teclado, que noutro caso a desligaria. Inverter estas duas linhas
- * é o defeito que trancaria uma criança fora do próprio jogo, e é silencioso.
- *
- * @deprecated 🔴 **ESTA FUNÇÃO IMPLEMENTA O MODELO QUE O ADR-0113 SUPERSEDEU**, e fica exportada por ser
- * superfície publicada (`./input/*.js`) e por o registo ter valor histórico — não por ser a resposta.
- *
- * O ADR-0109 decidia a alternância **só pelo aparelho**: assistida ligada → sim; toque → sim; todo o resto
- * → não. O ADR-0113 retirou essa cláusula, com a razão do Dev: a alternância é um **caps-lock guardado com
- * o mapeamento do controle**, e o valor que a criança gravou vale.
- *
- * 🔴 A DIVERGÊNCIA TEM UMA CRIANÇA CONCRETA, e é a que motivou o registo: quem tem dificuldade motora, joga
- * no TECLADO e gravou a alternância ligada. Esta função devolve `false` para ela — `teclado` não está em
- * `COM_ALTERNANCIA_PROPRIA` — e é exactamente o controle que lhe seria retirado. O `latch-scope.alternanciaDe`
- * devolve `true`, porque lê o que ela gravou.
- *
- * ⚠️ E A CLÁUSULA DO TOQUE TAMBÉM CAIU: sob o ADR-0113 o toque é um transporte como os outros — o valor dele
- * é escolha e fica guardado. Só olhos, rosto, gestos e fala podem recusar-se a DESLIGAR, e essa metade vive
- * em `latch-scope.alternanciaSempreLigada`, com um conjunto diferente deste e a responder a outra pergunta.
- *
- * **A resposta certa é `latch-scope.alternanciaDe(estado.emUso, leitura)`.** O papel que sobra a este
- * módulo é o que o nome dele diz: QUAL transporte está em uso — que é o que alimenta aquele primeiro
- * argumento. `tests/alternancia-por-transporte.node.test.js` afirma que esta função continua sem consumidor.
- */
-export function alternanciaAgora(estado) {
-    if (estado.assistidaLigada)
-        return true;
-    return COM_ALTERNANCIA_PROPRIA.has(estado.emUso);
-}
-/**
- * UMA ARESTA CHEGOU, com a sua origem. Devolve o estado NOVO.
- *
- * ⚠️ Uma aresta de um transporte assistido NÃO o habilita. Habilitar é um acto explícito (regra 4: «precisam
- * ser habilitados»), e deixar uma aresta fazê-lo significaria que um falso positivo da webcam — uma sombra,
- * um segundo rosto a passar — trancava a alternância de toda a gente sem ninguém ter pedido.
- */
-export function aposAresta(estado, origem) {
-    if (estado.emUso === origem)
-        return estado; // sem mudança: devolve o MESMO objecto, não uma cópia
-    return { emUso: origem, assistidaLigada: estado.assistidaLigada };
-}
-/** A criança (ou quem a acompanha) habilitou câmera/microfone. Daqui em diante a alternância é lei. */
-export function habilitarAssistida(estado) {
-    return estado.assistidaLigada ? estado : { emUso: estado.emUso, assistidaLigada: true };
-}
-/**
- * DESABILITAR a assistida. Existe, e o ADR-0109 diz de quem é: NÃO é da criança durante a partida.
- *
- * ⚠️ Fica exportada porque desligar a câmera tem de ser possível em algum lugar — trocar de utilizador,
- * fechar o jogo, um adulto a reconfigurar. O que o §4 proíbe é oferecê-la como um botão ao lado do jogo.
- * Uma função que existe e não é oferecida é diferente de uma função que não existe: a primeira diz onde a
- * decisão mora.
- */
-export function desabilitarAssistida(estado) {
-    return estado.assistidaLigada ? { emUso: estado.emUso, assistidaLigada: false } : estado;
-}

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

@@ -1,51 +0,0 @@
-// 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' | '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

@@ -1,99 +0,0 @@
-// 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/guide-intensity.d.ts

@@ -1,40 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-/** O que o guia soa, para uma dada distância. */
-export interface Intensidade {
-    /** Corte do passa-baixo, em hertz. Grave e abafado longe; aberto e brilhante perto. */
-    readonly corte: number;
-    /** Fator sobre o volume da categoria `guide`, entre `VOL_LONGE` e 1. NUNCA zero. */
-    readonly volume: number;
-}
-/**
- * A partir de quantos passos o guia deixa de escurecer mais.
- *
- * Doze, e o número não é novo: o `chaveDeDistancia` do sonar corta «muito perto» em 4 passos e «perto» em 9,
- * e o `PAN_PACES` satura o estéreo em 11. O guia satura logo depois — a informação fina serve para quem já
- * está a chegar, e mais longe do que isso «longe» basta.
- */
-export declare const PASSOS_ATE_O_FUNDO = 12;
-/** O corte no fundo da escala: abafado, presente, sem ser um som de alarme. */
-export declare const CORTE_LONGE = 320;
-/** O corte no alvo: aberto. Acima disto o timbre passa a sibilar, e sibilar chama atenção como um bipe. */
-export declare const CORTE_PERTO = 3200;
-/**
- * O fator de volume mais baixo.
- *
- * ⚠️ NUNCA ZERO, E É A ASSERÇÃO MAIS IMPORTANTE DESTE FICHEIRO. Se o guia emudecesse ao longe, «longe» ficaria
- * indistinguível de «não há alvo» — e a criança que depende dele concluiria que não há nada para achar,
- * exatamente quando há e está distante. Silêncio é uma afirmação, e aqui seria uma afirmação falsa.
- */
-export declare const VOL_LONGE = 0.55;
-/**
- * A intensidade para `passos` de distância ao longo da rota.
- *
- * ⚠️ A INTERPOLAÇÃO DO CORTE É EXPONENCIAL, e não linear, pelo mesmo motivo do earcon da #124: o ouvido
- * percebe altura e brilho em RAZÃO, não em diferença. Uma rampa linear de 320 a 3200 abriria quase tudo no
- * primeiro terço do caminho e depois pareceria parada — a criança sentiria que chegou quando ainda faltava
- * metade.
- *
- * O volume interpola LINEARMENTE, e a assimetria é deliberada: ele é o eixo secundário, e uma curva também
- * exponencial ali faria os dois acelerarem no mesmo ponto, que é o oposto de ter dois eixos.
- */
-export declare function intensidadeDoGuia(passos: number): Intensidade;

package/dist-pkg/platform/guide-intensity.js

@@ -1,73 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-// platform/guide-intensity — QUÃO PERTO SOA, sem bipe (#84 item 2).
-//
-// ========================= O QUE ISTO SUBSTITUI =========================
-// O guia tocava um `triangle` de 0,12 s a cada 0,8 s, PARA SEMPRE, sem depender de movimento nem de nada ter
-// mudado. O veredicto do Dev: «um ping é a pior escolha possível, tenebroso para quem tem TEA». Não era a
-// frequência que estava errada — era o bipe. Reduzi-lo a «só andando» deixaria a mesma coisa a doer menos
-// vezes.
-//
-// O que entra é uma presença CONTÍNUA que fica mais intensa conforme a criança se aproxima, ao longo da rota
-// mapeada (`core/route`). Nada dispara; a coisa apenas fica mais presente.
-//
-// ========================= O EIXO É O BRILHO, E A DECISÃO É DO DEV =========================
-// Quatro eixos foram postos na mesa — volume, brilho (corte de filtro), camadas e andamento — e a escolha foi
-// **brilho como principal, com uma parcela pequena de volume como secundário**. As razões, para quem reabrir:
-//
-//   · VOLUME SOZINHO colide com o cursor do mixer: a criança que baixou a categoria `guide` perderia o sinal
-//     inteiro, e variação de volume é a mais cansativa das quatro.
-//   · ANDAMENTO lê-se como PRESSA, que é o oposto do que o modo TEA existe para proteger.
-//   · CAMADAS precisa de material composto, e esta engine sintetiza.
-//   · BRILHO é contínuo, sai de um `BiquadFilter` que o Web Audio já tem, e não disputa o cursor.
-//
-// ⚠️ E A PARCELA DE VOLUME NÃO É ENFEITE: para uma criança com perda auditiva o brilho pode cair exatamente na
-// banda que ela não alcança. Dois eixos redundantes significam que nenhum deles sozinho decide.
-//
-// ========================= O QUE ESTE MÓDULO NÃO FAZ =========================
-// Não toca nada. Devolve dois números a partir de UM: quantos passos faltam ao longo da rota. Quem monta o
-// grafo é o `platform/audio-sonar`, e quem calcula a rota é o `core/route` — que já sabe contornar parede, e é
-// isso que torna a intensidade honesta: ela cresce com a distância que a criança REALMENTE vai andar.
-//
-// Módulo-folha: não importa nada.
-/**
- * A partir de quantos passos o guia deixa de escurecer mais.
- *
- * Doze, e o número não é novo: o `chaveDeDistancia` do sonar corta «muito perto» em 4 passos e «perto» em 9,
- * e o `PAN_PACES` satura o estéreo em 11. O guia satura logo depois — a informação fina serve para quem já
- * está a chegar, e mais longe do que isso «longe» basta.
- */
-export const PASSOS_ATE_O_FUNDO = 12;
-/** O corte no fundo da escala: abafado, presente, sem ser um som de alarme. */
-export const CORTE_LONGE = 320;
-/** O corte no alvo: aberto. Acima disto o timbre passa a sibilar, e sibilar chama atenção como um bipe. */
-export const CORTE_PERTO = 3200;
-/**
- * O fator de volume mais baixo.
- *
- * ⚠️ NUNCA ZERO, E É A ASSERÇÃO MAIS IMPORTANTE DESTE FICHEIRO. Se o guia emudecesse ao longe, «longe» ficaria
- * indistinguível de «não há alvo» — e a criança que depende dele concluiria que não há nada para achar,
- * exatamente quando há e está distante. Silêncio é uma afirmação, e aqui seria uma afirmação falsa.
- */
-export const VOL_LONGE = 0.55;
-/**
- * A intensidade para `passos` de distância ao longo da rota.
- *
- * ⚠️ A INTERPOLAÇÃO DO CORTE É EXPONENCIAL, e não linear, pelo mesmo motivo do earcon da #124: o ouvido
- * percebe altura e brilho em RAZÃO, não em diferença. Uma rampa linear de 320 a 3200 abriria quase tudo no
- * primeiro terço do caminho e depois pareceria parada — a criança sentiria que chegou quando ainda faltava
- * metade.
- *
- * O volume interpola LINEARMENTE, e a assimetria é deliberada: ele é o eixo secundário, e uma curva também
- * exponencial ali faria os dois acelerarem no mesmo ponto, que é o oposto de ter dois eixos.
- */
-export function intensidadeDoGuia(passos) {
-    if (!Number.isFinite(passos) || passos < 0)
-        return { corte: CORTE_LONGE, volume: VOL_LONGE };
-    // 0 = em cima do alvo; 1 = no fundo da escala ou além.
-    const longe = Math.min(1, passos / PASSOS_ATE_O_FUNDO);
-    const perto = 1 - longe;
-    return {
-        corte: CORTE_LONGE * Math.pow(CORTE_PERTO / CORTE_LONGE, perto),
-        volume: VOL_LONGE + (1 - VOL_LONGE) * perto,
-    };
-}

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

@@ -1,14 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-/** Uma coisa pesada que a engine promete e que não cabe no pacote. */
-export interface Pesado {
-    readonly id: string;
-    /** `null` = decidido que existe, mas ainda não há de onde vir. Ver `porQueNaoTemFonte`. */
-    readonly url: string | null;
-    /** Medido, não estimado — é o número que uma frase honesta usa antes de começar a descarga. */
-    readonly bytes?: number;
-    /** Obrigatório quando `url` é `null`: uma ausência sem razão escrita vira uma ausência esquecida. */
-    readonly porQueNaoTemFonte?: string;
-}
-/** O nome da Cache Storage. Versionado: mudar o conteúdo do catálogo não deve servir bytes velhos. */
-export declare const CACHE_PESADOS = "incl-pesados-v1";
-export declare const PESADOS: readonly Pesado[];