@the-inclusionist/engine 8.0.0 → 10.0.0

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

@@ -1,131 +1,126 @@
 // 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).
+// platform/audio-sonar — NAVIGATION BY SOUND, the part of audio navigation that serves ANY genre (item 19).
 //
-// ========================= O ACHADO 9, VIRADO CORTE =========================
-// O segundo consumidor registrou, e não contornou:
+// ========================= A FINDING, TURNED INTO A CUT =========================
+// A second consumer recorded it and did not work around it: the sonar could not be used by anything but a platformer.
+// Its context asked for tiles, a solid test, a hitbox, the tile size, a coin array and a scenery — a quiz would have had
+// to invent fake tiles, a fake hitbox and a fake scenery to ask "point at the nearest option". The module was TWO
+// modules under one name.
 //
-//     "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ó."
+// This is one of them: what navigates by SOUND — pointing at the nearest target, the looping beacon, the pan by relative
+// position and the question "does this child need audio cues?". The CANE and BLIND SWIMMING, which read tiles, floor and
+// hitbox, are the platformer's and live in its repository (ADR-0228, note CC), and the audio guide is its decision.
 //
-// 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.
+// ========================= WHAT REPLACED THE PLATFORMER THINGS =========================
+// None of them crossed over. The sonar used to ask the game for an array of coins and filter by taken/owner; now it
+// receives the CONTRACT (ADR-0030):
 //
-// ========================= 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):
+//   · the coins + the filter  →  `targetsOf(i)`, the "target" half of field 5. The game hands over the spots that still
+//     count for that player, and never says what they are.
+//   · the tile size (the ruler of "near")  →  `topology()` + `distance()`, the metric declared in field 1. In a
+//     platformer it is pixels over `unit`; on a grid, king's steps; in a quiz, a difference of index.
+//   · the target's name  →  `nameAt(spot)`, field 3. It is what lets the announcement say "coin", "question" or "box"
+//     without the engine knowing any of the three.
 //
-//   · `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.
+// ⚠️ AND ONE WAS LEFT, THE LAST AND THE WORST: the pan measured the stereo width as `LOGICAL_W * 0.55` — the SCREEN's
+// width. The `wx` it divides comes from the TOPOLOGY, and dividing a world measure by a screen's width only works when
+// both use the same ruler. Measured building a football game (#121): on a 90-METRE pitch, a team-mate ten metres to the
+// right gives `10 / 176 = 0.057` — mono, in practice. The sonar would be **right and inaudible**. For the platformer it
+// was true by chance (its world is measured in pixels) and for `grid`/`hotspots` it was vacuous, which is why it was
+// never seen.
 //
-// ⚠️ E SOBRAVA UMA, QUE ERA A ÚLTIMA E A PIOR: o pan media a largura do estéreo em `LOGICAL_W * 0.55` — a
-// largura da TELA. Escrevi aqui que ela era «da tela e não do gênero, e por isso entra por ctx». A frase
-// estava certa sobre a origem e errada sobre a consequência: o `wx` que ela divide vem da TOPOLOGIA, e
-// dividir uma medida de mundo pela largura de um ecrã só funciona quando as duas usam a mesma régua.
+// The stereo width comes from the declared metric: `PAN_PACES * step`, where the step is the continuous space's `unit`,
+// one cell on a grid, and nothing in a list — which has no space.
 //
-// Medido ao construir o `game-soccer` (#121): num campo de 90 METROS, um colega dez metros à direita dá
-// `10 / 176 = 0,057` — mono, na prática. O sonar ficaria **certo e inaudível**, que é a mesma classe de
-// defeito que o quiz registou como «certo e inútil». Para a plataforma era verdade por acaso (o mundo dela é
-// medido em pixels) e para `grid`/`hotspots` era vácuo, e é por isso que nunca se viu.
-//
-// A largura do estéreo passa a vir da métrica declarada: `PAN_PACES * passo`, onde o passo é o `unit` do
-// contínuo, uma célula na grade, e nada na lista — que não tem espaço.
-//
-// ========================= SEM I/O NO IMPORT =========================
-// Nada aqui toca `window` fora de `playerCtx`, que é chamada e não importada. Roda no project `node`.
+// ========================= NO I/O AT IMPORT =========================
+// Nothing here touches `window`: a player's own context comes from the injected `newContext` (ADR-0232 D4). It runs in the
+// `node` project.
 import { distance, bearing } from '../core/contract.js';
