@jgengine/shell 0.9.0 → 0.10.0

package/dist/audio/audioEngine.d.ts

@@ -1,4 +1,6 @@
 import { type AudioBusDef, type SoundDef } from "@jgengine/core/audio/audioFalloff";
+import type { MusicTheme } from "@jgengine/core/audio/music";
+import { type CrossfadeOptions } from "./musicDirector.js";
 export interface Vec3 {
     x: number;
     y: number;
@@ -7,6 +9,10 @@ export interface Vec3 {
 export interface AudioSceneConfig {
     sounds?: Record<string, SoundDef>;
     buses?: Record<string, AudioBusDef>;
+    /** Procedural music themes, crossfaded by {@link AudioEngine.playMusic}. Mixed through the `musicBus` (default "music") so the settings volume applies. */
+    music?: Record<string, MusicTheme>;
+    /** Bus id the procedural music director mixes through. Default "music". */
+    musicBus?: string;
 }
 export interface AudioEmitterHandle {
     setPosition(position: Vec3): void;
@@ -16,6 +22,8 @@ export interface AudioEngine {
     setListenerPose(position: Vec3): void;
     playOneShot(soundId: string, position?: Vec3): void;
     playLoop(soundId: string, position?: Vec3): AudioEmitterHandle | null;
+    /** Crossfade the procedural soundtrack to `themeId` (null fades out). No-op when no `music` catalog is configured. */
+    playMusic(themeId: string | null, options?: CrossfadeOptions): void;
     setBusGain(busId: string, gain: number): void;
     setMasterGain(gain: number): void;
     resume(): void;

package/dist/audio/audioEngine.js

@@ -1,9 +1,12 @@
 import { distance3, resolveEmitterGain } from "@jgengine/core/audio/audioFalloff";
+import { MusicDirector } from "./musicDirector.js";
+import { createNoiseBuffer, realizeSynthPatch } from "./synthEngine.js";
 function createNoopEngine() {
     return {
         setListenerPose: () => undefined,
         playOneShot: () => undefined,
         playLoop: () => null,
+        playMusic: () => undefined,
         setBusGain: () => undefined,
         setMasterGain: () => undefined,
         resume: () => undefined,
@@ -43,6 +46,21 @@ export function createAudioEngine(config = {}) {
         }
         return node;
     }
+    let noiseBuffer = null;
+    function sharedNoiseBuffer() {
+        if (noiseBuffer === null)
+            noiseBuffer = createNoiseBuffer(context);
+        return noiseBuffer;
+    }
+    let director = null;
+    function musicDirector() {
+        if (config.music === undefined)
+            return null;
+        if (director === null) {
+            director = new MusicDirector(context, busGainNode(config.musicBus ?? "music"), config.music);
+        }
+        return director;
+    }
     const bufferCache = new Map();
     function loadBuffer(url) {
         let pending = bufferCache.get(url);
@@ -62,6 +80,15 @@ export function createAudioEngine(config = {}) {
             return null;
         const bus = busGainNode(sound.bus);
         let currentPosition = position ?? listenerPosition;
+        if (sound.synth !== undefined) {
+            const cueGain = context.createGain();
+            cueGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
+            cueGain.connect(bus);
+            realizeSynthPatch(context, cueGain, sharedNoiseBuffer(), sound.synth);
+            return { setPosition: () => undefined, stop: () => undefined };
+        }
+        if (sound.url === undefined)
+            return null;
         let gainNode = null;
         let stopped = false;
         void loadBuffer(sound.url).then((buffer) => {
@@ -93,11 +120,16 @@ export function createAudioEngine(config = {}) {
             listenerPosition = position;
         },
         playOneShot(soundId, position) {
+            void context.resume().catch(() => undefined);
             playInternal(soundId, position, false);
         },
         playLoop(soundId, position) {
             return playInternal(soundId, position, true);
         },
+        playMusic(themeId, options) {
+            void context.resume().catch(() => undefined);
+            musicDirector()?.crossfadeTo(themeId, options);
+        },
         setBusGain(busId, gain) {
             busGainNode(busId).gain.value = gain;
         },
@@ -108,6 +140,7 @@ export function createAudioEngine(config = {}) {
             void context.resume().catch(() => undefined);
         },
         dispose() {
+            director?.dispose();
             void context.close().catch(() => undefined);
         },
     };

package/dist/audio/musicDirector.d.ts

@@ -0,0 +1,31 @@
+import { type MusicTheme } from "@jgengine/core/audio/music";
+/** Options for a music crossfade. */
+export interface CrossfadeOptions {
+    /** Semitone shift applied to every note of the incoming theme (per-zone key). Default 0. */
+    transpose?: number;
+}
+/**
+ * Runs a set of looping {@link MusicTheme}s as crossfadeable layers on one shared
+ * Web Audio graph: master → compressor → destination, with a fixed convolution
+ * reverb send. `crossfadeTo` swaps the audible theme; a 110ms lookahead scheduler
+ * keeps each active layer's notes queued ahead of the clock so loops are seamless.
+ */
+export declare class MusicDirector {
+    private readonly ctx;
+    private readonly master;
+    private readonly reverbSend;
+    private readonly layers;
+    private timer;
+    private volume;
+    private current;
+    constructor(ctx: BaseAudioContext, destination: AudioNode, themes: Record<string, MusicTheme>);
+    /** The currently faded-in theme id, or null when music is stopped. */
+    currentTheme(): string | null;
+    /** Fade to `themeId` (or fade all out when null). No-op if it is already current. */
+    crossfadeTo(themeId: string | null, options?: CrossfadeOptions): void;
+    /** Music volume 0..1, scaling the master gain. */
+    setVolume(volume: number): void;
+    /** Stop the scheduler and release the graph. */
+    dispose(): void;
+    private tick;
+}

package/dist/audio/musicDirector.js

@@ -0,0 +1,125 @@
+import { notesInWindow, themeLoopSeconds } from "@jgengine/core/audio/music";
+import { playMusicNote } from "./musicVoices.js";
+const LOOKAHEAD = 0.6;
+const TICK_MS = 110;
+const FADE_IN = 0.75;
+const FADE_OUT = 0.35;
+const MASTER_BASE = 0.2;
+/**
+ * Runs a set of looping {@link MusicTheme}s as crossfadeable layers on one shared
+ * Web Audio graph: master → compressor → destination, with a fixed convolution
+ * reverb send. `crossfadeTo` swaps the audible theme; a 110ms lookahead scheduler
+ * keeps each active layer's notes queued ahead of the clock so loops are seamless.
+ */
+export class MusicDirector {
+    ctx;
+    master;
+    reverbSend;
+    layers = new Map();
+    timer;
+    volume = 1;
+    current = null;
+    constructor(ctx, destination, themes) {
+        this.ctx = ctx;
+        this.master = ctx.createGain();
+        this.master.gain.value = MASTER_BASE;
+        const compressor = ctx.createDynamicsCompressor();
+        compressor.threshold.value = -18;
+        compressor.knee.value = 18;
+        compressor.ratio.value = 2.2;
+        compressor.attack.value = 0.015;
+        compressor.release.value = 0.25;
+        this.master.connect(compressor);
+        compressor.connect(destination);
+        const irSeconds = 2.6;
+        const len = Math.floor(ctx.sampleRate * irSeconds);
+        const ir = ctx.createBuffer(2, len, ctx.sampleRate);
+        for (let ch = 0; ch < 2; ch += 1) {
+            const data = ir.getChannelData(ch);
+            for (let i = 0; i < len; i += 1)
+                data[i] = (Math.random() * 2 - 1) * (1 - i / len) ** 2.4;
+        }
+        const reverb = ctx.createConvolver();
+        reverb.buffer = ir;
+        this.reverbSend = ctx.createGain();
+        this.reverbSend.gain.value = 0.55;
+        this.reverbSend.connect(reverb);
+        reverb.connect(this.master);
+        for (const [id, theme] of Object.entries(themes)) {
+            const gain = ctx.createGain();
+            gain.gain.value = 0;
+            gain.connect(this.master);
+            gain.connect(this.reverbSend);
+            this.layers.set(id, {
+                theme,
+                gain,
+                trim: theme.trim ?? 1,
+                active: false,
+                target: 0,
+                anchor: 0,
+                nextFrom: 0,
+                transpose: 0,
+            });
+        }
+        if (typeof setInterval === "function") {
+            this.timer = setInterval(() => this.tick(), TICK_MS);
+        }
+    }
+    /** The currently faded-in theme id, or null when music is stopped. */
+    currentTheme() {
+        return this.current;
+    }
+    /** Fade to `themeId` (or fade all out when null). No-op if it is already current. */
+    crossfadeTo(themeId, options = {}) {
+        if (themeId === this.current)
+            return;
+        this.current = themeId;
+        const now = this.ctx.currentTime;
+        for (const [id, layer] of this.layers) {
+            const target = id === themeId ? layer.trim : 0;
+            if (layer.target === target)
+                continue;
+            const rising = target > layer.target;
+            layer.target = target;
+            layer.gain.gain.setTargetAtTime(target, now, rising ? FADE_IN : FADE_OUT);
+            if (rising) {
+                layer.active = true;
+                layer.anchor = now + 0.15;
+                layer.nextFrom = layer.anchor - 1e-6;
+                layer.transpose = options.transpose ?? 0;
+            }
+            else {
+                layer.active = false;
+            }
+        }
+    }
+    /** Music volume 0..1, scaling the master gain. */
+    setVolume(volume) {
+        this.volume = Math.max(0, volume);
+        this.master.gain.value = MASTER_BASE * this.volume;
+    }
+    /** Stop the scheduler and release the graph. */
+    dispose() {
+        if (this.timer !== undefined)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        this.master.disconnect();
+        this.reverbSend.disconnect();
+    }
+    tick() {
+        const horizon = this.ctx.currentTime + LOOKAHEAD;
+        const spbAvailable = 60;
+        for (const layer of this.layers.values()) {
+            if (!layer.active)
+                continue;
+            if (themeLoopSeconds(layer.theme) <= 0)
+                continue;
+            const spb = spbAvailable / layer.theme.bpm;
+            const notes = notesInWindow(layer.theme, layer.anchor, layer.nextFrom, horizon);
+            for (const { event, when } of notes) {
+                playMusicNote(this.ctx, event, when, spb, layer.gain, layer.transpose);
+            }
+            layer.nextFrom = horizon;
+        }
+    }
+}

package/dist/audio/musicVoices.d.ts

@@ -0,0 +1,10 @@
+import { type NoteEvent } from "@jgengine/core/audio/music";
+type Ctx = BaseAudioContext;
+/**
+ * Play one theme note through its instrument voice into `out` (a per-layer gain
+ * node the director wires to master + reverb). `spb` is seconds-per-beat and
+ * `transpose` shifts the note in semitones for per-zone key changes. This is the
+ * engine's reusable instrument library; unknown instruments fall back to a sine.
+ */
+export declare function playMusicNote(ctx: Ctx, event: NoteEvent, when: number, spb: number, out: GainNode, transpose?: number): void;
+export {};

package/dist/audio/musicVoices.js

@@ -0,0 +1,338 @@
+import { mtof } from "@jgengine/core/audio/music";
+function adsr(ctx, when, dur, peak, attack, release) {
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(0.0001, when);
+    g.gain.linearRampToValueAtTime(peak, when + attack);
+    g.gain.setValueAtTime(peak, Math.max(when + attack, when + dur - release));
+    g.gain.exponentialRampToValueAtTime(0.0001, when + dur + release);
+    return g;
+}
+function stack(ctx, when, freq, dur, out, type, dets, tail) {
+    for (const det of dets) {
+        const o = ctx.createOscillator();
+        o.type = type;
+        o.frequency.value = freq;
+        o.detune.value = det;
+        o.connect(out);
+        o.start(when);
+        o.stop(when + dur + tail);
+    }
+}
+function strings(ctx, when, freq, dur, vel, out, attack = 0.3) {
+    const g = adsr(ctx, when, dur, vel * 0.16, attack, 0.7);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 750 + freq * 2;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, dur, lp, "sawtooth", [-6, 5], 0.9);
+}
+function pad(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.11, 0.6, 1.1);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 520 + freq * 1.4;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, dur, lp, "sawtooth", [-9, -3, 4, 10], 1.2);
+}
+function reed(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.14, 0.08, 0.25);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 1600 + freq;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, dur, lp, "sawtooth", [-3, 4], 0.35);
+}
+function horn(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.15, 0.09, 0.3);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 900 + freq * 1.5;
+    lp.Q.value = 0.6;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, dur, lp, "sawtooth", [-4, 3], 0.4);
+    const sub = ctx.createOscillator();
+    sub.type = "sine";
+    sub.frequency.value = freq;
+    const sg = ctx.createGain();
+    sg.gain.value = 0.4;
+    sub.connect(sg).connect(lp);
+    sub.start(when);
+    sub.stop(when + dur + 0.4);
+}
+function brassStab(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, Math.min(dur, 0.4), vel * 0.17, 0.02, 0.14);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 1400 + freq * 2;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, Math.min(dur, 0.4), lp, "sawtooth", [-5, 6], 0.2);
+}
+function flute(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.15, 0.06, 0.2);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 2600;
+    lp.connect(g).connect(out);
+    const o = ctx.createOscillator();
+    o.type = "sine";
+    o.frequency.value = freq;
+    o.connect(lp);
+    o.start(when);
+    o.stop(when + dur + 0.25);
+    const breath = ctx.createBufferSource();
+    const len = Math.floor(ctx.sampleRate * Math.min(dur, 0.4));
+    const buf = ctx.createBuffer(1, len, ctx.sampleRate);
+    const data = buf.getChannelData(0);
+    for (let i = 0; i < len; i += 1)
+        data[i] = (Math.random() * 2 - 1) * 0.5;
+    breath.buffer = buf;
+    const bp = ctx.createBiquadFilter();
+    bp.type = "bandpass";
+    bp.frequency.value = freq * 2;
+    const bg = ctx.createGain();
+    bg.gain.value = vel * 0.02;
+    breath.connect(bp).connect(bg).connect(out);
+    breath.start(when);
+}
+function pipe(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.13, 0.03, 0.15);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 3000;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, dur, lp, "triangle", [0, 7], 0.2);
+}
+function squareLead(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.1, 0.02, 0.12);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 2200 + freq;
+    lp.connect(g).connect(out);
+    const o = ctx.createOscillator();
+    o.type = "square";
+    o.frequency.value = freq;
+    o.connect(lp);
+    o.start(when);
+    o.stop(when + dur + 0.2);
+}
+function choir(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.12, 0.25, 0.6);
+    const formant = ctx.createBiquadFilter();
+    formant.type = "bandpass";
+    formant.frequency.value = Math.min(1800, 500 + freq * 1.6);
+    formant.Q.value = 0.7;
+    formant.connect(g).connect(out);
+    stack(ctx, when, freq, dur, formant, "sawtooth", [-8, -2, 6], 0.8);
+    stack(ctx, when, freq * 2, dur, formant, "triangle", [3], 0.8);
+}
+function oboe(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.17, 0.055, 0.22);
+    const formant = ctx.createBiquadFilter();
+    formant.type = "bandpass";
+    formant.frequency.value = Math.min(2400, 600 + freq * 2.2);
+    formant.Q.value = 0.9;
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 2800;
+    formant.connect(lp).connect(g).connect(out);
+    const vib = ctx.createOscillator();
+    vib.frequency.value = 5.2;
+    const vibGain = ctx.createGain();
+    vibGain.gain.setValueAtTime(0, when);
+    vibGain.gain.linearRampToValueAtTime(freq * 0.004, when + 0.3);
+    vib.connect(vibGain);
+    for (const det of [-5, 4]) {
+        const o = ctx.createOscillator();
+        o.type = "sawtooth";
+        o.frequency.value = freq;
+        o.detune.value = det;
+        vibGain.connect(o.frequency);
+        o.connect(formant);
+        o.start(when);
+        o.stop(when + dur + 0.4);
+    }
+    vib.start(when);
+    vib.stop(when + dur + 0.4);
+}
+function pluck(ctx, when, freq, vel, out, decay, bassy = false) {
+    const g = ctx.createGain();
+    const peak = vel * (bassy ? 0.26 : 0.2);
+    g.gain.setValueAtTime(0.0001, when);
+    g.gain.linearRampToValueAtTime(peak, when + 0.004);
+    g.gain.exponentialRampToValueAtTime(0.0001, when + decay);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = bassy ? 900 : 2600 + freq;
+    lp.connect(g).connect(out);
+    const o = ctx.createOscillator();
+    o.type = bassy ? "triangle" : "sawtooth";
+    o.frequency.value = freq;
+    o.connect(lp);
+    o.start(when);
+    o.stop(when + decay + 0.1);
+    if (!bassy) {
+        const o2 = ctx.createOscillator();
+        o2.type = "triangle";
+        o2.frequency.value = freq * 2.001;
+        const g2 = ctx.createGain();
+        g2.gain.setValueAtTime(peak * 0.4, when);
+        g2.gain.exponentialRampToValueAtTime(0.0001, when + decay * 0.6);
+        o2.connect(g2).connect(out);
+        o2.start(when);
+        o2.stop(when + decay);
+    }
+}
+function bell(ctx, when, freq, vel, out, decay = 1.8) {
+    for (const [ratio, amp] of [[1, 1], [2.76, 0.5], [5.4, 0.25], [8.9, 0.12]]) {
+        const g = ctx.createGain();
+        g.gain.setValueAtTime(0.0001, when);
+        g.gain.linearRampToValueAtTime(vel * 0.14 * amp, when + 0.005);
+        g.gain.exponentialRampToValueAtTime(0.0001, when + decay * (1 - (ratio - 1) * 0.06));
+        const o = ctx.createOscillator();
+        o.type = "sine";
+        o.frequency.value = freq * ratio;
+        o.connect(g).connect(out);
+        o.start(when);
+        o.stop(when + decay + 0.2);
+    }
+}
+function piano(ctx, when, freq, dur, vel, out) {
+    const naturalDecay = Math.min(5.2, Math.max(1.2, 380 / freq));
+    const body = ctx.createBiquadFilter();
+    body.type = "lowpass";
+    body.frequency.value = Math.min(5600, 1400 + freq * 4);
+    body.Q.value = 0.35;
+    body.connect(out);
+    const partials = [
+        [1, 0.62, 1, -3],
+        [1.0005, 0.62, 1, 3],
+        [2.003, 0.5, 0.58, 2],
+        [3.006, 0.2, 0.36, -4],
+        [4.012, 0.09, 0.24, 5],
+        [5.02, 0.05, 0.17, -6],
+        [7.03, 0.025, 0.12, 4],
+    ];
+    for (const [ratio, amp, decayMul, cents] of partials) {
+        const decay = Math.min(naturalDecay * decayMul, dur + 0.35);
+        const g = ctx.createGain();
+        const peak = vel * 0.24 * amp;
+        g.gain.setValueAtTime(0.0001, when);
+        g.gain.linearRampToValueAtTime(peak, when + 0.004);
+        g.gain.exponentialRampToValueAtTime(0.0001, when + Math.max(0.14, decay));
+        const o = ctx.createOscillator();
+        o.type = ratio < 1.01 ? "triangle" : "sine";
+        o.frequency.value = freq * ratio;
+        o.detune.value = cents;
+        o.connect(g).connect(body);
+        o.start(when);
+        o.stop(when + Math.max(0.14, decay) + 0.1);
+    }
+}
+function noiseHit(ctx, when, vel, out, hp, len, curve) {
+    const n = Math.floor(ctx.sampleRate * len);
+    const buf = ctx.createBuffer(1, n, ctx.sampleRate);
+    const data = buf.getChannelData(0);
+    for (let i = 0; i < n; i += 1)
+        data[i] = (Math.random() * 2 - 1) * (1 - i / n) ** curve;
+    const src = ctx.createBufferSource();
+    src.buffer = buf;
+    const f = ctx.createBiquadFilter();
+    f.type = "highpass";
+    f.frequency.value = hp;
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(vel * 0.22, when);
+    g.gain.exponentialRampToValueAtTime(0.0001, when + len);
+    src.connect(f).connect(g).connect(out);
+    src.start(when);
+}
+function drum(ctx, when, freq, vel, out, decay, punch) {
+    const o = ctx.createOscillator();
+    o.type = "sine";
+    o.frequency.setValueAtTime(freq * punch, when);
+    o.frequency.exponentialRampToValueAtTime(freq, when + 0.06);
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(vel * 0.5, when);
+    g.gain.exponentialRampToValueAtTime(0.0001, when + decay);
+    o.connect(g).connect(out);
+    o.start(when);
+    o.stop(when + decay + 0.05);
+    noiseHit(ctx, when, vel * 0.4, out, 200, Math.min(decay, 0.12), 2);
+}
+function woodBlock(ctx, when, vel, out) {
+    const o = ctx.createOscillator();
+    o.type = "square";
+    o.frequency.value = 1100;
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(vel * 0.2, when);
+    g.gain.exponentialRampToValueAtTime(0.0001, when + 0.05);
+    const bp = ctx.createBiquadFilter();
+    bp.type = "bandpass";
+    bp.frequency.value = 1100;
+    o.connect(bp).connect(g).connect(out);
+    o.start(when);
+    o.stop(when + 0.07);
+}
+function cymSwell(ctx, when, dur, vel, out) {
+    const n = Math.floor(ctx.sampleRate * (dur + 0.3));
+    const buf = ctx.createBuffer(1, n, ctx.sampleRate);
+    const data = buf.getChannelData(0);
+    for (let i = 0; i < n; i += 1)
+        data[i] = Math.random() * 2 - 1;
+    const src = ctx.createBufferSource();
+    src.buffer = buf;
+    const hp = ctx.createBiquadFilter();
+    hp.type = "highpass";
+    hp.frequency.value = 6000;
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(0.0001, when);
+    g.gain.linearRampToValueAtTime(vel * 0.1, when + dur);
+    g.gain.exponentialRampToValueAtTime(0.0001, when + dur + 0.3);
+    src.connect(hp).connect(g).connect(out);
+    src.start(when);
+}
+/**
+ * Play one theme note through its instrument voice into `out` (a per-layer gain
+ * node the director wires to master + reverb). `spb` is seconds-per-beat and
+ * `transpose` shifts the note in semitones for per-zone key changes. This is the
+ * engine's reusable instrument library; unknown instruments fall back to a sine.
+ */
+export function playMusicNote(ctx, event, when, spb, out, transpose = 0) {
+    const freq = mtof(event.midi + transpose);
+    const dur = Math.max(0.1, event.dur * spb);
+    const vel = event.vel;
+    const inst = event.inst;
+    switch (inst) {
+        case "strings": return strings(ctx, when, freq, dur, vel, out);
+        case "stacc": return strings(ctx, when, freq, Math.min(dur, 0.22), vel, out, 0.02);
+        case "pad": return pad(ctx, when, freq, dur, vel, out);
+        case "reed": return reed(ctx, when, freq, dur, vel, out);
+        case "horn": return horn(ctx, when, freq, dur, vel, out);
+        case "brassStab": return brassStab(ctx, when, freq, dur, vel, out);
+        case "flute": return flute(ctx, when, freq, dur, vel, out);
+        case "pipe": return pipe(ctx, when, freq, dur, vel, out);
+        case "squareLead": return squareLead(ctx, when, freq, dur, vel, out);
+        case "choir": return choir(ctx, when, freq, dur, vel, out);
+        case "oboe": return oboe(ctx, when, freq, dur, vel, out);
+        case "harp": return pluck(ctx, when, freq, vel, out, 1.4);
+        case "lute": return pluck(ctx, when, freq, vel, out, 0.7);
+        case "dulcimer": return pluck(ctx, when, freq, vel, out, 1.0);
+        case "bass": return pluck(ctx, when, freq, vel, out, 0.9, true);
+        case "bell": return bell(ctx, when, freq, vel, out);
+        case "tinyBell": return bell(ctx, when, freq, vel, out, 0.7);
+        case "piano": return piano(ctx, when, freq, dur, vel, out);
+        case "timpani": return drum(ctx, when, freq, vel, out, 0.6, 1.5);
+        case "warDrum": return drum(ctx, when, Math.max(50, freq * 0.5), vel, out, 0.35, 1.8);
+        case "frameDrum": return drum(ctx, when, Math.max(70, freq * 0.6), vel, out, 0.25, 1.6);
+        case "shaker": return noiseHit(ctx, when, vel, out, 6800, 0.055, 1.8);
+        case "woodBlock": return woodBlock(ctx, when, vel, out);
+        case "cymSwell": return cymSwell(ctx, when, dur, vel, out);
+        default: {
+            const o = ctx.createOscillator();
+            o.frequency.value = freq;
+            const g = adsr(ctx, when, dur, vel * 0.12, 0.02, 0.2);
+            o.connect(g).connect(out);
+            o.start(when);
+            o.stop(when + dur + 0.3);
+        }
+    }
+}

