@the-inclusionist/engine 10.0.0 → 11.0.0

package/dist-pkg/input/voice-map.js

@@ -1,9 +1,10 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // input/voice-map — THE WORDS A CHILD SAYS, AND THE POSITION EACH ONE PRESSES (ADR-0204 erratum; issues #184, #190).
 //
-// This is the pure half of playing by voice: a table of words per language, a closed grammar built from it, and the rule that
-// decides WHEN a heard word becomes a press. Nothing here opens a microphone or loads a model — the same division that let the
-// gaze cycle be measured without a camera.
+// This is the pure half of playing by voice: a table of words per language, a closed grammar built from it and the open menu's
+// names, and what a heard phrase MEANS — a position, or an item by name (ADR-0194). WHEN a phrase is heard is the reader's
+// (`platform/speech-recognition`). Nothing here opens a microphone or loads a model — the same division that let the gaze cycle
+// be measured without a camera.
 //
 // 🎯 THE WORDS ARE THE DEV'S, checked by the Dev against what games use (racing R2 accelerate / L2 brake, shooters L2 aim / R2 fire)
 // and then run in the lab's bar protocol in the three languages: pt 23/23, es 24/24, en 24/24 detected, all rated «ok».
@@ -13,12 +14,13 @@
 // symbol table), so under that recogniser R1 answers only to «estibordo». It stays in the table because the browser's own
 // recogniser has no closed vocabulary and does hear it — a word is dropped by the RECOGNISER that cannot hear it, never by this
 // table, which is the Dev's decision written down.