-import { t } from '../core/i18n.js';
-// O GUIA (#84 item 2) é feito destes dois, e de mais nada: a ROTA diz quantos passos faltam contornando
-// parede, e a INTENSIDADE traduz esse número em brilho e volume. Nenhum dos dois toca no Web Audio; a fiação
-// — a única parte que toca — é o `updateGuide` lá em baixo, e é por isso que o desenho é conferível em `node`.
-import { rotaAte } from '../core/route.js';
-import { intensidadeDoGuia, CORTE_LONGE, PASSOS_ATE_O_FUNDO } from './guide-intensity.js';
+// THE GUIDE (#84 item 2) is made of these two and nothing else: the ROUTE says how many steps remain going round walls,
+// and the INTENSITY turns that number into brightness and volume. Neither touches Web Audio; the wiring — the only part
+// that does — is `updateGuide` below, which is why the design can be checked in `node`.
+import { routeTo } from '../core/route.js';
+import { guideIntensity, FAR_CUT, STEPS_TO_FLOOR } from './guide-intensity.js';
 /**
- * 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 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 function passoDoMundo(topo) {
-    return topo.kind === 'continuous' ? topo.unit : topo.kind === 'grid' ? 1 : 0;
+export function worldStep(shape) {
+    return shape.kind === 'continuous' ? shape.unit : shape.kind === 'grid' ? 1 : 0;
 }
 /**
- * ⚠️ 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 const GUIA_TIPO = 'sawtooth';
+export const GUIDE_WAVE = 'sawtooth';
 /**
- * A fundamental do guia, fixa.
+ * The guide's fundamental, fixed.
  *
- * ⚠️ 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.
+ * ⚠️ FIXED ON PURPOSE: PITCH is already the sonar's language (`380 + 740 * near`, nearer = higher). If the guide also
+ * rose in pitch, both would say the same thing through the same means, and whoever hears both at once could not tell them
+ * apart. The guide says distance by brightness; the sonar, by pitch.
  */
-export const GUIA_HZ = 220;
+const GUIDE_HZ = 220;
 /**
- * Quantos quadros entre dois cálculos de rota.
+ * How many frames between two route computations.
  *
- * ⚠️ 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.
+ * ⚠️ 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 const QUADROS_ENTRE_ROTAS = 12;
+export const FRAMES_BETWEEN_ROUTES = 12;
 /**
- * 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.
+ * The ceiling of spots for the guide's route. Well below `core/route`'s 4096, and that module says why: a cue every
+ * frame tolerates far less than a calculation when a level loads. Hitting it returns `null`, which is "I cannot say" —
+ * and the guide falls back to the straight line, which still sounds.
  */
