@the-inclusionist/engine 9.0.0 → 10.0.0

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

@@ -1,31 +1,31 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { type Spot, type Topology, type Speakable, type Role } from '../core/contract.js';
+import type { Translate } from '../core/i18n.js';
 export type SinkAC = AudioContext & {
     setSinkId?: (id: string) => Promise<void>;
 };
 /**
- * Quantos PASSOS da métrica declarada saturam o estéreo. Além disto, "à direita" é só à direita.
+ * How many STEPS of the declared metric saturate the stereo. Beyond this, "to the right" is just to the right.
  *
- * ⚠️ ONZE NÃO É NÚMERO NOVO — é o que a plataforma sempre teve, relido na régua certa. O denominador antigo
- * era `LOGICAL_W * 0.55 = 320 × 0,55 = 176` pixels, e a plataforma declara `unit: TILE` = 16: são **exatamente
- * 11 tiles**. Reescrever em passos preserva o que essa criança já ouve, letra por letra, e passa a dizer o
- * mesmo em qualquer gênero — 11 casas num tabuleiro, 11 metros num campo.
+ * ⚠️ ELEVEN IS NOT A NEW NUMBER — it is what the platformer always had, reread on the right ruler. The old denominator was
+ * `LOGICAL_W * 0.55 = 320 × 0.55 = 176` pixels, and the platformer declares `unit: TILE` = 16: **exactly 11 tiles**.
+ * Rewriting it in steps keeps what that child already hears, and says the same in any genre — 11 squares on a board,
+ * 11 metres on a pitch.
  *
- * E encaixa na régua que o resto do módulo já usa: `chaveDeDistancia` corta "muito perto" em 4 passos e
- * "perto" em 9. O estéreo satura logo depois de a coisa passar a ser "longe", que é onde a direção deixa de
- * precisar de mais precisão.
+ * And it fits the ruler the rest of the module uses: `distanceKey` cuts "very near" at 4 steps and "near" at 9. The
+ * stereo saturates just after the thing becomes "far", which is where direction stops needing more precision.
  */
 export declare const PAN_PACES = 11;
 /**
- * Quanto vale UM passo, em unidades do mundo. Zero = este espaço não tem lado.
+ * What ONE step is worth, in world units. Zero = this space has no sides.
  *
- * Contínuo: o `unit` declarado. Grade: uma célula, por definição. Lista: nada — `hotspots` é uma ordem, não
- * uma geometria, e inventar-lhe uma largura de estéreo seria apontar para um lado que não existe.
+ * Continuous: the declared `unit`. Grid: one cell, by definition. List: nothing — `hotspots` is an order, not a geometry,
+ * and inventing a stereo width for it would point at a side that does not exist.
  */