package/dist/audio/synthEngine.d.ts

@@ -0,0 +1,9 @@
+import type { SynthPatch } from "@jgengine/core/audio/synth";
+/** Build the shared 1-second mono white-noise buffer every noise voice samples from. */
+export declare function createNoiseBuffer(ctx: BaseAudioContext): AudioBuffer;
+/**
+ * Realise a procedural cue on Web Audio: every voice is scheduled at
+ * `ctx.currentTime + delay` into `out`, summed into one one-shot. `noiseBuf` is
+ * the shared buffer from {@link createNoiseBuffer}.
+ */
+export declare function realizeSynthPatch(ctx: BaseAudioContext, out: AudioNode, noiseBuf: AudioBuffer, patch: SynthPatch): void;

package/dist/audio/synthEngine.js

@@ -0,0 +1,57 @@
+/** Build the shared 1-second mono white-noise buffer every noise voice samples from. */
+export function createNoiseBuffer(ctx) {
+    const len = Math.floor(ctx.sampleRate);
+    const buf = ctx.createBuffer(1, len, ctx.sampleRate);
+    const data = buf.getChannelData(0);
+    for (let i = 0; i < len; i += 1)
+        data[i] = Math.random() * 2 - 1;
+    return buf;
+}
+function realizeTone(ctx, out, voice, cueGain, at) {
+    const t = at + (voice.delay ?? 0);
+    const peak = (voice.gain ?? 1) * cueGain;
+    const attack = voice.attack ?? 0.012;
+    const osc = ctx.createOscillator();
+    osc.type = voice.wave ?? "sine";
+    osc.frequency.setValueAtTime(voice.freq, t);
+    if (voice.slideTo !== undefined)
+        osc.frequency.exponentialRampToValueAtTime(Math.max(1, voice.slideTo), t + voice.duration);
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(0, t);
+    g.gain.linearRampToValueAtTime(peak, t + attack);
+    g.gain.exponentialRampToValueAtTime(0.001, t + voice.duration);
+    osc.connect(g).connect(out);
+    osc.start(t);
+    osc.stop(t + voice.duration + 0.05);
+}
+function realizeNoise(ctx, out, noiseBuf, voice, cueGain, at) {
+    const t = at + (voice.delay ?? 0);
+    const peak = (voice.gain ?? 1) * cueGain;
+    const decay = voice.decay ?? 0.9;
+    const src = ctx.createBufferSource();
+    src.buffer = noiseBuf;
+    src.playbackRate.value = 0.8 + Math.random() * 0.4;
+    const filter = ctx.createBiquadFilter();
+    filter.type = voice.filterType ?? "lowpass";
+    filter.frequency.value = voice.filterFreq;
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(peak, t);
+    g.gain.exponentialRampToValueAtTime(0.001, t + voice.duration * decay);
+    src.connect(filter).connect(g).connect(out);
+    src.start(t, Math.random() * 0.5, voice.duration);
+}
+/**
+ * Realise a procedural cue on Web Audio: every voice is scheduled at
+ * `ctx.currentTime + delay` into `out`, summed into one one-shot. `noiseBuf` is
+ * the shared buffer from {@link createNoiseBuffer}.
+ */
+export function realizeSynthPatch(ctx, out, noiseBuf, patch) {
+    const cueGain = patch.gain ?? 1;
+    const at = ctx.currentTime;
+    for (const voice of patch.voices) {
+        if (voice.kind === "tone")
+            realizeTone(ctx, out, voice, cueGain, at);
+        else
+            realizeNoise(ctx, out, noiseBuf, voice, cueGain, at);
+    }
+}

package/dist/camera/GameFirstPersonCamera.d.ts

@@ -1,5 +1,8 @@
 import { type MutableRefObject } from "react";
+import * as THREE from "three";
 import type { FirstPersonCameraConfig } from "@jgengine/core/game/playableGame";
+/** World position of the first-person weapon muzzle, or false when no viewmodel is mounted. */
+export declare function readFirstPersonMuzzle(target: THREE.Vector3): boolean;
 export interface GameFirstPersonCameraProps {
     yawRef: MutableRefObject<number>;
     pitchRef: MutableRefObject<number>;