-export const ORCAMENTO_DA_ROTA = 1024;
+const ROUTE_BUDGET = 1024;
 /**
- * O ganho de base do guia, antes de a intensidade e o volume mestre o multiplicarem.
+ * The guide's base gain, before the intensity and the master volume multiply it.
  *
- * ⚠️ 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.
+ * ⚠️ 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 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 const TAU_DO_GUIA = 0.08;
+export const GUIDE_VOL = 0.06;
+/** The `setTargetAtTime` time constant. Short enough to follow a step, long enough that a change is a glide and not a
+ *  stair — a stair on every route would be a beep again. */
+const GUIDE_TAU = 0.08;
 export function createAudioSonar(ctx) {
+    const { t } = ctx;
     let _sonarCount = 0, _guideCount = 0;
-    /** AudioContext do jogador (para o `setSinkId` no dispositivo dele), ou null → contexto global. */
+    /** The player's AudioContext (for `setSinkId` on their device), or null → the global context. */
     function playerCtx(pl) {
         if (!pl || !pl.audioSink)
             return null;
         try {
             if (!pl._ac) {
-                const AC = window.AudioContext || window.webkitAudioContext;
-                if (!AC)
+                const ac = ctx.newContext();
+                if (!ac)
                     return null;
-                pl._ac = new AC();
+                pl._ac = ac;
                 pl._acOut = pl._ac.createGain();
                 pl._acOut.connect(pl._ac.destination);
                 if (pl._ac.setSinkId)
@@ -140,242 +135,254 @@ export function createAudioSonar(ctx) {
         }
     }
     function panFor(wx, pl) {
-        const passo = passoDoMundo(ctx.topology());
-        // `hotspots` não tem espaço, logo não tem lado. O `bearing` já responde `none` pelo mesmo motivo, e
-        // centrar é a única resposta honesta — um pan calculado sobre índices de lista aponta para nada.
-        if (!(passo > 0))
+        const pace = worldStep(ctx.topology());
+        // `hotspots` has no space, so no side. `bearing` already answers `none` for the same reason, and centring is the only
+        // honest answer — a pan computed over list indices points at nothing.
+        if (!(pace > 0))
             return 0;
-        return Math.max(-1, Math.min(1, (wx - pl.x) / (PAN_PACES * passo)));
+        return Math.max(-1, Math.min(1, (wx - pl.x) / (PAN_PACES * pace)));
     }
     /**
-     * Visão comprometida? Guarda e guia só existem quando a resposta é sim (ou no modo cego).
+     * Impaired sight? The edge guard and the guide exist only when the answer is yes (or in blind mode).
      *
-     * ⚠️ A METADE VISUAL PASSOU A SER INJECTADA (#104), e o módulo ficou MENOR em vez de migrado. Ele
-     * consultava `ctx.VIZ_BY_KEY[pl.viz]` — uma tabela de modos de RENDER, atravessada por uma chave de
-     * render, dentro de `platform/`. A #104 obrigava a escolher: ou este ficheiro passava a importar
-     * `render/viz-axes` (uma aresta ao contrário: medido, `render/` importa de `platform/` em cinco pontos e o
-     * inverso em nenhum), ou deixava de saber o que é um modo visual.
+     * ⚠️ THE VISUAL HALF IS INJECTED (#104), and the module got SMALLER instead of migrating. It used to consult a table of
+     * RENDER modes, walked with a render key, from inside `platform/`. The choice was: import `render/` (an edge the wrong
+     * way — `render/` imports `platform/`, never the reverse), or stop knowing what a visual mode is.
      *
-     * A segunda é a certa, e é o movimento que o `touch.ts` já nomeia como «o mesmo do achado 10
-     * (`isNavigable`): injetar o BOOLEANO, não o estado». O que este módulo precisa de saber é «esta criança
-     * precisa de pista sonora», e isso não é uma pergunta sobre tabelas de filtro — é uma pergunta que a raiz
-     * de composição responde, porque é ela que conhece os dois eixos.
+     * The second is right, and it is the move of `isNavigable`: inject the BOOLEAN, not the state. What this module needs to
+     * know is "does this child need audio cues", and that is not a question about filter tables — the composition root
+     * answers it, because it knows the two axes.
      *
-     * O que FICA aqui é a regra que é mesmo deste módulo: **o modo cego liga as pistas para toda a gente**,
-     * independentemente do que a visão diga.
+     * What STAYS here is the rule that really is this module's: **blind mode turns the cues on for everyone**, whatever
+     * sight says.
      */
     function needsAudioCues(pl) {
-        return ctx.getModoCego() || ctx.visaoComprometida(pl);
+        return ctx.getBlindMode() || ctx.visionImpaired(pl);
     }
     /**
-     * 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.
+     * THE BEARING IN WORDS, in the player's language and in the frame the GAME declared.
      *
-     * ⚠️ 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:
+     * ⚠️ WHAT THIS REPLACED WAS AN ACCESSIBILITY DEFECT, not a style detail. The sonar computed the side by hand, from a raw
+     * `x`, with a ±4 dead zone:
      *
-     *     alvo.at.x < pl.x - 4 ? 'left' : alvo.at.x > pl.x + 4 ? 'right' : 'ahead'
+     *     target.at.x < pl.x - 4 ? 'left' : target.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.
+     * Three words where the contract has eight — and MIXING FRAMES: left/right is relative to the SCREEN, ahead is relative
+     * to the BODY, and a listener cannot know which origin each one speaks from. Worse: everything above or below the child
+     * became "ahead", exactly the information most missing for someone who cannot see the screen — erased by a dead zone.
      *
-     * ⚠️ 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».
+     * ⚠️ AND THE FRAME IS THE GAME'S. On a board one says "to the north-east"; in a 2D platformer seen from the side, north
+     * means nothing, and what one says is "at 2 o'clock".
      */
-    function emPalavras(r) {
+    function inWords(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.
+        // One key with `{h}` and not twelve — but the singular has its own, because "at 1 hours" is not a sentence in any of
+        // the three languages the way the plural key would write it. Where two forms coincide, having both costs nothing.
         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);
+    /**
+     * This player's nearest target, in the DECLARED METRIC — and `null` if there is none.
+     *
+     * It was a loop over coins that skipped the taken and the unowned and measured with `Math.hypot`. The three things it
+     * knew about the game (that targets are coins, that coins have owners, that distance is Euclidean in pixels) became a
+     * question to the contract and a call to `distance`.
+     */
+    function nearestSpot(pl) {
+        const shape = ctx.topology();
+        const here = { x: pl.x, y: pl.y };
+        let nearest = null, bd = Infinity;
+        for (const target of ctx.targetsOf(pl.i)) {
+            const d = distance(shape, here, target);
             if (d < bd) {
                 bd = d;
-                melhor = alvo;
+                nearest = target;
             }
         }
-        return melhor ? { at: melhor, d: bd } : null;
+        return nearest ? { at: nearest, d: bd } : null;
     }
     /**
-     * "Perto" em PASSOS da métrica declarada, e não em pixels.
+     * "Near" in STEPS of the declared metric, not in 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.
+     * The original thresholds of 4 and 9 tiles become 4 and 9 UNITS: in a platformer with `unit = TILE` the sum is the same
+     * as before; on a grid it is four and nine squares; in a quiz, four and nine items away in the list. The same sentence
+     * for the child in any genre, which is the contract's point.
      */
-    const chaveDeDistancia = (d) => d < 4 ? 'sr.nav.veryClose' : d < 9 ? 'sr.nav.close' : 'sr.nav.far';
+    const distanceKey = (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) {
+        const target = nearestSpot(pl);
+        // A sonar that no longer knows what the target is cannot name it when there is NO target at all: it says "nothing
+        // nearby", which is true in any genre.
+        if (!target) {
             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 pan = panFor(target.at.x, pl), near = Math.max(0, 1 - target.d / 12);
+        ctx.tonePan(380 + 740 * near, 0.16, 'sonar', pan, 0.26, 'sine', pc); // nearer = higher
+        // The NAME comes from the game (field 3); the engine used to say "coin" because it only knew coins. The fallback is
+        // for a game that declares a target without a name: "target" is better than a raw key.
+        const name = ctx.nameAt(target.at);
+        const foundSentence = t('sr.nav.sonarFound', {
+            alvo: name ? name.text : t('sr.nav.target'),
+            lado: inWords(bearing(ctx.topology(), { x: pl.x, y: pl.y }, target.at)),
+            dist: t(distanceKey(target.d)),
         });
-        const msg = (ctx.getNumPlayers() > 1 ? t('sr.player.prefix', { n: pl.i + 1 }) : '') + corpo;
+        const msg = (ctx.getNumPlayers() > 1 ? t('sr.player.prefix', { n: pl.i + 1 }) : '') + foundSentence;
         ctx.srSay(msg);
         ctx.narrate(msg);
     }
     /**
-     * QUANTOS PASSOS FALTAM, e a resposta preferida é a que contorna parede.
+     * HOW MANY STEPS REMAIN, and the preferred answer is the one that goes round walls.
      *
-     * ⚠️ AS DUAS RESPOSTAS JÁ ESTÃO NA MESMA UNIDADE, e é a única razão pela qual esta função é uma linha em vez
-     * de uma conversão: `rotaAte().passos` conta passos por definição, e `distance()` também devolve passos em
-     * TODA topologia — ela própria divide pela `unit` no ramo contínuo. Dividir aqui outra vez pelo passo do
-     * mundo era o erro à espera de ser cometido, e num jogo com `unit = 16` ele poria o guia no brilho máximo
-     * para sempre. É o mesmo defeito que a #121 tirou do `panFor`: misturar régua de mundo com régua de ecrã.
+     * ⚠️ BOTH ANSWERS ARE ALREADY IN THE SAME UNIT, which is the only reason this is a line and not a conversion: the route
+     * counts steps by definition, and `distance()` returns steps in EVERY topology — it divides by the `unit` itself in the
+     * continuous branch. Dividing again by the world step here was the mistake waiting to be made, and in a game with
+     * `unit = 16` it would put the guide at full brightness forever — the defect #121 took out of `panFor`: mixing a world
+     * ruler with a screen ruler.
      *
-     * A rota perde-se de duas maneiras — jogo que não injectou `roleAt`, e orçamento estourado — e as duas caem
-     * no mesmo recuo: a RETA. ⚠️ Ela mente atrás de parede (diz «perto» de um alvo que exige dar a volta), e é
-     * por isso que é recuo e não escolha. Mas é o que o guia já dizia antes desta mudança, e continuar a dizê-lo
-     * é estritamente melhor do que calar — calar afirmaria que não há alvo.
+     * The route is lost two ways — a game that did not inject `roleAt`, and a budget run out — and both fall back to the
+     * STRAIGHT LINE. ⚠️ It lies behind a wall (says "near" of a target that needs going round), which is why it is a
+     * fallback and not a choice. But continuing to say it is strictly better than going quiet — quiet would claim there is
+     * no target.
      */
-    function passosAteOAlvo(pl, alvo) {
+    function stepsToTarget(pl, target) {
         const roleAt = ctx.roleAt;
         if (roleAt) {
-            const rota = rotaAte({ topology: ctx.topology(), roleAt, orcamento: ORCAMENTO_DA_ROTA }, { x: pl.x, y: pl.y }, [alvo.at]);
-            if (rota)
-                return rota.passos;
+            const path = routeTo({ topology: ctx.topology(), roleAt, budget: ROUTE_BUDGET }, { x: pl.x, y: pl.y }, [target.at]);
+            if (path)
+                return path.steps;
         }
-        return alvo.d;
+        return target.d;
     }
-    /** Acende o grafo contínuo deste jogador. `null` = não deu (sem contexto, ou motor sem Web Audio). */
-    function ligarGuia(pl) {
+    /** Lights this player's continuous graph. `null` = it could not (no context, or an engine without Web Audio). */
+    function startGuide(pl) {
         const pc = playerCtx(pl);
         const ac = pc ? pc.ac : ctx.getAudioCtx();
         if (!ac)
             return null;
         try {
-            const osc = ac.createOscillator(), filtro = ac.createBiquadFilter(), ganho = ac.createGain();
-            osc.type = GUIA_TIPO;
-            osc.frequency.value = GUIA_HZ;
-            filtro.type = 'lowpass';
-            filtro.frequency.value = CORTE_LONGE; // nasce no fundo da escala e sobe; nascer aberto seria um susto
-            ganho.gain.value = 0; // e nasce calado, para não estalar ao ligar
-            let saida = ganho;
+            const osc = ac.createOscillator(), lowpass = ac.createBiquadFilter(), level = ac.createGain();
+            osc.type = GUIDE_WAVE;
+            osc.frequency.value = GUIDE_HZ;
+            lowpass.type = 'lowpass';
+            lowpass.frequency.value = FAR_CUT; // born at the bottom of the scale and rising; born open would be a fright
+            level.gain.value = 0; // and born quiet, so it does not click when it starts
+            let migrated = level;
             let panner = null;
             if (ac.createStereoPanner) {
                 panner = ac.createStereoPanner();
-                ganho.connect(panner);
-                saida = panner;
+                level.connect(panner);
+                migrated = panner;
             }
-            osc.connect(filtro).connect(ganho);
-            saida.connect(pc ? pc.out : (ctx.catNode?.('guide') || ctx.audioOut?.() || ac.destination));
+            osc.connect(lowpass).connect(level);
+            migrated.connect(pc ? pc.out : (ctx.catNode?.('guide') || ctx.audioOut?.() || ac.destination));
             osc.start();
-            // `desdeARota` nasce no tecto para que a PRIMEIRA volta já meça a rota, em vez de soar doze quadros
-            // com um `passos` inventado.
-            return { ac, osc, filtro, ganho, panner, desdeARota: QUADROS_ENTRE_ROTAS, passos: PASSOS_ATE_O_FUNDO, pan: 0 };
+            // `framesSinceRoute` is born at the ceiling so the FIRST pass measures the route, instead of sounding for twelve
+            // frames on invented steps.
+            return { ac, osc, filter: lowpass, gain: level, panner, framesSinceRoute: FRAMES_BETWEEN_ROUTES, steps: STEPS_TO_FLOOR, pan: 0 };
         }
         catch (e) {
             return null;
         }
     }
     /**
-     * Apaga o grafo — e ele TEM de ser apagado, porque um oscilador que fica é a diferença entre esta forma e a
-     * anterior. O bipe morria sozinho ao fim de 0,12 s; este toca até alguém o parar. Sem esta função, desligar
-     * a categoria `guide` no mixer deixaria o som a tocar, e trocar de modo visual deixaria um segundo grafo a
-     * somar-se ao primeiro.
+     * Puts the graph out — and it HAS to be put out, because an oscillator that stays is the difference between this shape
+     * and the old one. The beep died by itself; this plays until someone stops it. Without this, turning the `guide`
+     * category off in the mixer would leave the sound playing, and changing visual mode would leave a second graph adding
+     * to the first.
      *
-     * Desce em rampa (não corta) porque um corte seco num oscilador vivo é um clique — um transiente, que é
-     * precisamente o que este item existe para tirar do ouvido da criança.
+     * It ramps down (does not cut) because a dry cut on a live oscillator is a click — a transient, precisely what this item
+     * exists to take out of the child's ear.
      */
-    function desligarGuia(pl) {
-        const g = pl._guia;
+    function stopGuide(pl) {
+        const g = pl._guide;
         if (!g)
             return;
-        pl._guia = null;
+        pl._guide = null;
         try {
-            const agora = g.ac.currentTime;
-            g.ganho.gain.setTargetAtTime(0, agora, 0.05);
-            g.osc.stop(agora + 0.3);
+            const audioNow = g.ac.currentTime;
+            g.gain.gain.setTargetAtTime(0, audioNow, 0.05);
+            g.osc.stop(audioNow + 0.3);
         }
         catch (e) { /* noop */ }
     }
     /**
-     * A PRESENÇA CONTÍNUA, um quadro de cada vez (#84 item 2).
+     * THE CONTINUOUS PRESENCE, one frame at a time (#84 item 2).
      *
-     * ⚠️ O QUE SAIU DAQUI FOI UM BIPE: um `triangle` de 0,12 s a cada 48 quadros, para sempre, independente de a
-     * criança se mexer ou de algo ter mudado. O veredicto do Dev: «um ping é a pior escolha possível, tenebroso
-     * para quem tem TEA». O que entra não dispara nada — o som já está lá, e muda de brilho.
+     * ⚠️ WHAT LEFT HERE WAS A BEEP, forever, whether or not the child moved or anything changed. The Dev's verdict: «um
+     * ping é a pior escolha possível, tenebroso para quem tem TEA». What replaces it fires nothing — the sound is already
+     * there, and changes brightness.
      *
-     * ⚠️ E CALAR CONTINUA A SER UMA AFIRMAÇÃO, com um significado só: NÃO HÁ ALVO. É por isso que «sem alvo»
-     * apaga o grafo e «longe» não: o piso do `guide-intensity` (`VOL_LONGE`) existe exactamente para que a
-     * criança não confunda «está longe» com «não há nada para achar».
+     * ⚠️ AND GOING QUIET IS STILL A STATEMENT, with one meaning only: THERE IS NO TARGET. That is why "no target" puts the
+     * graph out and "far" does not: `guide-intensity`'s floor (`FAR_VOL`) exists exactly so the child does not confuse "it
+     * is far" with "there is nothing to find".
      */
     function updateGuide() {
-        const cat = ctx.getAudioCat();
-        const ligado = !!ctx.getAudioCtx() && ctx.getSoundOn() && !!cat && !!cat.guide && cat.guide.on;
+        const audible = guideAudible();
         const vol = ctx.getVolume ? ctx.getVolume() : 1;
         for (const pl of ctx.getPlayers()) {
-            if (!ligado || !needsAudioCues(pl)) {
-                desligarGuia(pl);
+            if (!audible || !needsAudioCues(pl)) {
+                stopGuide(pl);
                 continue;
             }
-            let g = pl._guia;
-            if (!g) {
-                // ⚠️ A PERGUNTA «HÁ ALVO?» VEM ANTES DE ACENDER, e o gate cobrou-a: com o grafo a nascer primeiro, um
-                // jogador sem alvo criava um oscilador, media a rota, não achava nada e apagava-o — SESSENTA VEZES
-                // POR SEGUNDO. O bipe não tinha este problema porque não tinha nada que durasse; foi a permanência
-                // que o trouxe. `alvoMaisProximo` é um laço sobre `targetsOf`, não a BFS: perguntar por quadro custa
-                // zero quando a lista está vazia, que é exactamente o caso em questão.
-                if (!alvoMaisProximo(pl))
-                    continue;
-                g = pl._guia = ligarGuia(pl);
-                if (!g)
-                    continue;
-            }
-            if (++g.desdeARota >= QUADROS_ENTRE_ROTAS) {
-                g.desdeARota = 0;
-                const alvo = alvoMaisProximo(pl);
-                if (!alvo) {
-                    desligarGuia(pl);
-                    continue;
-                }
-                g.passos = passosAteOAlvo(pl, alvo);
-                g.pan = panFor(alvo.at.x, pl);
-            }
-            // TODO quadro, e não só quando a rota é nova: é isto que faz a mudança ser um deslize.
-            const i = intensidadeDoGuia(g.passos);
-            try {
-                const agora = g.ac.currentTime;
-                g.filtro.frequency.setTargetAtTime(i.corte, agora, TAU_DO_GUIA);
-                g.ganho.gain.setTargetAtTime(GUIA_VOL * i.volume * vol, agora, TAU_DO_GUIA);
-                g.panner?.pan.setTargetAtTime(g.pan, agora, TAU_DO_GUIA);
+            // no guide lit (no target, or a device that refused it), or the target gone: silence says «nothing to find»
+            const g = liveGuide(pl);
+            if (!g || !remeasure(pl, g)) {
+                stopGuide(pl);
+                continue;
             }
-            catch (e) { /* noop */ }
+            glide(g, vol);
             _guideCount++;
         }
     }
+    /** Can the guide be heard at all: the engine's audio started, the game's sound on, and a `guide` category that is on. */
+    function guideAudible() {
+        const cat = ctx.getAudioCat();
+        return !!ctx.getAudioCtx() && ctx.getSoundOn() && !!cat && !!cat.guide && cat.guide.on;
+    }
+    /** This player's live guide — lit here only if there is a target to point to, and `null` where it cannot be lit. */
+    function liveGuide(pl) {
+        if (pl._guide)
+            return pl._guide;
+        // ⚠️ THE QUESTION "IS THERE A TARGET?" COMES BEFORE LIGHTING, and the gate insisted: with the graph born first, a
+        // player with no target created an oscillator, measured the route, found nothing and put it out — SIXTY TIMES A
+        // SECOND. The beep did not have this problem because nothing of it lasted; permanence brought it. `nearestSpot` is a
+        // loop over `targetsOf`, not the BFS: asking every frame costs nothing when the list is empty, which is the case here.
+        if (!nearestSpot(pl))
+            return null;
+        return (pl._guide = startGuide(pl));
+    }
+    /**
+     * Every FRAMES_BETWEEN_ROUTES frames the route and the side are measured again — the BFS on a cadence, not sixty times a
+     * second. Answers `false` when the target is gone.
+     */
+    function remeasure(pl, g) {
+        if (++g.framesSinceRoute < FRAMES_BETWEEN_ROUTES)
+            return true;
+        g.framesSinceRoute = 0;
+        const target = nearestSpot(pl);
+        if (!target)
+            return false;
+        g.steps = stepsToTarget(pl, target);
+        g.pan = panFor(target.at.x, pl);
+        return true;
+    }
+    /** EVERY frame, not only when the route is new: this is what makes the change a glide. */
+    function glide(g, vol) {
+        const i = guideIntensity(g.steps);
+        try {
+            const audioNow = g.ac.currentTime;
+            g.filter.frequency.setTargetAtTime(i.cutoff, audioNow, GUIDE_TAU);
+            g.gain.gain.setTargetAtTime(GUIDE_VOL * i.volume * vol, audioNow, GUIDE_TAU);
+            g.panner?.pan.setTargetAtTime(g.pan, audioNow, GUIDE_TAU);
+        }
+        catch (e) { /* noop */ }
+    }
     return {
         playerCtx, panFor, needsAudioCues, sonar, updateGuide,
         get sonarCount() { return _sonarCount; },