-export declare function passoDoMundo(topo: Topology): number;
+export declare function worldStep(shape: Topology): number;
 /**
- * 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.
+ * The player as navigation by sound sees them. The MINIMAL slice, which shrank with the cut: `facing` stayed with the cane
+ * (it is the cane that taps "ahead") and `wnT` with swimming. What remains is identity, position, sight and the device.
  */
 export interface SonarPlayer extends PlayerAudioOut {
     readonly i: number;
@@ -33,156 +33,134 @@ export interface SonarPlayer extends PlayerAudioOut {
     readonly y: number;
     readonly audioSink?: string | null;
 }
-/** O grafo contínuo do guia: oscilador → passa-baixo → ganho → panorâmica → categoria `guide`. */
-export interface GuiaVivo {
-    /** O contexto que o construiu — é dele que sai o `currentTime` de cada `setTargetAtTime`. */
+/** The guide's continuous graph: oscillator → low-pass → gain → pan → the `guide` category. */
+export interface LiveGuide {
+    /** The context that built it — each `setTargetAtTime` takes its `currentTime` from it. */
     readonly ac: AudioContext;
     readonly osc: OscillatorNode;
-    readonly filtro: BiquadFilterNode;
-    readonly ganho: GainNode;
-    /** `null` em motor sem `createStereoPanner` — o guia fica mono em vez de não existir. */
+    readonly filter: BiquadFilterNode;
+    readonly gain: GainNode;
+    /** `null` on an engine without `createStereoPanner` — the guide goes mono instead of not existing. */
     readonly panner: StereoPannerNode | null;
-    /** Quadros desde a última vez que a ROTA foi recalculada. A rota é cara; o som não pode esperar por ela. */
-    desdeARota: number;
-    /** O último `passos` medido. É daqui que a intensidade sai a cada quadro. */
-    passos: number;
-    /** A última panorâmica medida, pelo mesmo motivo: ela vem do alvo, que só se procura com a rota. */
+    /** Frames since the ROUTE was last recomputed. The route is costly; the sound cannot wait for it. */
+    framesSinceRoute: number;
+    /** The last measured steps. The intensity comes from here every frame. */
+    steps: number;
+    /** The last measured pan, for the same reason: it comes from the target, which is found only with the route. */
     pan: number;
 }
 /**
- * ⚠️ O TIMBRE TEM DE TER HARMÓNICOS, e isto é requisito técnico, não gosto.
+ * ⚠️ THE TIMBRE MUST HAVE HARMONICS, and it is a technical requirement, not taste.
  *
- * O eixo do #84 item 2 é o BRILHO, e brilho é um passa-baixo a abrir e a fechar. **Um passa-baixo sobre uma
- * onda `sine` não faz absolutamente nada**: a senoide não tem nada acima da fundamental para o filtro cortar,
- * e o guia ficaria com um eixo morto e só o volume a trabalhar. A dente-de-serra é a mais rica das quatro
- * ondas do Web Audio — tem TODOS os harmónicos —, e é por isso que ela é a escolha.
+ * The axis of #84 item 2 is BRIGHTNESS, and brightness is a low-pass opening and closing. **A low-pass over a `sine` wave
+ * does absolutely nothing**: a sine has nothing above its fundamental for the filter to cut, and the guide would be left
+ * with a dead axis and only the volume working. The sawtooth is the richest of Web Audio's four waves — it has ALL the
+ * harmonics — which is why it is the choice.
  *
- * E ela resolve, de graça, a outra restrição do plano: o sonar e a bengala usam `sine`. Um timbre diferente
- * era exigência de não colidirem no mesmo canal; aqui o timbre diferente É o mecanismo.
+ * And it solves, for free, the plan's other constraint: the sonar and the cane use `sine`. A different timbre was
+ * required so they would not collide on one channel; here the different timbre IS the mechanism.
  */
-export declare const GUIA_TIPO: OscillatorType;
+export declare const GUIDE_WAVE: OscillatorType;
 /**
- * A fundamental do guia, fixa.
+ * How many frames between two route computations.
  *
- * ⚠️ FIXA DE PROPÓSITO: a ALTURA já é a linguagem do sonar (`380 + 740 * near`, mais perto = mais agudo). Se o
- * guia também subisse de tom, os dois estariam a dizer a mesma coisa pelo mesmo meio, e quem ouve os dois ao
- * mesmo tempo não teria como separá-los. O guia diz distância por brilho; o sonar, por altura.
+ * ⚠️ THE ROUTE IS A BREADTH-FIRST SEARCH, and `__incl.update(dt)` counts FRAMES: running a BFS every frame on a platform
+ * map spends the whole frame budget on the target device (Positivo/Chromebook, pillar 1). Twelve frames are ~0.2 s at
+ * 60 fps — faster than a child takes a step, and the sound does not wait for them: the intensity is rewritten EVERY
+ * frame, with the steps the last route left.
  */
-export declare const GUIA_HZ = 220;
+export declare const FRAMES_BETWEEN_ROUTES = 12;
 /**
- * Quantos quadros entre dois cálculos de rota.
+ * The guide's base gain, before the intensity and the master volume multiply it.
  *
- * ⚠️ A ROTA É UMA BUSCA EM LARGURA, e o `__incl.update(dt)` conta QUADROS: correr uma BFS a cada quadro num
- * mapa de plataforma gasta o orçamento do quadro inteiro no aparelho-alvo (Positivo/Chromebook, pilar 1). Doze
- * quadros são ~0,2 s a 60 fps — mais depressa do que a criança anda um passo, e o som não espera por eles: a
- * intensidade é reescrita TODO quadro, com o `passos` que a última rota deixou.
+ * ⚠️ LOWER THAN THE BEEP IT REPLACES (0.11), and not by mistake: a sound that **never stops** is perceived as louder
+ * than a transient of the same peak, and it tires by persistence rather than intensity — exactly what autism-support
+ * mode exists not to do.
  */
-export declare const QUADROS_ENTRE_ROTAS = 12;
+export declare const GUIDE_VOL = 0.06;
 /**
- * O tecto de pontos da rota do guia. Bem abaixo dos 4096 do `core/route`, e o próprio módulo diz porquê:
- * «uma pista por quadro tolera muito menos do que um cálculo ao carregar a fase». Estourar devolve `null`, que
- * é «não sei» — e o guia cai na reta, que ainda soa.
- */
-export declare const ORCAMENTO_DA_ROTA = 1024;
-/**
- * O ganho de base do guia, antes de a intensidade e o volume mestre o multiplicarem.
+ * A player's DEDICATED OUTPUT, and this module OWNS it: it is here the two fields are BORN (`new AC()` + `createGain()`,
+ * below). By ADR-0039 the owner declares where a field is born, and `core/entity` does not mention them — they are not
+ * the engine entity's, they are scratch the audio hangs on the player.
  *
- * ⚠️ MAIS BAIXO DO QUE O BIPE QUE ELE SUBSTITUI (0,11), e não por engano: um som que **nunca para** é
- * percebido como mais alto do que um transiente do mesmo pico, e cansa por permanência em vez de por
- * intensidade — exactamente o que o modo TEA existe para não fazer.
- */
-export declare const GUIA_VOL = 0.06;
-/** Constante de tempo do `setTargetAtTime`. Curta o bastante para acompanhar o passo, longa o bastante para
- *  que a mudança seja um deslize e não um degrau — um degrau a cada rota seria um bipe outra vez. */
-export declare const TAU_DO_GUIA = 0.08;
-/**
- * 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.
+ * `_acOut` allows `null` because the audio panel writes `null` to both when the device changes; an `unknown` on the
+ * entity used to hide that the owner declared a non-null `GainNode`.
  */
 export interface PlayerAudioOut {
     _ac?: SinkAC | null;
     _acOut?: GainNode | null;
     /**
-     * O GRAFO VIVO DO GUIA deste jogador, e mora AQUI, ao lado dos outros dois, pelo mesmo motivo que eles
-     * (ADR-0039: o dono declara onde o campo nasce; ADR-0033: a entidade da engine declara o que a ENGINE
-     * possui, e um oscilador não é dela). `null`/ausente = calado.
+     * This player's LIVE GUIDE GRAPH, and it lives HERE, beside the other two, for their reason (ADR-0039: the owner
+     * declares where a field is born; ADR-0033: the engine's entity declares what the ENGINE owns, and an oscillator is
+     * not). `null`/absent = quiet.
      *
-     * ⚠️ ELE PRECISA DE SOBREVIVER AOS QUADROS, e é aí que ele difere de tudo o resto neste ficheiro. O sonar e
-     * o bipe antigo criavam um oscilador, tocavam-no e deitavam-no fora; uma presença CONTÍNUA (#84 item 2) é um
-     * oscilador que FICA, com o filtro e o ganho a mover-se por baixo dele. É por isso que ele tem de estar
-     * pendurado no jogador: não há outro lugar onde algo por jogador dure de um quadro para o outro.
+     * ⚠️ IT HAS TO SURVIVE FRAMES, and that is where it differs from everything else in this file. The sonar and the old
+     * beep created an oscillator, played it and threw it away; a CONTINUOUS presence (#84 item 2) is an oscillator that
+     * STAYS, with the filter and gain moving under it. That is why it hangs on the player: there is nowhere else a
+     * per-player thing lasts from one frame to the next.
      *
-     * ⚠️ E É POR ISSO QUE `desligarGuia` EXISTE. Um campo que dura é um campo que vaza: sem alguém a pará-lo,
-     * desligar a categoria `guide` no mixer deixaria o som a tocar.
+     * ⚠️ AND THAT IS WHY THERE IS A WAY TO STOP IT. A field that lasts is a field that leaks: with nobody stopping it,
+     * turning the `guide` category off in the mixer would leave the sound playing.
      */
-    _guia?: GuiaVivo | null;
+    _guide?: LiveGuide | null;
 }
 export interface PlayerCtxOut {
     ac: AudioContext;
     out: GainNode;
 }
 export interface SonarCtx {
-    /** Campo 1: a métrica. Função, porque um jogo com fases troca de topologia entre elas. */
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    /** Field 1: the metric. A function, because a game with stages changes topology between them. */
     topology: () => Topology;
-    /** Campo 5, metade "alvo": onde estão os alvos ainda válidos deste jogador. Vazio = nada a apontar. */
+    /** Field 5, the "target" half: where this player's still-valid targets are. Empty = nothing to point at. */
     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. */
+    /** Field 3: what the thing there is called. `null` = no name, and the announcement falls back to the generic. */
     nameAt: (at: Spot) => Speakable | null;
     /**
-     * Campo 2: o que há neste ponto. É o que o `core/route` atravessa (ou não) para achar o caminho.
+     * Field 2: what is at this spot. It is what `core/route` crosses (or not) to find the way.
      *
-     * ⚠️ OPCIONAL AQUI, e obrigatório na `GameDeclaration` — a diferença não é descuido. Tornar um campo do
-     * `SonarCtx` obrigatório quebra todo o consumidor que já monta este ctx à mão, e o `create-game` (que é
-     * quem o monta de verdade) sempre o tem, porque o `validateDeclaration` o exige. Ausente aqui, o guia não
-     * fica calado: ele cai na distância em reta, que é o que ele já fazia antes desta mudança.
+     * ⚠️ OPTIONAL HERE, and required in `GameDeclaration` — the difference is not carelessness. Making a `SonarCtx` field
+     * required breaks every consumer that builds this ctx by hand, and the composition root (which really builds it) always
+     * has it, because the declaration's validation requires it. Absent here, the guide does not go quiet: it falls back to
+     * the straight-line distance, which is what it did before.
      */
     roleAt?: (at: Spot) => Role;
     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;
     /**
-     * O barramento de uma categoria do mixer. A MESMA forma que `audio-ambient`, `audio-earcons`, `audio-jingles`
-     * e `tts` já recebem — o guia deixou de poder usar o `tonePan` porque `tonePan` toca e esquece, e uma
-     * presença contínua é um grafo que FICA.
+     * A mixer category's bus. The SAME shape the other audio modules receive — the guide cannot use `tonePan`, because
+     * `tonePan` plays and forgets, and a continuous presence is a graph that STAYS.
      *
-     * Opcional pelo mesmo motivo que o `roleAt`: quem não o injectar cai no `audioOut` e, na falta dele, no
-     * `destination`. O que se perde é o cursor da categoria `guide`, não o som.
+     * Optional for the reason of `roleAt`: whoever does not inject it falls back to `audioOut` and, lacking that, to the
+     * `destination`. What is lost is the `guide` category's slider, not the sound.
      */
     catNode?: (cat: string) => AudioNode | null;
-    /** O nó mestre, recuo do `catNode`. */
+    /** The master node, `catNode`'s fallback. */
     audioOut?: () => AudioNode | null;
     /**
-     * O volume mestre (0..1), que cada síntese multiplica por si — o `_masterGain` do `platform/audio` é o mudo
-     * da pausa, não o cursor. Ausente = 1: o guia soa, e ignora o cursor. Por isso o `create-game` injecta-o.
+     * The master volume (0..1), which each synthesis multiplies by itself — `platform/audio`'s master gain is the pause's
+     * mute, not the slider. Absent = 1: the guide sounds and ignores the slider. That is why the root injects it.
      */
     getVolume?: () => number;
     /**
-     * Esta criança tem a visão comprometida — cegueira simulada ou baixa visão?
+     * Is this child's sight impaired — simulated blindness or low vision?
      *
-     * ⚠️ SUBSTITUIU O `VIZ_BY_KEY` EM 2026-09-08 (#104), e a troca encolheu este módulo em vez de o migrar.
-     * Ele recebia a TABELA de modos de render e atravessava-a com `pl.viz`; agora recebe a RESPOSTA. Quem a dá
-     * é a raiz de composição, que conhece os dois eixos e pode importar de `render/` — o que este ficheiro,
-     * estando em `platform/`, não pode sem inverter uma aresta de camada.
+     * ⚠️ It replaced the table of render modes (#104), and the swap shrank this module instead of migrating it: it used to
+     * receive the TABLE and walk it with `pl.viz`; now it receives the ANSWER. The composition root gives it — it knows the
+     * two axes and may import `render/`, which this file, in `platform/`, cannot without inverting a layer edge.
      *
-     * O `pl` inteiro e não o índice: quem responde já tem o jogador em mão, e passar o índice obrigaria a raiz
-     * a procurá-lo outra vez numa lista que ela acabou de percorrer.
+     * The whole `pl` and not the index: whoever answers already has the player in hand.
      */
-    visaoComprometida: (pl: SonarPlayer) => boolean;
-    getModoCego: () => boolean;
-    /** Largura LÓGICA da tela. É do console, não do gênero — por isso ctx, e não campo de contrato. */
+    visionImpaired: (pl: SonarPlayer) => boolean;
+    getBlindMode: () => boolean;
     /**
-     * @deprecated ⚠️ SEM LEITOR DESDE 2026-09-07 (#121). Era o denominador do pan, e era o defeito: media a
-     * largura do estéreo em pixels de ecrã e dividia por ela uma distância de MUNDO. Agora a largura vem da
-     * topologia (`PAN_PACES * passoDoMundo`).
+     * @deprecated ⚠️ NO READER (#121). It was the pan's denominator, and it was the defect: it measured the stereo width in
+     * screen pixels and divided a WORLD distance by it. The width now comes from the topology (`PAN_PACES * worldStep`).
      *
-     * Ficou OPCIONAL em vez de removido — tornar um campo obrigatório em opcional é compatível para trás, e
-     * quem já o injecta continua a compilar. Removê-lo de vez é candidato ao próximo major.
+     * It stayed OPTIONAL instead of removed — making a required field optional is backward compatible. Removing it for good
+     * is a candidate for the next major.
      */
     LOGICAL_W?: number;
     getPlayers: () => SonarPlayer[];
@@ -192,6 +170,12 @@ export interface SonarCtx {
     getAudioCat: () => Record<string, {
         on: boolean;
     }> | null;
+    /**
+     * Makes a NEW AudioContext, or `null` where the host has none: each player with an audio device of their own gets one, so
+     * `setSinkId` can send that child's cues to that device. The root's maker, from `host.win` — the same one its `createAudio`
+     * receives. REQUIRED (ADR-0232 D4): a default would be the page's window reached from `platform/`.
+     */
+    newContext: () => AudioContext | null;
 }
 export interface AudioSonar {
     playerCtx: (pl: SonarPlayer) => PlayerCtxOut | null;
@@ -201,10 +185,9 @@ export interface AudioSonar {
     updateGuide: () => void;
     readonly sonarCount: number;
     /**
-     * ⚠️ MUDOU DE SIGNIFICADO com o #84 item 2, e o número passa a ser muito maior. Contava BIPES (um a cada 48
-     * quadros); conta agora QUADROS EM QUE O GUIA SOA, porque não há mais nada discreto para contar — é essa a
-     * mudança. Quem o lê para dizer «o guia está a funcionar» continua certo; quem o lesse para dizer «tocou
-     * três vezes» estaria a perguntar por uma coisa que deixou de existir.
+     * ⚠️ It counts FRAMES IN WHICH THE GUIDE SOUNDS (#84 item 2), not beeps: there is nothing discrete left to count.
+     * Reading it to say "the guide is working" is right; reading it to say "it played three times" asks about something
+     * that no longer exists.
      */
     readonly guideCount: number;
 }