+import { spokenText, createCommandReader } from '../platform/speech-recognition.js';
 const PT = {
     up: ['acima'], down: ['abaixo'], left: ['esquerda'], right: ['direita'],
     start: ['start'], select: ['select'],
     // 🔴 `ação` WITH THE CEDILLA AND THE TILDE, measured in a browser: written `acao`, the pt model answered "Ignoring word
     // missing in vocabulary: 'acao'" and the first position was MUTE — the child said the word and nothing happened. The
-    // spelling here is the recogniser's VOCABULARY's; whoever compares no longer looks at accents (`wordsOf`), so spelling it
+    // spelling here is the recogniser's VOCABULARY's; whoever compares no longer looks at accents (the reader's key), so spelling it
     // right costs nothing on the hearing side. ⚠️ `boreste` is still outside the small model's vocabulary (ADR-0204 erratum)
     // and stays on the table on purpose: it is the Dev's word, and a larger model hears it.
     action1: ['ação'], action2: ['confirma', 'pega', 'ativar', 'pulo'], action3: ['voltar', 'solta', 'cancelar', 'especial'],
@@ -48,14 +50,6 @@ const BY_LANGUAGE = { pt: PT, es: ES, en: EN };
 export function voiceWordsFor(language) {
     return BY_LANGUAGE[language.split('-')[0].toLowerCase()] ?? PT;
 }
-/**
- * The words a sentence is made of, compared the way a recogniser writes them: no case, no accents, no punctuation.
- * The same rule the quiz's spoken answer uses — a recogniser that writes «Acima.» is not a child who said something else.
- */
-function wordsOf(sentence) {
-    return sentence.normalize('NFD').replace(/[̀-ͯ]/gu, '').toLowerCase()
-        .replace(/[^\p{L}\p{N}]+/gu, ' ').trim().split(' ').filter(Boolean);
-}
 /**
  * THE CLOSED GRAMMAR: every word the recogniser is allowed to return, and nothing else (ADR-0189, ADR-0193).
  *
@@ -63,7 +57,8 @@ function wordsOf(sentence) {
  * says something that is not a command: the lab measured free speech being pushed to the nearest word («configurações de
  * inclusão» → «quatro»). That is the cost of the closed list and the reason the words are short and unlike each other.
  * ⚠️ `extra` is what the MENU is showing right now (ADR-0194): saying the name of an item activates it, so those words join the
- * grammar while that menu is open and leave with it.
+ * grammar while that menu is open and leave with it — AS THE LANGUAGE WRITES THEM (§1, «as shown»), accents kept: stripped,
+ * «configurações» is not in the model's vocabulary and the name goes mute, the same defect «acao» was.
  */
 export function voiceGrammar(language, extra = []) {
     const all = new Set();
@@ -71,55 +66,58 @@ export function voiceGrammar(language, extra = []) {
         for (const p of words)
             all.add(p.toLowerCase());
     for (const e of extra) {
-        const clean = wordsOf(e).join(' ');
+        const clean = spokenText(e);
         if (clean)
             all.add(clean);
     }
     return [...all];
 }
 /**
- * The rule that turns a growing partial into presses.
+ * The Dev's words and the open menu's names, READ BY `platform/speech-recognition.createCommandReader` — the one reader of what
+ * was heard (ADR-0194 §2–§3); this adds only what a word MEANS here, the position it presses.
  *
  * 🎯 A PARTIAL GROWS, AND ONLY WHAT IS NEW FIRES. «acima» then «acima abaixo» is a child who said two words, and the second
- * press must be `down`, not `up` all over again — so the words already answered for are counted, never re-read.
- * 📌 The tail is matched LONGEST FIRST because a position may answer to a phrase: «pick up» is one command in English, and
- * reading only the last word would make it `null` after having fired nothing.
+ * press must be `down`, not `up` all over again — the reader counts what it already answered for in each utterance.
  */
 export function createVoiceCommands(language) {
-    const words = voiceWordsFor(language);
-    const byPhrase = new Map();
-    for (const [action, spoken] of Object.entries(words)) {
+    const actionOf = new Map();
+    for (const [action, spoken] of Object.entries(voiceWordsFor(language))) {
         for (const phrase of spoken)
-            byPhrase.set(wordsOf(phrase).join(' '), action);
+            if (!actionOf.has(spokenText(phrase)))
+                actionOf.set(spokenText(phrase), action);
     }
-    const longest = Math.max(1, ...[...byPhrase.keys()].map((f) => f.split(' ').length));
-    let answered = 0;
+    const reader = createCommandReader([...actionOf.keys()]);
+    let names = [];
+    let utterance = 0;
     let previous = [];
+    const meaning = (heard) => heard.flatMap((h) => {
+        if (h.kind === 'palavra') {
+            const action = actionOf.get(h.word);
+            return action ? [{ kind: 'position', action }] : [];
+        }
+        const name = names.find((n) => spokenText(n) === h.name);
+        return name === undefined ? [] : [{ kind: 'item', name }];
+    });
     return {
+        items(n) { names = [...n]; reader.items(names); },
         partial(text) {
-            const heard = wordsOf(text);
+            const heard = spokenText(text).split(' ').filter(Boolean);
             /*
              * 🔴 A NEW UTTERANCE IS ONE THAT DOES NOT CONTINUE THE LAST, and counting words is not enough to see it: a recogniser
-             * starts a new partial without saying so, and «abaixo» after «acima abaixo» is the same LENGTH as what was already
-             * answered. A case caught it — the child said a second command and nothing moved. What a partial of the same utterance
-             * always is, is the previous one plus more.
+             * starts a new partial without saying so — and does whenever the grammar changes, because a new grammar is a new
+             * recogniser — and «abaixo» after «acima abaixo» is shorter than what was already answered. What a partial of the same
+             * utterance always is, is the previous one plus more.
              */
-            const continues = previous.every((p, i) => heard[i] === p);
-            if (!continues)
-                answered = 0;
+            if (!previous.every((p, i) => heard[i] === p))
+                utterance += 1;
             previous = heard;
-            if (heard.length <= answered)
-                return null;
-            for (let n = Math.min(longest, heard.length - answered); n >= 1; n--) {
-                const action = byPhrase.get(heard.slice(heard.length - n).join(' '));
-                if (action) {
-                    answered = heard.length;
-                    return action;
-                }
-            }
-            answered = heard.length;
-            return null;
+            return meaning(reader.read(utterance, text, false));
+        },
+        final(text) {
+            const done = meaning(reader.read(utterance, text, true));
+            utterance += 1;
+            previous = [];
+            return done;
         },
-        reset() { answered = 0; previous = []; },
     };
 }

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

@@ -21,7 +21,6 @@ export interface AudioAmbientCtx {
     getAudioCtx: () => AudioContext | null;
     catNode: (cat: string) => AudioNode | null;
     audioOut: () => AudioNode | null;
-    noiseBuffer: (ac: AudioContext) => AudioBuffer;
     getSoundOn: () => boolean;
     getVolume: () => number;
     getAudioCat: () => Record<string, {

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

@@ -5,6 +5,7 @@
 //   updateAmbient() — per frame: builds the track once (lazily) and sets the WATER gain (nearness of what the game
 //                     calls 'water') and the RAIN gain (follows the rain level). Gated by audioCat.ambient.on.
 //   thunder(inten)  — a synthesised low rumble (low-passed noise) of variable intensity; called by the weather.
+import { noiseBuffer } from './audio.js';
 export function createAudioAmbient(ctx) {
     let _ambient = null;
     function buildAmbient(ac) {
@@ -66,8 +67,9 @@ export function createAudioAmbient(ctx) {
             return;
         try {
             const vol = ctx.getVolume();
+            // the engine's own white noise (ADR-0258): a game could only ever hand back this same function
             const src = ac.createBufferSource();
-            src.buffer = ctx.noiseBuffer(ac);
+            src.buffer = noiseBuffer(ac);
             src.loop = true;
             const bq = ac.createBiquadFilter();
             bq.type = 'lowpass';

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

@@ -12,8 +12,8 @@ export const AUDIO_CATS = [
     { k: 'earcons', lbl: 'audio.cat.earcons' },
     { k: 'tts', lbl: 'audio.cat.tts' },
     { k: 'sonar', lbl: 'audio.cat.sonar' },
-    { k: 'guard', lbl: 'audio.cat.guard' },
-    { k: 'guide', lbl: 'audio.cat.guide' },
+    // 🔴 `guard` and `guide` LEFT (ADR-0258, the Dev: «Saem.»): the engine plays nothing in either since the guide moved to the
+    // platformer (ADR-0257); a level stored for them stays in the child's storage and is read by nobody.
 ];
 /**
  * The categories born OFF, and the reason for each. A list with its reason written down, not a `k !== 'x'` hanging in an
@@ -22,14 +22,9 @@ export const AUDIO_CATS = [
  *  · `tts` — a robotic voice irritates and overloads autistic people. Whoever needs it turns it on in the menu. (The
  *    literacy voice is `gameSay()`, independent of this and always on.)
  *
- *  · `guide` — the audio guide, off by the Dev's decision, a PROVISIONAL measure that should not become permanent
- *    without someone reviewing it. The Dev's verdict on the old beacon: «um ping é a pior escolha possível, tenebroso
- *    para quem tem TEA». It was not the FREQUENCY that was wrong — it was the beep, which the child who most needs cues
- *    heard the whole game long. Its replacement, a sound that grows as one approaches along a walkable route (#84), is
- *    the game's to decide; until someone reviews it, silence is the default, and a child who wants the guide can still
- *    turn it on in the hearing menu.
+ * (`guide`, born off by the Dev's decision on the old beacon, left with its category — ADR-0258.)
  */
-const BORN_OFF = new Set(['tts', 'guide']);
+const BORN_OFF = new Set(['tts']);
 /**
  * A category's FACTORY state. It has a name because two places need it: the boot's read (when nothing is stored) and
  * the hearing menu's "restore defaults" (ADR-0028). Writing `k !== 'tts'` and `0.8` in both would be the ownerless copy

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

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import { type Spot, type Topology, type Speakable, type Role } from '../core/contract.js';
+import { type Spot, type Topology, type Speakable } from '../core/contract.js';
 import type { Translate } from '../core/i18n.js';
 export type SinkAC = AudioContext & {
     setSinkId?: (id: string) => Promise<void>;
@@ -33,51 +33,6 @@ export interface SonarPlayer extends PlayerAudioOut {
     readonly y: number;
     readonly audioSink?: string | null;
 }
-/** 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 filter: BiquadFilterNode;
-    readonly gain: GainNode;
-    /** `null` on an engine without `createStereoPanner` — the guide goes mono instead of not existing. */
-    readonly panner: StereoPannerNode | null;
-    /** 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;
-}
-/**
- * ⚠️ THE TIMBRE MUST HAVE HARMONICS, and it is a technical requirement, not taste.
- *
- * 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.
- *
- * 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 GUIDE_WAVE: OscillatorType;
-/**
- * How many frames between two route computations.
- *
- * ⚠️ 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 FRAMES_BETWEEN_ROUTES = 12;
-/**
- * The guide's base gain, before the intensity and the master volume multiply it.
- *
- * ⚠️ 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 GUIDE_VOL = 0.06;
 /**
  * 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
@@ -89,20 +44,6 @@ export declare const GUIDE_VOL = 0.06;
 export interface PlayerAudioOut {
     _ac?: SinkAC | null;
     _acOut?: GainNode | null;
-    /**
-     * 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.
-     *
-     * ⚠️ 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.
-     *
-     * ⚠️ 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.
-     */
-    _guide?: LiveGuide | null;
 }
 export interface PlayerCtxOut {
     ac: AudioContext;
@@ -117,33 +58,19 @@ export interface SonarCtx {
     targetsOf: (playerIndex: number) => readonly Spot[];
     /** Field 3: what the thing there is called. `null` = no name, and the announcement falls back to the generic. */
     nameAt: (at: Spot) => Speakable | null;
-    /**
-     * Field 2: what is at this spot. It is what `core/route` crosses (or not) to find the way.
-     *
-     * ⚠️ 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;
     /**
-     * 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.
-     *
-     * 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.
+     * Speaks the sonar's words. `seat` is the player who pressed: a reading takes turns with the other players' and cuts that
+     * player's own (ADR-0234, errata 2026-09-26 — the root's narration does it; a ctx built by hand may ignore it).
      */
-    catNode?: (cat: string) => AudioNode | null;
-    /** The master node, `catNode`'s fallback. */
-    audioOut?: () => AudioNode | null;
+    narrate: (text: string, seat: number) => void;
     /**
-     * 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.
+     * WHAT IS ON THE SCREEN NOW, as text in reading order — `''` when there is none the engine can read (ADR-0234: «sonar do que
+     * está na tela»). With text, the sonar's WORDS are that text, read at the press; the tone still points at the nearest
+     * target. Without (a world drawn on a canvas, or no text), the words are the navigation sentence. Absent: always the latter.
      */
-    getVolume?: () => number;
+    screenText?: () => string;
     /**
      * Is this child's sight impaired — simulated blindness or low vision?
      *
@@ -163,13 +90,7 @@ export interface SonarCtx {
      * is a candidate for the next major.
      */
     LOGICAL_W?: number;
-    getPlayers: () => SonarPlayer[];
     getNumPlayers: () => number;
-    getAudioCtx: () => AudioContext | null;
-    getSoundOn: () => boolean;
-    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`
@@ -182,13 +103,6 @@ export interface AudioSonar {
     panFor: (wx: number, pl: SonarPlayer) => number;
     needsAudioCues: (pl: SonarPlayer) => boolean;
     sonar: (pl: SonarPlayer) => void;
-    updateGuide: () => void;
     readonly sonarCount: number;
-    /**
-     * ⚠️ 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;
 }
 export declare function createAudioSonar(ctx: SonarCtx): AudioSonar;

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

@@ -9,7 +9,8 @@
 //
 // 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.
+// hitbox, are the platformer's and live in its repository (ADR-0228, note CC). So is the continuous audio GUIDE, which
+// is that game's decision: it left this module for the platformer's `platform/audio-guide` (ADR-0257, note DZ).
 //
 // ========================= 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
@@ -36,11 +37,6 @@
 // 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';
-// 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';
 /**
  * How many STEPS of the declared metric saturate the stereo. Beyond this, "to the right" is just to the right.
  *
@@ -62,55 +58,9 @@ export const PAN_PACES = 11;
 export function worldStep(shape) {
     return shape.kind === 'continuous' ? shape.unit : shape.kind === 'grid' ? 1 : 0;
 }
-/**
- * ⚠️ THE TIMBRE MUST HAVE HARMONICS, and it is a technical requirement, not taste.
- *
- * 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.
- *
- * 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 GUIDE_WAVE = 'sawtooth';
-/**
- * The guide's fundamental, fixed.
- *
- * ⚠️ 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.
- */
-const GUIDE_HZ = 220;
-/**
- * How many frames between two route computations.
- *
- * ⚠️ 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 FRAMES_BETWEEN_ROUTES = 12;
-/**
- * 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.
- */
-const ROUTE_BUDGET = 1024;
-/**
- * The guide's base gain, before the intensity and the master volume multiply it.
- *
- * ⚠️ 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 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;
+    let _sonarCount = 0;
     /** The player's AudioContext (for `setSinkId` on their device), or null → the global context. */
     function playerCtx(pl) {
         if (!pl || !pl.audioSink)
@@ -143,7 +93,8 @@ export function createAudioSonar(ctx) {
         return Math.max(-1, Math.min(1, (wx - pl.x) / (PAN_PACES * pace)));
     }
     /**
-     * Impaired sight? The edge guard and the guide exist only when the answer is yes (or in blind mode).
+     * Impaired sight? A game's audio cues — its edge guard, its guide — ask this, and exist only when the answer is yes (or in
+     * blind mode).
      *
      * ⚠️ 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
@@ -211,19 +162,31 @@ export function createAudioSonar(ctx) {
      * for the child in any genre, which is the contract's point.
      */
     const distanceKey = (d) => d < 4 ? 'sr.nav.veryClose' : d < 9 ? 'sr.nav.close' : 'sr.nav.far';
+    /**
+     * THE SONAR: a tone that points, and words (ADR-0234). The tone is the same with or without text on screen — pitch says how
+     * near the nearest target is, the pan which side, and a low tone that there is none. The WORDS are what is on the screen
+     * when there is text there, read now; only a screen with no text the engine can read gets the navigation sentence.
+     */
     function sonar(pl) {
         _sonarCount++;
         const pc = playerCtx(pl);
         const target = nearestSpot(pl);
+        if (target)
+            ctx.tonePan(380 + 740 * Math.max(0, 1 - target.d / 12), 0.16, 'sonar', panFor(target.at.x, pl), 0.26, 'sine', pc); // nearer = higher
+        else
+            ctx.tonePan(300, 0.2, 'sonar', 0, 0.2, 'sine', pc);
+        const onScreen = ctx.screenText?.() ?? '';
+        if (onScreen) {
+            ctx.srSay(onScreen);
+            ctx.narrate(onScreen, pl.i);
+            return;
+        }
         // 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(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);
@@ -234,158 +197,10 @@ export function createAudioSonar(ctx) {
         });
         const msg = (ctx.getNumPlayers() > 1 ? t('sr.player.prefix', { n: pl.i + 1 }) : '') + foundSentence;
         ctx.srSay(msg);
-        ctx.narrate(msg);
-    }
-    /**
-     * HOW MANY STEPS REMAIN, and the preferred answer is the one that goes round walls.
-     *
-     * ⚠️ 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.
-     *
-     * 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 stepsToTarget(pl, target) {
-        const roleAt = ctx.roleAt;
-        if (roleAt) {
-            const path = routeTo({ topology: ctx.topology(), roleAt, budget: ROUTE_BUDGET }, { x: pl.x, y: pl.y }, [target.at]);
-            if (path)
-                return path.steps;
-        }
-        return target.d;
-    }
-    /** 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(), 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();
-                level.connect(panner);
-                migrated = panner;
-            }
-            osc.connect(lowpass).connect(level);
-            migrated.connect(pc ? pc.out : (ctx.catNode?.('guide') || ctx.audioOut?.() || ac.destination));
-            osc.start();
-            // `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;
-        }
-    }
-    /**
-     * 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.
-     *
-     * 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 stopGuide(pl) {
-        const g = pl._guide;
-        if (!g)
-            return;
-        pl._guide = null;
-        try {
-            const audioNow = g.ac.currentTime;
-            g.gain.gain.setTargetAtTime(0, audioNow, 0.05);
-            g.osc.stop(audioNow + 0.3);
-        }
-        catch (e) { /* noop */ }
-    }
-    /**
-     * THE CONTINUOUS PRESENCE, one frame at a time (#84 item 2).
-     *
-     * ⚠️ 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.
-     *
-     * ⚠️ 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 audible = guideAudible();
-        const vol = ctx.getVolume ? ctx.getVolume() : 1;
-        for (const pl of ctx.getPlayers()) {
-            if (!audible || !needsAudioCues(pl)) {
-                stopGuide(pl);
-                continue;
-            }
-            // 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;
-            }
-            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 */ }
+        ctx.narrate(msg, pl.i);
     }
     return {
-        playerCtx, panFor, needsAudioCues, sonar, updateGuide,
+        playerCtx, panFor, needsAudioCues, sonar,
         get sonarCount() { return _sonarCount; },
-        get guideCount() { return _guideCount; },
     };
 }