@the-inclusionist/engine 8.0.0 → 10.0.0

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

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-type CatState = {
+import { type AudioCatStore } from './audio-mixer.js';
+export type CatState = {
     on: boolean;
     vol: number;
 };
@@ -10,23 +11,56 @@ type PlayerCtx = {
 type ACWithCache = AudioContext & {
     _noiseBuf?: AudioBuffer;
 };
-export declare let soundOn: boolean;
-export declare function setSoundOn(v: boolean): void;
-export declare let volume: number;
-export declare function setVolume(v: number): void;
-export declare let audioCtx: AudioContext | null;
-export declare function ensureAC(): AudioContext | null;
-export declare let hearingLoss: boolean;
-export declare function audioOut(): GainNode | null;
-export declare function setHearingLossGraph(on: boolean): void;
-export declare function setMasterMuted(muted: boolean): void;
-export declare let audioCat: Record<string, CatState> | null;
-export declare function initAudioMixer(): void;
-export declare function catNode(cat: string): GainNode | null;
-export declare function setCatGain(cat: string): void;
-export declare function tone(freq: number, dur: number, type?: OscillatorType, when?: number, vol?: number): void;
-export declare function tonePan(freq: number, dur: number, cat: string, pan?: number | null, vol?: number, type?: OscillatorType, pc?: PlayerCtx | null): void;
-export declare let _footCount: number;
+export interface AudioDeps {
+    /**
+     * Makes the engine's AudioContext, or answers `null` where the host has none. Called at the FIRST sound and not before: a
+     * context made before the child's first gesture is born suspended, and the browser only lets it run from a gesture. The root
+     * builds it from `host.win` (ADR-0232 point 2); REQUIRED, because a default would be the page's window reached from here.
+     */
+    readonly newContext: () => AudioContext | null;
+    /** Where the mixer's categories are read from and kept: the page's store, built by the root. */
+    readonly store: AudioCatStore;
+}
+/**
+ * ONE ROOT'S SOUND. The reads are GETTERS, so `audio.soundOn` is the value of now; copying one into a local freezes it. The
+ * methods hold no `this` and can be destructured.
+ */
+export interface Audio {
+    /** The game's master switch. Session only (not stored). */
+    readonly soundOn: boolean;
+    setSoundOn(v: boolean): void;
+    /** The master volume, 0..1, which every synthesis multiplies by. Session only. */
+    readonly volume: number;
+    setVolume(v: number): void;
+    /** The engine's context, `null` until the first sound asks for one. */
+    readonly audioCtx: AudioContext | null;
+    /** The context, made on the first call and resumed if the browser suspended it; `null` where the host has none. */
+    ensureAC(): AudioContext | null;
+    /** The master node (master gain → optional hearing-loss filter → destination), made on the first call. */
+    audioOut(): GainNode | null;
+    /** Whether the hearing-loss empathy simulation is on the master node. */
+    readonly hearingLoss: boolean;
+    /** Switches the hearing-loss filter on the master node. Storing it and announcing it are the caller's. */
+    setHearingLossGraph(on: boolean): void;
+    /** The pause and title silence everything; playing brings it back. Acts only if the master exists — never makes one. */
+    setMasterMuted(muted: boolean): void;
+    /** The mixer's live state per category, loaded from the store when the audio is built. Mutated by the panels. */
+    readonly audioCat: Record<string, CatState>;
+    /** A category's bus, hanging off the master node. */
+    catNode(cat: string): GainNode | null;
+    /** Moves a category's bus to its state now, and keeps that state in the store. */
+    setCatGain(cat: string): void;
+    tone(freq: number, dur: number, type?: OscillatorType, when?: number, vol?: number): void;
+    /** `pc` = a per-player audio context, passed to route the cue to that player's device. */
+    tonePan(freq: number, dur: number, cat: string, pan?: number | null, vol?: number, type?: OscillatorType, pc?: PlayerCtx | null): void;
+    noiseHit(mat: string, pan?: number | null, pc?: PlayerCtx | null): void;
+    /** A count of steps and taps (an accessibility statistic). */
+    readonly footCount: number;
+}
 export declare function noiseBuffer(ac: ACWithCache): AudioBuffer;
-export declare function noiseHit(mat: string, pan?: number | null, pc?: PlayerCtx | null): void;
+/**
+ * Builds one root's sound. The mixer's state is read from `store` HERE, so a voice built after it finds its categories — the
+ * order the second consumer once found by the silence (create-game, finding 3) is now the order of construction.
+ */
+export declare function createAudio(deps: AudioDeps): Audio;
 export {};

package/dist-pkg/platform/audio.js

@@ -1,40 +1,21 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// platform/audio.ts — base do áudio: ciclo do AudioContext (ensureAC) + definições de SFX (dados). Módulo-folha.
-// O grafo (master/mixer), soundOn/volume e as sínteses (tone/noiseHit/tonePan/sfx) ainda ficam no game.js —
-// migram numa rodada dedicada (injeção de dependência). audioCtx é binding vivo; só ensureAC o (re)cria. (Fase 2)
-import { loadAudioCat, saveAudioCat } from './audio-mixer.js'; // mixer por categoria (dados + persistência)
-// Som mestre: liga/desliga + volume (0..1). Sessão-only (sem persistência). Bindings vivos: as sínteses
-// (tone/noiseHit/…) e a narração leem soundOn/volume; o botão/slider mestre do game.js escreve pelos setters.
-export let soundOn = true;
-export function setSoundOn(v) { soundOn = v; }
-export let volume = 0.6;
-export function setVolume(v) { volume = v; }
-export let audioCtx = null;
-export function ensureAC() {
-    if (!audioCtx) {
-        const AC = window.AudioContext || window.webkitAudioContext;
-        if (AC)
-            audioCtx = new AC();
-    }
-    if (audioCtx && audioCtx.state === 'suspended')
-        audioCtx.resume();
-    return audioCtx;
-}
-// ===== Nó MESTRE: master gain → (filtro de perda auditiva opcional) → destino. =====
-export let hearingLoss = false;
-let _masterGain = null, _hlChain = null;
-export function audioOut() { const ac = ensureAC(); if (!ac)
-    return null; if (!_masterGain) {
-    _masterGain = ac.createGain();
-    wireMaster();
-} return _masterGain; }
+// platform/audio.ts — the audio base: the AudioContext's lifecycle (ensureAC), the master and mixer graph, and the
+// oscillator and noise syntheses every game's cues are made of. One per root (ADR-0232 D4, issue #207): `createAudio` holds
+// the context, the master, the mixer and the counters in its closure, and receives the host's context maker and store.
+import { loadAudioCat, saveAudioCat } from './audio-mixer.js'; // per-category mixer (data + persistence)
+export function noiseBuffer(ac) { if (ac._noiseBuf && ac._noiseBuf.length === ((ac.sampleRate * 0.2) | 0))
+    return ac._noiseBuf; const n = (ac.sampleRate * 0.2) | 0, b = ac.createBuffer(1, n, ac.sampleRate), d = b.getChannelData(0); for (let i = 0; i < n; i++)
+    d[i] = Math.random() * 2 - 1; return ac._noiseBuf = b; }
+const FOOT = { grama: { f: 'highpass', hz: 2000, d: 0.09, v: 0.10 }, piso: { f: 'bandpass', hz: 1200, d: 0.06, v: 0.15 }, pedra: { f: 'highpass', hz: 1600, d: 0.05, v: 0.19 },
+    areia: { f: 'lowpass', hz: 650, d: 0.13, v: 0.10 }, madeira: { f: 'bandpass', hz: 480, d: 0.08, v: 0.15 }, ferro: { f: 'bandpass', hz: 2600, d: 0.12, v: 0.16 }, parede: { f: 'highpass', hz: 3200, d: 0.10, v: 0.08 },
+    terra: { f: 'lowpass', hz: 520, d: 0.11, v: 0.12 }, agua: { f: 'lowpass', hz: 330, d: 0.15, v: 0.13 } };
 function buildHearingChain(ac) {
     const lp = ac.createBiquadFilter();
     lp.type = 'lowpass';
     lp.frequency.value = 1400;
-    lp.Q.value = 0.7; // agudos primeiro
+    lp.Q.value = 0.7; // the highs go first
     const sp = ac.createScriptProcessor(512, 1, 1);
-    const TH = 0.06, RED = 0.12; // frame < limiar → ×0.12 (contrário de aparelho auditivo)
+    const TH = 0.06, RED = 0.12; // a frame below the threshold → ×0.12 (a hearing aid in reverse)
     sp.onaudioprocess = (e) => { const inp = e.inputBuffer.getChannelData(0), out = e.outputBuffer.getChannelData(0); let s = 0; for (let i = 0; i < inp.length; i++)
         s += inp[i] * inp[i]; const g = Math.sqrt(s / inp.length) < TH ? RED : 1; for (let i = 0; i < inp.length; i++)
         out[i] = inp[i] * g; };
@@ -42,150 +23,161 @@ function buildHearingChain(ac) {
     sp.connect(ac.destination);
     return { input: lp };
 }
-function wireMaster() {
-    const ac = audioCtx;
-    if (!ac || !_masterGain)
-        return;
-    try {
-        _masterGain.disconnect();
+/** The last node before the output: a panner clamped to the two ears when a pan is asked, the gain itself when not. */
+function panned(ac, g, pan) {
+    if (pan == null || !ac.createStereoPanner)
+        return g;
+    const p = ac.createStereoPanner();
+    p.pan.value = Math.max(-1, Math.min(1, pan));
+    g.connect(p);
+    return p;
+}
+/**
+ * Builds one root's sound. The mixer's state is read from `store` HERE, so a voice built after it finds its categories — the
+ * order the second consumer once found by the silence (create-game, finding 3) is now the order of construction.
+ */
+export function createAudio(deps) {
+    let soundOn = true, volume = 0.6;
+    let audioCtx = null;
+    let hearingLoss = false;
+    let masterGain = null, hlChain = null;
+    let footCount = 0;
+    const audioCat = loadAudioCat(deps.store);
+    const catNodes = {};
+    function ensureAC() {
+        if (!audioCtx)
+            audioCtx = deps.newContext();
+        if (audioCtx && audioCtx.state === 'suspended')
+            audioCtx.resume();
+        return audioCtx;
+    }
+    // ===== The MASTER node: master gain → (optional hearing-loss filter) → destination. =====
+    function audioOut() { const ac = ensureAC(); if (!ac)
+        return null; if (!masterGain) {
+        masterGain = ac.createGain();
+        wireMaster();
+    } return masterGain; }
+    function wireMaster() {
+        const ac = audioCtx;
+        if (!ac || !masterGain)
+            return;
+        try {
+            masterGain.disconnect();
+        }
+        catch (e) { /* noop */ }
+        if (hearingLoss) {
+            if (!hlChain)
+                hlChain = buildHearingChain(ac);
+            masterGain.connect(hlChain.input);
+        }
+        else
+            masterGain.connect(ac.destination);
     }
-    catch (e) { /* noop */ }
-    if (hearingLoss) {
-        if (!_hlChain)
-            _hlChain = buildHearingChain(ac);
-        _masterGain.connect(_hlChain.input);
+    function setHearingLossGraph(on) { hearingLoss = on; if (audioCtx) {
+        audioOut();
+        wireMaster();
+    } }
+    function setMasterMuted(muted) { if (!masterGain || !audioCtx)
+        return; try {
+        masterGain.gain.setTargetAtTime(muted ? 0 : 1, audioCtx.currentTime, 0.04);
     }
-    else
-        _masterGain.connect(ac.destination);
-}
-// Empatia de perda auditiva: liga/desliga o filtro no nó mestre. A persistência + srSay ficam no game.js.
-export function setHearingLossGraph(on) { hearingLoss = on; if (audioCtx) {
-    audioOut();
-    wireMaster();
-} }
-// Mute mestre (pausa/título silenciam tudo; volta ao jogar). Só age se o nó mestre já existe (não o cria à toa).
-export function setMasterMuted(muted) { if (!_masterGain || !audioCtx)
-    return; try {
-    _masterGain.gain.setTargetAtTime(muted ? 0 : 1, audioCtx.currentTime, 0.04);
-}
-catch (e) { /* noop */ } }
-// ===== Mixer por categoria: cada categoria tem seu gain (liga/desliga + volume), pendurado no nó mestre. =====
-// audioCat é a fonte viva do estado do mixer (mutada pela UI/calmMode no game.js — objeto, nunca reatribuído
-// APÓS init). NULL até initAudioMixer(): o import fica PURO (não lê localStorage). initAudioMixer é chamado no
-// boot do game.js — todos os leitores de audioCat (mixer/ambiente/narração) rodam depois. (Fase 2.25)
-export let audioCat = null;
-// Carrega o estado do mixer (defaults do audio-mixer.js + o que estiver salvo). I/O EXPLÍCITO, idempotente.
-export function initAudioMixer() { if (!audioCat)
-    audioCat = loadAudioCat(); }
-const _catNodes = {};
-export function catNode(cat) { const ac = ensureAC(); if (!ac || !audioCat)
-    return null; const out = audioOut(); if (!out)
-    return null; if (!_catNodes[cat]) {
-    const g = ac.createGain();
-    g.gain.value = audioCat[cat].on ? audioCat[cat].vol : 0;
-    g.connect(out);
-    _catNodes[cat] = g;
-} return _catNodes[cat]; }
-export function setCatGain(cat) { if (!audioCat)
-    return; const g = _catNodes[cat]; if (g && audioCtx)
-    g.gain.setTargetAtTime(audioCat[cat].on ? audioCat[cat].vol : 0, audioCtx.currentTime, 0.02); saveAudioCat(cat, audioCat[cat]); }
-// ===== Sínteses de oscilador (earcons/melodias). Leem soundOn/volume; roteiam pelo mixer→mestre. =====
-// pc = contexto de áudio por-jogador (opcional; o game.js o passa p/ rotear a pista ao dispositivo do jogador).
-export function tone(freq, dur, type, when, vol) {
-    if (!soundOn || volume <= 0)
-        return;
-    try {
-        const ac = ensureAC();
-        if (!ac)
+    catch (e) { /* noop */ } }
+    // ===== The per-category mixer: each category has its gain (on/off + volume), hanging off the master node. =====
+    /** A category's level: silence when it is switched off, its volume when on — asked the same way when its bus is made and when the slider moves. */
+    function catLevel(cat) { const c = audioCat[cat]; return c.on ? c.vol : 0; }
+    function catNode(cat) { const ac = ensureAC(); if (!ac)
+        return null; const out = audioOut(); if (!out)
+        return null; if (!catNodes[cat]) {
+        const g = ac.createGain();
+        g.gain.value = catLevel(cat);
+        g.connect(out);
+        catNodes[cat] = g;
+    } return catNodes[cat]; }
+    function setCatGain(cat) { const g = catNodes[cat]; if (g && audioCtx)
+        g.gain.setTargetAtTime(catLevel(cat), audioCtx.currentTime, 0.02); saveAudioCat(deps.store, cat, audioCat[cat]); }
+    // ===== The questions a cue asks before it sounds, the same for the tone and the noise. =====
+    /** Whether a sound may play at all: the game's sound on, and the master above zero. */
+    function audible() { return soundOn && volume > 0; }
+    /** The context a cue plays in: the player's own device when one is given, the engine's otherwise. */
+    function contextFor(pc) { return pc ? pc.ac : ensureAC(); }
+    /** Where a cue goes out: the player's own device; otherwise its category's bus, the master, or the device itself. */
+    function outFor(ac, cat, pc) { return pc ? pc.out : (catNode(cat) || audioOut() || ac.destination); }
+    // ===== Oscillator syntheses (earcons/melodies). They read soundOn/volume and route through mixer → master. =====
+    function tone(freq, dur, type, when, vol) {
+        if (!audible())
             return;
-        const o = ac.createOscillator(), g = ac.createGain(), t = ac.currentTime + (when || 0);
-        o.type = type || 'square';
-        o.frequency.setValueAtTime(freq, t);
-        g.gain.setValueAtTime(0.0001, t);
-        g.gain.exponentialRampToValueAtTime(Math.max(0.02, (vol || 0.22) * volume), t + 0.01);
-        g.gain.exponentialRampToValueAtTime(0.0001, t + dur);
-        o.connect(g).connect(catNode('earcons') || audioOut() || ac.destination);
-        o.start(t);
-        o.stop(t + dur + 0.02);
+        try {
+            const ac = contextFor();
+            if (!ac)
+                return;
+            const o = ac.createOscillator(), g = ac.createGain(), t = ac.currentTime + (when || 0);
+            o.type = type || 'square';
+            o.frequency.setValueAtTime(freq, t);
+            g.gain.setValueAtTime(0.0001, t);
+            g.gain.exponentialRampToValueAtTime(Math.max(0.02, (vol || 0.22) * volume), t + 0.01);
+            g.gain.exponentialRampToValueAtTime(0.0001, t + dur);
+            o.connect(g).connect(outFor(ac, 'earcons'));
+            o.start(t);
+            o.stop(t + dur + 0.02);
+        }
+        catch (e) { /* noop */ }
     }
-    catch (e) { /* noop */ }
-}
-export function tonePan(freq, dur, cat, pan, vol, type, pc) {
-    if (!soundOn || volume <= 0)
-        return;
-    const ac = pc ? pc.ac : ensureAC();
-    if (!ac)
-        return;
-    try {
-        const o = ac.createOscillator(), g = ac.createGain(), t = ac.currentTime;
-        o.type = type || 'sine';
-        o.frequency.value = freq;
-        g.gain.setValueAtTime(0.0001, t);
-        g.gain.exponentialRampToValueAtTime(Math.max(0.02, (vol || 0.2) * volume), t + 0.01);
-        g.gain.exponentialRampToValueAtTime(0.0001, t + dur);
-        let node = g;
-        if (pan != null && ac.createStereoPanner) {
-            const p = ac.createStereoPanner();
-            p.pan.value = Math.max(-1, Math.min(1, pan));
-            g.connect(p);
-            node = p;
+    function tonePan(freq, dur, cat, pan, vol, type, pc) {
+        if (!audible())
+            return;
+        const ac = contextFor(pc);
+        if (!ac)
+            return;
+        try {
+            const o = ac.createOscillator(), g = ac.createGain(), t = ac.currentTime;
+            o.type = type || 'sine';
+            o.frequency.value = freq;
+            g.gain.setValueAtTime(0.0001, t);
+            g.gain.exponentialRampToValueAtTime(Math.max(0.02, (vol || 0.2) * volume), t + 0.01);
+            g.gain.exponentialRampToValueAtTime(0.0001, t + dur);
+            o.connect(g);
+            panned(ac, g, pan).connect(outFor(ac, cat, pc));
+            o.start(t);
+            o.stop(t + dur + 0.02);
         }
-        o.connect(g);
-        node.connect(pc ? pc.out : (catNode(cat) || audioOut() || ac.destination));
-        o.start(t);
-        o.stop(t + dur + 0.02);
+        catch (e) { /* noop */ }
     }
-    catch (e) { /* noop */ }
-}
-// ===== Synth de RUÍDO (passos por material, bengala). noiseBuffer cacheia por-contexto (suporta AC por jogador). =====
-export let _footCount = 0; // contador de passos/pancadas (estatística de a11y; o __incl do game.js lê via getter)
-export function noiseBuffer(ac) { if (ac._noiseBuf && ac._noiseBuf.length === ((ac.sampleRate * 0.2) | 0))
-    return ac._noiseBuf; const n = (ac.sampleRate * 0.2) | 0, b = ac.createBuffer(1, n, ac.sampleRate), d = b.getChannelData(0); for (let i = 0; i < n; i++)
-    d[i] = Math.random() * 2 - 1; return ac._noiseBuf = b; }
-const FOOT = { grama: { f: 'highpass', hz: 2000, d: 0.09, v: 0.10 }, piso: { f: 'bandpass', hz: 1200, d: 0.06, v: 0.15 }, pedra: { f: 'highpass', hz: 1600, d: 0.05, v: 0.19 },
-    areia: { f: 'lowpass', hz: 650, d: 0.13, v: 0.10 }, madeira: { f: 'bandpass', hz: 480, d: 0.08, v: 0.15 }, ferro: { f: 'bandpass', hz: 2600, d: 0.12, v: 0.16 }, parede: { f: 'highpass', hz: 3200, d: 0.10, v: 0.08 },
-    terra: { f: 'lowpass', hz: 520, d: 0.11, v: 0.12 }, agua: { f: 'lowpass', hz: 330, d: 0.15, v: 0.13 } };
-export function noiseHit(mat, pan, pc) {
-    if (!soundOn || volume <= 0)
-        return;
-    const ac = pc ? pc.ac : ensureAC();
-    if (!ac)
-        return;
-    const f = FOOT[mat] || FOOT.piso;
-    try {
-        const src = ac.createBufferSource();
-        src.buffer = noiseBuffer(ac);
-        const bq = ac.createBiquadFilter();
-        bq.type = f.f;
-        bq.frequency.value = f.hz;
-        bq.Q.value = 1.2;
-        const g = ac.createGain(), t = ac.currentTime;
-        g.gain.setValueAtTime(0.0001, t);
-        g.gain.exponentialRampToValueAtTime(Math.max(0.02, f.v * volume), t + 0.006);
-        g.gain.exponentialRampToValueAtTime(0.0001, t + f.d);
-        let node = g;
-        if (pan != null && ac.createStereoPanner) {
-            const p = ac.createStereoPanner();
-            p.pan.value = Math.max(-1, Math.min(1, pan));
-            g.connect(p);
-            node = p;
+    // ===== The NOISE synth (footsteps by material, the cane). noiseBuffer caches per context (supports one per player). =====
+    function noiseHit(mat, pan, pc) {
+        if (!audible())
+            return;
+        const ac = contextFor(pc);
+        if (!ac)
+            return;
+        const f = FOOT[mat] || FOOT.piso;
+        try {
+            const src = ac.createBufferSource();
+            src.buffer = noiseBuffer(ac);
+            const bq = ac.createBiquadFilter();
+            bq.type = f.f;
+            bq.frequency.value = f.hz;
+            bq.Q.value = 1.2;
+            const g = ac.createGain(), t = ac.currentTime;
+            g.gain.setValueAtTime(0.0001, t);
+            g.gain.exponentialRampToValueAtTime(Math.max(0.02, f.v * volume), t + 0.006);
+            g.gain.exponentialRampToValueAtTime(0.0001, t + f.d);
+            src.connect(bq).connect(g);
+            panned(ac, g, pan).connect(outFor(ac, 'interact', pc));
+            src.start(t);
+            src.stop(t + f.d + 0.03);
+            footCount++;
         }
-        src.connect(bq).connect(g);
-        node.connect(pc ? pc.out : (catNode('interact') || audioOut() || ac.destination));
-        src.start(t);
-        src.stop(t + f.d + 0.03);
-        _footCount++;
+        catch (e) { /* noop */ }
     }
-    catch (e) { /* noop */ }
+    return {
+        get soundOn() { return soundOn; }, setSoundOn: (v) => { soundOn = v; },
+        get volume() { return volume; }, setVolume: (v) => { volume = v; },
+        get audioCtx() { return audioCtx; }, ensureAC, audioOut,
+        get hearingLoss() { return hearingLoss; }, setHearingLossGraph, setMasterMuted,
+        audioCat, catNode, setCatGain,
+        tone, tonePan, noiseHit,
+        get footCount() { return footCount; },
+    };
 }
-/* A TABELA DE EARCONS SAIU daqui em 2026-08-25 (item 19) — está em `game/earcons`.
- *
- * De dez earcons, sete eram deste jogo: `coin`/`key`/`gate`/`power` são objetos deste mundo e
- * `correct`/`wrong`/`place` são eventos da atividade. O gate acusava só a linha do `coin`, porque é a única
- * com palavra que o casador conhece — e a linha acusada era a menos interessante das dez.
- *
- * As legendas eram pt-BR CRU (`'🔊 Coletou'`, `'🔊 Portão abriu'`): nove frases dentro de um módulo de
- * plataforma, que o gate de i18n do `main.js` não alcança. Viraram CHAVES, e quem exibe resolve.
- *
- * O que ficou aqui é a SÍNTESE — oscilador, envelope, ruído, roteamento por categoria —, que serve a
- * qualquer jogo. O que é 880 Hz de triangular por 0,14 s ao pegar uma moeda, não. */
+/* What lives here is the SYNTHESIS — oscillator, envelope, noise, routing by category — which serves any game. A table of
+ * earcons does not: "880 Hz of triangle for 0.14 s when a coin is taken" is one game's world, and it lives with that game. */

package/dist-pkg/platform/flash-sampler.d.ts

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** What a measurement found. `passes` and `worstSecond` exist only when the canvas was actually read. */
+export interface FlashMeasurement {
+    readonly measured: boolean;
+    readonly reason?: string;
+    readonly passes?: boolean;
+    readonly worstSecond?: number;
+}
+export interface FlashSamplerCtx {
+    /** The world's canvas, read at the moment of the call — a `mount()` may have replaced the world. */
+    readonly canvas: () => HTMLCanvasElement | null;
+    /** A scratch canvas of our own: the world's is never resized, only copied from. */
+    readonly scratch: () => HTMLCanvasElement;
+    /** `requestAnimationFrame`, absent in a host that cannot animate — then there is nothing to sample over time. */
+    readonly frame?: (cb: (t: number) => void) => void;
+    /** Where a failure goes, so `problems` carries it for whoever reads the page's diagnosis. */
+    readonly report: (line: string) => void;
+}
+export declare function sampleFlashes(ctx: FlashSamplerCtx, ms: number): Promise<FlashMeasurement>;

package/dist-pkg/platform/flash-sampler.js

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/flash-sampler — READING THE WORLD'S CANVAS TO ANSWER WCAG 2.3.1 (study item B2; ADR-0027; issue #203).
+//
+// The pure half of this has lived in `core/flash-threshold` since it was written: given the luminance of a grid over time, it
+// says whether the general flash threshold is crossed. THIS is the half that has to touch a browser — copy the world's canvas
+// into a small one, read its pixels frame by frame, and turn them into the grid the pure half expects. It lived inside
+// `boot/create-game`, and it left for the reason ADR-0221 gives: 📏 that file reached 2185 lines and 330 decision nodes, and
+// the debt is paid by SUBJECT.
+//
+// ⚠️ IT ONLY RUNS WHEN IT IS CALLED, and that is a decision and not an omission: sampling a canvas every frame would cost a
+// school's machine the very thing the engine exists to protect. `Engine.measureFlashes(ms)` is how an adult asks.
+//
+// 📌 THE THREE REFUSALS ARE AS MUCH THE ANSWER AS THE MEASUREMENT, and each names what a developer must do: a world that is not
+// a canvas cannot be read at all; a host without `getImageData` or `requestAnimationFrame` cannot sample; and a canvas that
+// reads transparent in every frame is the WebGL case, where the buffer is thrown away unless `preserveDrawingBuffer` asked it
+// not to be. A silent `false` would have sent somebody looking for a flash that was never measured.
+import { analyseFlashes, COLUMNS, ROWS } from '../core/flash-threshold.js';
+/** Ten samples per cell of the pure half's grid — enough for an average, small enough to read every frame. */
+const SAMPLE_COLS = COLUMNS * 10;
+const SAMPLE_ROWS = ROWS * 10;
+/** sRGB → linear light, which is what a luminance average may be taken over (WCAG's own definition). */
+const linear = (v) => { const c = v / 255; return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; };
+export function sampleFlashes(ctx, ms) {
+    const canvas = ctx.canvas();
+    if (!canvas)
+        return Promise.resolve({ measured: false, reason: 'the world is not a canvas and contains none to read' });
+    const copy = ctx.scratch();
+    copy.width = SAMPLE_COLS;
+    copy.height = SAMPLE_ROWS;
+    const c2d = copy.getContext('2d', { willReadFrequently: true });
+    const frame = ctx.frame;
+    if (!c2d || typeof frame !== 'function')
+        return Promise.resolve({ measured: false, reason: 'this host cannot sample canvases' });
+    return new Promise((resolve) => {
+        const frames = [];
+        let start = -1;
+        let anyPixel = false;
+        const step = (now) => {
+            if (start < 0)
+                start = now;
+            let px;
+            try {
+                c2d.clearRect(0, 0, SAMPLE_COLS, SAMPLE_ROWS);
+                c2d.drawImage(canvas, 0, 0, SAMPLE_COLS, SAMPLE_ROWS);
+                px = c2d.getImageData(0, 0, SAMPLE_COLS, SAMPLE_ROWS).data;
+            }
+            catch {
+                resolve({ measured: false, reason: 'the page may not read the world\'s canvas (an image from another origin drew on it)' });
+                return;
+            }
+            const grid = new Float32Array(COLUMNS * ROWS);
+            for (let y = 0; y < SAMPLE_ROWS; y++) {
+                for (let x = 0; x < SAMPLE_COLS; x++) {
+                    const i = (y * SAMPLE_COLS + x) * 4;
+                    if (px[i + 3])
+                        anyPixel = true;
+                    const l = 0.2126 * linear(px[i]) + 0.7152 * linear(px[i + 1]) + 0.0722 * linear(px[i + 2]);
+                    grid[Math.floor(y / 10) * COLUMNS + Math.floor(x / 10)] += l / 100;
+                }
+            }
+            frames.push({ t: now - start, luminances: grid });
+            if (now - start < ms) {
+                frame(step);
+                return;
+            }
+            if (!anyPixel) {
+                resolve({ measured: false, reason: 'the world\'s canvas read transparent in every frame (WebGL canvases need preserveDrawingBuffer)' });
+                return;
+            }
+            const { passes: passed, worstSecond: worst } = analyseFlashes(frames);
+            if (!passed) {
+                ctx.report(`the world's canvas flashed ${worst} times in one second within a 10-degree field `
+                    + '(WCAG 2.3.1 allows 3): it can trigger a seizure in a child with photosensitive epilepsy — slow or dim it');
+            }
+            resolve({ measured: true, passes: passed, worstSecond: worst });
+        };
+        frame(step);
+    });
+}

package/dist-pkg/platform/guide-intensity.d.ts

@@ -1,40 +1,39 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** O que o guia soa, para uma dada distância. */
-export interface Intensidade {
-    /** Corte do passa-baixo, em hertz. Grave e abafado longe; aberto e brilhante perto. */
-    readonly corte: number;
-    /** Fator sobre o volume da categoria `guide`, entre `VOL_LONGE` e 1. NUNCA zero. */
+/** What the guide sounds like, for a given distance. */
+export interface Intensity {
+    /** The low-pass cutoff, in hertz. Low and muffled far away; open and bright up close. */
+    readonly cutoff: number;
+    /** A factor on the `guide` category's volume, between `FAR_VOL` and 1. NEVER zero. */
     readonly volume: number;
 }
 /**
- * A partir de quantos passos o guia deixa de escurecer mais.
+ * From how many steps on the guide stops getting darker.
  *
- * Doze, e o número não é novo: o `chaveDeDistancia` do sonar corta «muito perto» em 4 passos e «perto» em 9,
- * e o `PAN_PACES` satura o estéreo em 11. O guia satura logo depois — a informação fina serve para quem já
- * está a chegar, e mais longe do que isso «longe» basta.
+ * Twelve, and the number is not new: the sonar's distance words cut "very near" at 4 steps and "near" at 9, and its pan
+ * saturates the stereo at 11. The guide saturates just after — fine detail serves whoever is arriving, and beyond that
+ * "far" is enough.
  */
-export declare const PASSOS_ATE_O_FUNDO = 12;
-/** O corte no fundo da escala: abafado, presente, sem ser um som de alarme. */
-export declare const CORTE_LONGE = 320;
-/** O corte no alvo: aberto. Acima disto o timbre passa a sibilar, e sibilar chama atenção como um bipe. */
-export declare const CORTE_PERTO = 3200;
+export declare const STEPS_TO_FLOOR = 12;
+/** The cutoff at the bottom of the scale: muffled, present, never an alarm sound. */
+export declare const FAR_CUT = 320;
+/** The cutoff at the target: open. Above this the timbre starts to hiss, and a hiss draws attention like a beep. */
+export declare const NEAR_CUT = 3200;
 /**
- * O fator de volume mais baixo.
+ * The lowest volume factor.
  *
- * ⚠️ NUNCA ZERO, E É A ASSERÇÃO MAIS IMPORTANTE DESTE FICHEIRO. Se o guia emudecesse ao longe, «longe» ficaria
- * indistinguível de «não há alvo» — e a criança que depende dele concluiria que não há nada para achar,
- * exatamente quando há e está distante. Silêncio é uma afirmação, e aqui seria uma afirmação falsa.
+ * ⚠️ NEVER ZERO, AND IT IS THE MOST IMPORTANT ASSERTION IN THIS FILE. If the guide went mute far away, "far" would be
+ * indistinguishable from "there is no target" — and the child who depends on it would conclude there is nothing to find,
+ * exactly when there is and it is distant. Silence is a statement, and here it would be a false one.
  */
-export declare const VOL_LONGE = 0.55;
+export declare const FAR_VOL = 0.55;
 /**
- * A intensidade para `passos` de distância ao longo da rota.
+ * The intensity for `stepsAway` steps along the route.
  *
- * ⚠️ A INTERPOLAÇÃO DO CORTE É EXPONENCIAL, e não linear, pelo mesmo motivo do earcon da #124: o ouvido
- * percebe altura e brilho em RAZÃO, não em diferença. Uma rampa linear de 320 a 3200 abriria quase tudo no
- * primeiro terço do caminho e depois pareceria parada — a criança sentiria que chegou quando ainda faltava
- * metade.
+ * ⚠️ THE CUTOFF INTERPOLATES EXPONENTIALLY, not linearly, for the reason of #124's earcon: the ear perceives pitch and
+ * brightness as a RATIO, not a difference. A linear ramp from 320 to 3200 would open almost everything in the first third
+ * of the way and then seem to stand still — the child would feel they had arrived with half the way to go.
  *
- * O volume interpola LINEARMENTE, e a assimetria é deliberada: ele é o eixo secundário, e uma curva também
- * exponencial ali faria os dois acelerarem no mesmo ponto, que é o oposto de ter dois eixos.
+ * The volume interpolates LINEARLY, and the asymmetry is deliberate: it is the secondary axis, and an exponential curve
+ * there too would make both accelerate at the same point, the opposite of having two axes.
  */
-export declare function intensidadeDoGuia(passos: number): Intensidade;
+export declare function guideIntensity(stepsAway: number): Intensity;