@real-music-packages/web-core 0.11.0 → 0.13.0

package/README.md

@@ -36,6 +36,31 @@ peers; OSMD is only loaded via a dynamic import). Pure helpers (`parseMidi`,
 - **`renderNotation(xml, opts?)`** — renders a MusicXML string via OSMD to a detached canvas; returns per-staff measure boxes (RSR geometry), per-measure column union boxes (RMT geometry), system rows, and content bounds. Parameterisable via `RenderNotationOpts` (paper, inkSumThreshold, hostWidth, bars).
 - **`createPromoSampler(opts?)`** — creates a Tone.js Salamander sampler wired to a `MediaStreamDestination`. `keepAlive` option feeds a silent ConstantSource so the recorder never drops silent intro scenes (default false; RMT passes true).
 
+### `./scene`
+Render-components: the Score model (`scoreFromMusicXML`), the Layer contract +
+SceneSpec runner, and the built-in layers (notation, scroll-cursor, keyboard,
+falling-notes, promo cards, spectrum, branding, and the S5 extended catalog).
+
+This barrel is **browser-safe** — it pulls in no Node-only dependencies, so
+Vite/rolldown consumers need **no aliases**. `scoreFromMusicXML` runs unchanged in
+the browser (native canvas handles OSMD's lyric layout).
+
+### `./scene/headless` (Node-only)
+`setupHeadlessDom()` — installs `jsdom` globals + a fake 2D canvas context so OSMD
+can `load()` a score outside a browser (CI, batch, audio-only paths). Import it
+**only in Node**, and call it once before `scoreFromMusicXML` (or pass
+`opts.osmdFactory`):
+
+```ts
+import { setupHeadlessDom } from '@real-music-packages/web-core/scene/headless'; // Node only
+import { scoreFromMusicXML } from '@real-music-packages/web-core/scene';
+await setupHeadlessDom();
+const score = scoreFromMusicXML(xml);
+```
+
+This subpath references `jsdom` and must never be imported from browser code. It
+lives here (not in `./scene`) precisely so the `./scene` barrel stays bundler-safe.
+
 ## ⚠️ Octave-base gotcha (`scales.getMidiNote` / `getScaleDegree`)
 These are ported verbatim from RealEarTrainer and use **RET's non-standard octave
 base**: `getMidiNote(1, 'C', 4) === 48`, i.e. one octave below the General-MIDI

package/dist/audio.d.ts

@@ -132,6 +132,42 @@ declare class AudioEngine {
      * Check if audio is ready
      */
     get isReady(): boolean;
+    /**
+     * Current audio-clock time in SECONDS (`Tone.now()`), or 0 before init.
+     *
+     * The scheduling seam for web-core's per-segment audio hook
+     * (`@real-music-packages/web-core/scene` → `recordSceneSpec`'s `segmentAudio`
+     * / `BuiltScene.scheduleAudio`). Pair it with `instrument` so an
+     * AudioEngine-driven app (RET) can satisfy `segmentAudio` exactly like a
+     * raw promo sampler does — `{ instrument: engine.instrument, audioNow: () => engine.audioNow() }`.
+     */
+    audioNow(): number;
+    /**
+     * A `ScheduleTarget`-shaped view of the active piano voice: an object whose
+     * `triggerAttackRelease(note, dur, time?, velocity?)` forwards to the current
+     * voice (synth, upgrading to the Salamander sampler when it loads). Unlike
+     * `playNote`/`playChord` — which hard-code `Tone.now()` — this accepts an
+     * explicit absolute `time`, which is what offline/deterministic capture needs.
+     *
+     * This is the seam web-core's runner consumes: `segmentAudio.instrument =
+     * engine.instrument`. The declarative `SegmentAudio.schedule` path drives this
+     * via `applySchedule`; the imperative `onEnter` path can call it directly, or
+     * use the `scheduleNoteAt` / `scheduleChordAt` convenience wrappers below.
+     */
+    get instrument(): {
+        triggerAttackRelease: (note: unknown, dur: unknown, time?: unknown, velocity?: unknown) => void;
+    };
+    /**
+     * Schedule a single MIDI note to sound at an explicit absolute audio-clock
+     * time (seconds). The capture-clock counterpart of `playNote` — use it inside
+     * a segment's `audio.onEnter` (where you're handed the segment's `startSec`).
+     */
+    scheduleNoteAt(midiNote: number, atSec: number, durSec?: number, velocity?: number): void;
+    /**
+     * Schedule a chord (list of MIDI notes) to sound at an explicit absolute
+     * audio-clock time (seconds). The capture-clock counterpart of `playChord`.
+     */
+    scheduleChordAt(midiNotes: number[], atSec: number, durSec?: number, velocity?: number): void;
     /** A MediaStream of the engine's full output, tapped additively (speakers keep
      *  playing). Returns null until init() has created the audio context. For the
      *  promo capture only — not part of normal playback. */

package/dist/audio.js

@@ -337,6 +337,61 @@ var AudioEngine = class {
   get isReady() {
     return this.isInitialized;
   }
+  /**
+   * Current audio-clock time in SECONDS (`Tone.now()`), or 0 before init.
+   *
+   * The scheduling seam for web-core's per-segment audio hook
+   * (`@real-music-packages/web-core/scene` → `recordSceneSpec`'s `segmentAudio`
+   * / `BuiltScene.scheduleAudio`). Pair it with `instrument` so an
+   * AudioEngine-driven app (RET) can satisfy `segmentAudio` exactly like a
+   * raw promo sampler does — `{ instrument: engine.instrument, audioNow: () => engine.audioNow() }`.
+   */
+  audioNow() {
+    return this.Tone ? this.Tone.now() : 0;
+  }
+  /**
+   * A `ScheduleTarget`-shaped view of the active piano voice: an object whose
+   * `triggerAttackRelease(note, dur, time?, velocity?)` forwards to the current
+   * voice (synth, upgrading to the Salamander sampler when it loads). Unlike
+   * `playNote`/`playChord` — which hard-code `Tone.now()` — this accepts an
+   * explicit absolute `time`, which is what offline/deterministic capture needs.
+   *
+   * This is the seam web-core's runner consumes: `segmentAudio.instrument =
+   * engine.instrument`. The declarative `SegmentAudio.schedule` path drives this
+   * via `applySchedule`; the imperative `onEnter` path can call it directly, or
+   * use the `scheduleNoteAt` / `scheduleChordAt` convenience wrappers below.
+   */
+  get instrument() {
+    return {
+      triggerAttackRelease: (note, dur, time, velocity) => {
+        this.piano?.triggerAttackRelease(
+          note,
+          dur,
+          time,
+          velocity
+        );
+      }
+    };
+  }
+  /**
+   * Schedule a single MIDI note to sound at an explicit absolute audio-clock
+   * time (seconds). The capture-clock counterpart of `playNote` — use it inside
+   * a segment's `audio.onEnter` (where you're handed the segment's `startSec`).
+   */
+  scheduleNoteAt(midiNote, atSec, durSec = 0.5, velocity = 0.8) {
+    if (!this.piano) return;
+    this.piano.triggerAttackRelease(midiToNoteName(midiNote), durSec, atSec, velocity);
+  }
+  /**
+   * Schedule a chord (list of MIDI notes) to sound at an explicit absolute
+   * audio-clock time (seconds). The capture-clock counterpart of `playChord`.
+   */
+  scheduleChordAt(midiNotes, atSec, durSec = 1.5, velocity = 0.7) {
+    if (!this.piano) return;
+    for (const m of midiNotes) {
+      this.piano.triggerAttackRelease(midiToNoteName(m), durSec, atSec, velocity);
+    }
+  }
   /** A MediaStream of the engine's full output, tapped additively (speakers keep
    *  playing). Returns null until init() has created the audio context. For the
    *  promo capture only — not part of normal playback. */

package/dist/audio.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/engine.ts"],"sourcesContent":["import { getMidiNote } from './scales';\nimport { midiToNoteName } from './notes';\nimport { KEYS_PREFER_FLATS } from './enharmonic';\nimport { SALAMANDER_URLS_FULL } from './salamander';\nimport { createSalamanderSampler, generateReverb } from './audioHelpers';\n\n// SSR-safe browser guard (equivalent to SvelteKit's `browser` at runtime).\nconst browser = typeof window !== 'undefined';\n\n// Tone.js types (loaded dynamically)\ntype ToneSampler = {\n\ttriggerAttackRelease: (note: string, duration: number | string, time?: number, velocity?: number) => void;\n\ttoDestination: () => ToneSampler;\n\tvolume?: { value: number };\n};\ntype TonePolySynth = {\n\ttriggerAttackRelease: (notes: string[], duration: number | string, time?: number, velocity?: number) => void;\n\ttriggerAttack: (notes: string[], time?: number, velocity?: number) => void;\n\ttriggerRelease: (notes: string[], time?: number) => void;\n\treleaseAll?: (time?: number) => void;\n\ttoDestination: () => TonePolySynth;\n\tconnect: (node: unknown) => TonePolySynth;\n\tvolume: { value: number };\n};\n// Minimal audio-node shape we need to reroute the pad through reverb later.\ntype ToneNode = {\n\tconnect: (node: unknown) => unknown;\n\tdisconnect: () => void;\n\ttoDestination: () => unknown;\n};\n\n// Pre-warm the Tone import so that init() can call Tone.start()\n// synchronously inside a user-gesture handler (required by iOS Safari).\nconst tonePreload: Promise<typeof import('tone')> | null = browser\n\t? import('tone')\n\t: null;\n\nexport class AudioEngine {\n\tprivate piano: ToneSampler | null = null;\n\tprivate synthPiano: ToneSampler | null = null;\n\tprivate strings: TonePolySynth | null = null;\n\tprivate dronePad: TonePolySynth | null = null;\n\tprivate droneNotes: string[] = [];\n\t/** Piano voice level in dB; applied to whichever voice is active. */\n\tprivate pianoVolumeDb = 0;\n\tprivate isInitialized = false;\n\tprivate isLoading = false;\n\tprivate samplerUpgradeStarted = false;\n\tprivate reverbStarted = false;\n\tprivate padFilter: ToneNode | null = null;\n\tprivate Tone: typeof import('tone') | null = null;\n\t/** Which piano voice is currently sounding — for diagnostics. */\n\tvoice: 'none' | 'synth' | 'sampler' = 'none';\n\t/** Last init milestone reached — surfaced on-device to pinpoint stalls. */\n\tlastStage = 'idle';\n\t/**\n\t * Raw AudioContext we create + resume SYNCHRONOUSLY inside the first user\n\t * gesture. iOS Safari only unlocks audio when resume() is called directly\n\t * in the gesture task; awaiting the Tone import first (as init() must) loses\n\t * that activation, so Tone.start()'s resume() hangs with the context stuck\n\t * 'suspended'. We resume this context in the gesture, then hand it to Tone.\n\t */\n\tprivate rawCtx: AudioContext | null = null;\n\tprivate captureDest: MediaStreamAudioDestinationNode | null = null;\n\n\t/**\n\t * Initialize the audio engine (must be called from a user gesture handler).\n\t *\n\t * Strategy: graceful degradation. We bring up a synthesized piano voice\n\t * FIRST — it needs no downloads and decodes nothing, so it is ready\n\t * instantly and works on every browser including iOS Safari. Audio is\n\t * considered ready at that point. We THEN try to load the richer\n\t * Salamander samples in the background and swap them in if they finish.\n\t *\n\t * Why: Tone.Sampler's MP3 decode path hangs on iOS Safari (await\n\t * Tone.loaded() never resolves), which previously stalled init forever.\n\t * Loading samples off the critical path means iOS always gets working\n\t * sound (synth) and merely misses the upgrade, instead of getting silence.\n\t *\n\t * On iOS Safari, Tone.start() must run during the synchronous portion of\n\t * the gesture handler, which is why we pre-import the Tone module above.\n\t */\n\tasync init(): Promise<void> {\n\t\tif (!browser) return;\n\t\tif (this.isInitialized || this.isLoading) return;\n\t\tthis.isLoading = true;\n\t\tthis.lastStage = 'init-start';\n\n\t\ttry {\n\t\t\t// Resolve the pre-warmed Tone import (typically already done).\n\t\t\tthis.Tone = await tonePreload!;\n\t\t\tthis.lastStage = 'tone-imported';\n\n\t\t\t// Use the context we already resumed synchronously in the gesture\n\t\t\t// (see unlock()). Handing it to Tone before any node is created means\n\t\t\t// Tone runs on an already-'running' context, so start() can't hang.\n\t\t\tif (this.rawCtx) {\n\t\t\t\ttry {\n\t\t\t\t\tthis.Tone.setContext(this.rawCtx);\n\t\t\t\t} catch (e) {\n\t\t\t\t\tconsole.warn('[audio] setContext failed', e);\n\t\t\t\t}\n\t\t\t}\n\t\t\tthis.lastStage = 'context-set:' + this.contextState;\n\n\t\t\t// start() resumes the context; on an already-running context it\n\t\t\t// resolves immediately. Race a short timeout as a backstop so a\n\t\t\t// hung resume() can never stall init — the context is running anyway.\n\t\t\tawait Promise.race([\n\t\t\t\tthis.Tone.start(),\n\t\t\t\tnew Promise<void>((r) => setTimeout(r, 1500)),\n\t\t\t]);\n\t\t\tthis.lastStage = 'context-started:' + this.contextState;\n\n\t\t\t// ── Reliable synth piano: instant, zero downloads, universal ──\n\t\t\tthis.synthPiano = new this.Tone.PolySynth(this.Tone.Synth, {\n\t\t\t\toscillator: { type: 'triangle' },\n\t\t\t\tenvelope: { attack: 0.005, decay: 0.5, sustain: 0.3, release: 1.2 },\n\t\t\t}).toDestination() as unknown as ToneSampler;\n\t\t\tthis.piano = this.synthPiano;\n\t\t\tthis.voice = 'synth';\n\t\t\tthis.applyPianoVolume();\n\t\t\tthis.lastStage = 'piano-synth-ready';\n\n\t\t\t// ── Pad synth for background chords ──\n\t\t\t// Pad → lowpass → destination, immediately and reliably (dry). Reverb\n\t\t\t// is added later in the background (see addReverbInBackground): its\n\t\t\t// generate() runs an OfflineAudioContext render that can hang on iOS,\n\t\t\t// so it must never sit on the init critical path.\n\t\t\tthis.padFilter = new this.Tone.Filter({\n\t\t\t\ttype: 'lowpass',\n\t\t\t\tfrequency: 2000,\n\t\t\t\trolloff: -12,\n\t\t\t}).toDestination() as unknown as ToneNode;\n\n\t\t\tthis.strings = new this.Tone.PolySynth(this.Tone.Synth, {\n\t\t\t\toscillator: { type: 'fatsawtooth', count: 3, spread: 30 },\n\t\t\t\tenvelope: { attack: 0.5, decay: 0.3, sustain: 0.6, release: 2 },\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\t\t}).connect(this.padFilter as any) as TonePolySynth;\n\t\t\tthis.strings.volume.value = -10;\n\n\t\t\t// ── Drone pad: a sustained, NON-resolving key anchor ──\n\t\t\t// Open-fifth tonic drone (root + 5th, no third). Exploratory views use\n\t\t\t// it instead of a tonic triad so a held note keeps its real tension\n\t\t\t// (e.g. the leading tone 7 still strains toward 1) rather than being\n\t\t\t// harmonised into a consonant Imaj/Imaj7. Soft, low, routed through the\n\t\t\t// same filter/reverb as the pad. Sustains until stopDrone().\n\t\t\tthis.dronePad = new this.Tone.PolySynth(this.Tone.Synth, {\n\t\t\t\toscillator: { type: 'triangle' },\n\t\t\t\tenvelope: { attack: 0.6, decay: 0.2, sustain: 0.9, release: 1.5 },\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\t\t}).connect(this.padFilter as any) as TonePolySynth;\n\t\t\tthis.dronePad.volume.value = -16;\n\n\t\t\t// Audio is usable now — do NOT block on sample loading or reverb.\n\t\t\tthis.isInitialized = true;\n\t\t\tthis.lastStage = 'ready';\n\n\t\t\t// Background upgrades — neither blocks readiness.\n\t\t\tthis.upgradeToSamplerInBackground();\n\t\t\tthis.addReverbInBackground();\n\t\t} catch (error) {\n\t\t\tthis.lastStage = 'error:' + (error instanceof Error ? error.message : String(error));\n\t\t\tconsole.error('Failed to initialize audio:', error);\n\t\t} finally {\n\t\t\tthis.isLoading = false;\n\t\t}\n\t}\n\n\t/**\n\t * Attempt to load the Salamander sampler in the background and swap it in\n\t * for the synth piano once (and only if) every sample has decoded. On iOS\n\t * Safari this typically never completes, so we simply stay on the synth —\n\t * no stall is ever surfaced because init already resolved.\n\t */\n\tprivate upgradeToSamplerInBackground(): void {\n\t\tif (!this.Tone || this.samplerUpgradeStarted) return;\n\t\tthis.samplerUpgradeStarted = true;\n\n\t\ttry {\n\t\t\tconst sampler = createSalamanderSampler(this.Tone, {\n\t\t\t\turls: SALAMANDER_URLS_FULL,\n\t\t\t\tbaseUrl: '/audio/salamander/',\n\t\t\t\trelease: 1,\n\t\t\t\tonload: () => {\n\t\t\t\t\t// Swap only after every sample decoded successfully.\n\t\t\t\t\tthis.piano = sampler as ToneSampler;\n\t\t\t\t\tthis.voice = 'sampler';\n\t\t\t\t\tthis.applyPianoVolume();\n\t\t\t\t\tconsole.info('[audio] upgraded piano voice to Salamander samples');\n\t\t\t\t},\n\t\t\t\tonerror: (e: unknown) => {\n\t\t\t\t\tconsole.warn('[audio] sample load failed, staying on synth voice', e);\n\t\t\t\t},\n\t\t\t});\n\t\t\tvoid sampler;\n\t\t} catch (e) {\n\t\t\tconsole.warn('[audio] sampler init threw, staying on synth voice', e);\n\t\t}\n\t}\n\n\t/**\n\t * Generate a reverb in the background and reroute the background pad through\n\t * it once ready: pad → filter → reverb → destination. Reverb.generate()\n\t * runs an OfflineAudioContext render that can hang on iOS Safari, so this is\n\t * deliberately off the init critical path — if it never resolves, the pad\n\t * simply stays dry. Raced against a timeout so we log and move on cleanly.\n\t */\n\tprivate async addReverbInBackground(): Promise<void> {\n\t\tif (!this.Tone || !this.padFilter || this.reverbStarted) return;\n\t\tthis.reverbStarted = true;\n\n\t\ttry {\n\t\t\tconst reverb = await generateReverb(this.Tone, { decay: 3, wet: 0.5 }, 4000);\n\t\t\tif (!reverb) {\n\t\t\t\tconsole.warn('[audio] reverb generate timed out, pad stays dry');\n\t\t\t\treturn;\n\t\t\t}\n\t\t\t(reverb as unknown as ToneNode).toDestination();\n\t\t\t// Reroute the pad: detach the filter from the raw destination and\n\t\t\t// send it through the reverb instead.\n\t\t\tthis.padFilter.disconnect();\n\t\t\tthis.padFilter.connect(reverb);\n\t\t\tconsole.info('[audio] reverb enabled');\n\t\t} catch (e) {\n\t\t\tconsole.warn('[audio] reverb generate failed, pad stays dry', e);\n\t\t}\n\t}\n\n\t/**\n\t * MUST be called SYNCHRONOUSLY from a user-gesture handler (touchstart /\n\t * click / keydown), before any await. Creates and resumes a raw\n\t * AudioContext in the gesture task so iOS Safari actually unlocks audio.\n\t * init() then adopts this context via Tone.setContext(). Idempotent.\n\t */\n\tunlock(): void {\n\t\tif (!browser) return;\n\t\ttry {\n\t\t\tif (!this.rawCtx) {\n\t\t\t\tconst AC = (window.AudioContext ||\n\t\t\t\t\t(window as unknown as { webkitAudioContext?: typeof AudioContext })\n\t\t\t\t\t\t.webkitAudioContext) as typeof AudioContext | undefined;\n\t\t\t\tif (!AC) return;\n\t\t\t\tthis.rawCtx = new AC();\n\t\t\t}\n\t\t\tif (this.rawCtx.state !== 'running') {\n\t\t\t\tthis.rawCtx.resume().catch(() => {});\n\t\t\t}\n\t\t} catch (e) {\n\t\t\tconsole.warn('[audio] unlock failed', e);\n\t\t}\n\t}\n\n\t/**\n\t * iOS Safari can silently leave the AudioContext in 'suspended' or\n\t * 'interrupted' state even after Tone.start() resolves, especially after\n\t * tab backgrounding or initial activation. Call this synchronously from\n\t * a user-gesture handler (or before playback) to wake it up. No-op when\n\t * the context is already running.\n\t */\n\tensureRunning(): void {\n\t\t// Resume the raw context we own (covers the pre-Tone window too).\n\t\tif (this.rawCtx && this.rawCtx.state !== 'running') {\n\t\t\tthis.rawCtx.resume().catch(() => {});\n\t\t}\n\t\tif (!this.Tone) return;\n\t\tconst ctx = this.Tone.getContext().rawContext as AudioContext | undefined;\n\t\tif (ctx && ctx.state !== 'running') {\n\t\t\t// Fire-and-forget resume — keeps the call synchronous so it stays\n\t\t\t// inside the current user-gesture stack.\n\t\t\tctx.resume().catch(() => {});\n\t\t}\n\t}\n\n\t/** Current AudioContext state, for diagnostics. */\n\tget contextState(): string {\n\t\tif (!this.Tone) return 'no-tone';\n\t\tconst ctx = this.Tone.getContext().rawContext as AudioContext | undefined;\n\t\treturn ctx?.state ?? 'no-context';\n\t}\n\n\t/**\n\t * Play a MIDI note\n\t */\n\tplayNote(midiNote: number, duration: number = 0.5, velocity: number = 0.8): void {\n\t\tif (!this.piano || !this.isInitialized) return;\n\t\tthis.ensureRunning();\n\t\tconst noteName = midiToNoteName(midiNote);\n\t\tthis.piano.triggerAttackRelease(noteName, duration, this.Tone!.now(), velocity);\n\t}\n\n\t/**\n\t * Play a scale degree in a given key\n\t */\n\tplayScaleDegree(degree: number, key: string, octave: number = 4, duration: number = 0.5): void {\n\t\tconst midiNote = getMidiNote(degree, key, octave);\n\t\tthis.playNote(midiNote, duration);\n\t}\n\n\t/**\n\t * Start a sustained background chord (tonic chord)\n\t */\n\tstartBackgroundChord(key: string, duration: number = 4): void {\n\t\tif (!this.strings || !this.isInitialized) return;\n\t\tthis.ensureRunning();\n\n\t\tconst useFlats = (KEYS_PREFER_FLATS as readonly string[]).includes(key);\n\n\t\t// Build tonic chord voicing\n\t\tconst root4 = getMidiNote(1, key, 4);\n\t\tconst fifth4 = getMidiNote(5, key, 4);\n\t\tconst root5 = getMidiNote(1, key, 5);\n\t\tconst third5 = getMidiNote(3, key, 5);\n\n\t\tconst notes = [root4, fifth4, root5, third5].map((m) => midiToNoteName(m, useFlats));\n\n\t\tthis.strings.triggerAttackRelease(notes, duration, this.Tone!.now(), 0.3);\n\t}\n\n\t/**\n\t * Start a sustained tonic DRONE as a key anchor — an open fifth (root + 5th,\n\t * no third) in a low octave. Unlike startBackgroundChord (a full tonic\n\t * triad), the missing third means individual scale degrees keep their\n\t * tension instead of being resolved into the tonic chord: a note held over\n\t * this drone sounds as tense/stable as it truly is. Intended for exploratory\n\t * note-by-note views. Sustains until stopDrone() is called; calling again\n\t * restarts cleanly in the new key. Idempotent-safe.\n\t */\n\tstartDrone(key: string): void {\n\t\tif (!this.dronePad || !this.isInitialized) return;\n\t\tthis.ensureRunning();\n\t\tthis.stopDrone();\n\n\t\tconst useFlats = (KEYS_PREFER_FLATS as readonly string[]).includes(key);\n\t\tconst root3 = getMidiNote(1, key, 3);\n\t\tconst fifth3 = getMidiNote(5, key, 3);\n\t\tconst root4 = getMidiNote(1, key, 4);\n\t\tthis.droneNotes = [root3, fifth3, root4].map((m) => midiToNoteName(m, useFlats));\n\n\t\tthis.dronePad.triggerAttack(this.droneNotes, this.Tone!.now());\n\t}\n\n\t/** Stop the sustained drone started by startDrone(). No-op if none playing. */\n\tstopDrone(): void {\n\t\tif (!this.dronePad) return;\n\t\ttry {\n\t\t\tif (this.droneNotes.length > 0) {\n\t\t\t\tthis.dronePad.triggerRelease(this.droneNotes, this.Tone!.now());\n\t\t\t} else {\n\t\t\t\tthis.dronePad.releaseAll?.(this.Tone!.now());\n\t\t\t}\n\t\t} catch (e) {\n\t\t\tconsole.warn('[audio] stopDrone failed', e);\n\t\t}\n\t\tthis.droneNotes = [];\n\t}\n\n\t/**\n\t * Set the piano voice level in dB (0 = unchanged default, negative = quieter).\n\t * Applies to the current voice and is re-applied when the sampler swaps in.\n\t */\n\tsetPianoVolume(db: number): void {\n\t\tthis.pianoVolumeDb = db;\n\t\tthis.applyPianoVolume();\n\t}\n\n\tprivate applyPianoVolume(): void {\n\t\tfor (const voice of [this.synthPiano, this.piano]) {\n\t\t\tconst vol = (voice as { volume?: { value: number } } | null)?.volume;\n\t\t\tif (vol) vol.value = this.pianoVolumeDb;\n\t\t}\n\t}\n\n\t/**\n\t * Play a chord (list of MIDI notes) on the piano sampler.\n\t */\n\tplayChord(midiNotes: number[], duration: number = 1.5, velocity: number = 0.7): void {\n\t\tif (!this.piano || !this.isInitialized) return;\n\t\tthis.ensureRunning();\n\t\tconst names = midiNotes.map((m) => midiToNoteName(m));\n\t\tfor (const n of names) {\n\t\t\tthis.piano.triggerAttackRelease(n, duration, this.Tone!.now(), velocity);\n\t\t}\n\t}\n\n\t/**\n\t * Play a melodic phrase: a sequence of scale degrees with configurable timing.\n\t * Each note plays for `noteDuration` seconds, with `gap` ms gap between notes.\n\t */\n\tasync playPhrase(\n\t\tdegrees: number[],\n\t\tkey: string,\n\t\toctave: number,\n\t\tnoteDuration: number = 0.4,\n\t\tgap: number = 100\n\t): Promise<void> {\n\t\tfor (let i = 0; i < degrees.length; i++) {\n\t\t\tthis.playScaleDegree(degrees[i], key, octave, noteDuration);\n\t\t\tawait this.wait(Math.round(noteDuration * 1000) + gap);\n\t\t}\n\t}\n\n\t/**\n\t * Play a sequence of scale degrees\n\t */\n\tasync playSequence(\n\t\tdegrees: number[],\n\t\tkey: string,\n\t\ttempo: number = 500,\n\t\toctave: number = 4,\n\t\tonNoteStart?: (index: number) => void,\n\t\tonNoteEnd?: (index: number) => void\n\t): Promise<void> {\n\t\tfor (let i = 0; i < degrees.length; i++) {\n\t\t\tonNoteStart?.(i);\n\t\t\tthis.playScaleDegree(degrees[i], key, octave, 0.45);\n\t\t\tawait this.wait(tempo);\n\t\t\tonNoteEnd?.(i);\n\t\t}\n\t}\n\n\t/**\n\t * Utility to wait for a given duration\n\t */\n\tprivate wait(ms: number): Promise<void> {\n\t\treturn new Promise((resolve) => setTimeout(resolve, ms));\n\t}\n\n\t/**\n\t * Check if audio is ready\n\t */\n\tget isReady(): boolean {\n\t\treturn this.isInitialized;\n\t}\n\n\t/** A MediaStream of the engine's full output, tapped additively (speakers keep\n\t *  playing). Returns null until init() has created the audio context. For the\n\t *  promo capture only — not part of normal playback. */\n\tgetCaptureStream(): MediaStream | null {\n\t\tif (!this.Tone || !this.rawCtx) return null;\n\t\tif (!this.captureDest) {\n\t\t\tthis.captureDest = this.rawCtx.createMediaStreamDestination();\n\t\t\t(this.Tone.getDestination() as unknown as { connect: (n: AudioNode) => void }).connect(this.captureDest);\n\t\t}\n\t\treturn this.captureDest.stream;\n\t}\n}\n\n// Singleton instance\nexport const audio = new AudioEngine();\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/engine.ts"],"sourcesContent":["import { getMidiNote } from './scales';\nimport { midiToNoteName } from './notes';\nimport { KEYS_PREFER_FLATS } from './enharmonic';\nimport { SALAMANDER_URLS_FULL } from './salamander';\nimport { createSalamanderSampler, generateReverb } from './audioHelpers';\n\n// SSR-safe browser guard (equivalent to SvelteKit's `browser` at runtime).\nconst browser = typeof window !== 'undefined';\n\n// Tone.js types (loaded dynamically)\ntype ToneSampler = {\n\ttriggerAttackRelease: (note: string, duration: number | string, time?: number, velocity?: number) => void;\n\ttoDestination: () => ToneSampler;\n\tvolume?: { value: number };\n};\ntype TonePolySynth = {\n\ttriggerAttackRelease: (notes: string[], duration: number | string, time?: number, velocity?: number) => void;\n\ttriggerAttack: (notes: string[], time?: number, velocity?: number) => void;\n\ttriggerRelease: (notes: string[], time?: number) => void;\n\treleaseAll?: (time?: number) => void;\n\ttoDestination: () => TonePolySynth;\n\tconnect: (node: unknown) => TonePolySynth;\n\tvolume: { value: number };\n};\n// Minimal audio-node shape we need to reroute the pad through reverb later.\ntype ToneNode = {\n\tconnect: (node: unknown) => unknown;\n\tdisconnect: () => void;\n\ttoDestination: () => unknown;\n};\n\n// Pre-warm the Tone import so that init() can call Tone.start()\n// synchronously inside a user-gesture handler (required by iOS Safari).\nconst tonePreload: Promise<typeof import('tone')> | null = browser\n\t? import('tone')\n\t: null;\n\nexport class AudioEngine {\n\tprivate piano: ToneSampler | null = null;\n\tprivate synthPiano: ToneSampler | null = null;\n\tprivate strings: TonePolySynth | null = null;\n\tprivate dronePad: TonePolySynth | null = null;\n\tprivate droneNotes: string[] = [];\n\t/** Piano voice level in dB; applied to whichever voice is active. */\n\tprivate pianoVolumeDb = 0;\n\tprivate isInitialized = false;\n\tprivate isLoading = false;\n\tprivate samplerUpgradeStarted = false;\n\tprivate reverbStarted = false;\n\tprivate padFilter: ToneNode | null = null;\n\tprivate Tone: typeof import('tone') | null = null;\n\t/** Which piano voice is currently sounding — for diagnostics. */\n\tvoice: 'none' | 'synth' | 'sampler' = 'none';\n\t/** Last init milestone reached — surfaced on-device to pinpoint stalls. */\n\tlastStage = 'idle';\n\t/**\n\t * Raw AudioContext we create + resume SYNCHRONOUSLY inside the first user\n\t * gesture. iOS Safari only unlocks audio when resume() is called directly\n\t * in the gesture task; awaiting the Tone import first (as init() must) loses\n\t * that activation, so Tone.start()'s resume() hangs with the context stuck\n\t * 'suspended'. We resume this context in the gesture, then hand it to Tone.\n\t */\n\tprivate rawCtx: AudioContext | null = null;\n\tprivate captureDest: MediaStreamAudioDestinationNode | null = null;\n\n\t/**\n\t * Initialize the audio engine (must be called from a user gesture handler).\n\t *\n\t * Strategy: graceful degradation. We bring up a synthesized piano voice\n\t * FIRST — it needs no downloads and decodes nothing, so it is ready\n\t * instantly and works on every browser including iOS Safari. Audio is\n\t * considered ready at that point. We THEN try to load the richer\n\t * Salamander samples in the background and swap them in if they finish.\n\t *\n\t * Why: Tone.Sampler's MP3 decode path hangs on iOS Safari (await\n\t * Tone.loaded() never resolves), which previously stalled init forever.\n\t * Loading samples off the critical path means iOS always gets working\n\t * sound (synth) and merely misses the upgrade, instead of getting silence.\n\t *\n\t * On iOS Safari, Tone.start() must run during the synchronous portion of\n\t * the gesture handler, which is why we pre-import the Tone module above.\n\t */\n\tasync init(): Promise<void> {\n\t\tif (!browser) return;\n\t\tif (this.isInitialized || this.isLoading) return;\n\t\tthis.isLoading = true;\n\t\tthis.lastStage = 'init-start';\n\n\t\ttry {\n\t\t\t// Resolve the pre-warmed Tone import (typically already done).\n\t\t\tthis.Tone = await tonePreload!;\n\t\t\tthis.lastStage = 'tone-imported';\n\n\t\t\t// Use the context we already resumed synchronously in the gesture\n\t\t\t// (see unlock()). Handing it to Tone before any node is created means\n\t\t\t// Tone runs on an already-'running' context, so start() can't hang.\n\t\t\tif (this.rawCtx) {\n\t\t\t\ttry {\n\t\t\t\t\tthis.Tone.setContext(this.rawCtx);\n\t\t\t\t} catch (e) {\n\t\t\t\t\tconsole.warn('[audio] setContext failed', e);\n\t\t\t\t}\n\t\t\t}\n\t\t\tthis.lastStage = 'context-set:' + this.contextState;\n\n\t\t\t// start() resumes the context; on an already-running context it\n\t\t\t// resolves immediately. Race a short timeout as a backstop so a\n\t\t\t// hung resume() can never stall init — the context is running anyway.\n\t\t\tawait Promise.race([\n\t\t\t\tthis.Tone.start(),\n\t\t\t\tnew Promise<void>((r) => setTimeout(r, 1500)),\n\t\t\t]);\n\t\t\tthis.lastStage = 'context-started:' + this.contextState;\n\n\t\t\t// ── Reliable synth piano: instant, zero downloads, universal ──\n\t\t\tthis.synthPiano = new this.Tone.PolySynth(this.Tone.Synth, {\n\t\t\t\toscillator: { type: 'triangle' },\n\t\t\t\tenvelope: { attack: 0.005, decay: 0.5, sustain: 0.3, release: 1.2 },\n\t\t\t}).toDestination() as unknown as ToneSampler;\n\t\t\tthis.piano = this.synthPiano;\n\t\t\tthis.voice = 'synth';\n\t\t\tthis.applyPianoVolume();\n\t\t\tthis.lastStage = 'piano-synth-ready';\n\n\t\t\t// ── Pad synth for background chords ──\n\t\t\t// Pad → lowpass → destination, immediately and reliably (dry). Reverb\n\t\t\t// is added later in the background (see addReverbInBackground): its\n\t\t\t// generate() runs an OfflineAudioContext render that can hang on iOS,\n\t\t\t// so it must never sit on the init critical path.\n\t\t\tthis.padFilter = new this.Tone.Filter({\n\t\t\t\ttype: 'lowpass',\n\t\t\t\tfrequency: 2000,\n\t\t\t\trolloff: -12,\n\t\t\t}).toDestination() as unknown as ToneNode;\n\n\t\t\tthis.strings = new this.Tone.PolySynth(this.Tone.Synth, {\n\t\t\t\toscillator: { type: 'fatsawtooth', count: 3, spread: 30 },\n\t\t\t\tenvelope: { attack: 0.5, decay: 0.3, sustain: 0.6, release: 2 },\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\t\t}).connect(this.padFilter as any) as TonePolySynth;\n\t\t\tthis.strings.volume.value = -10;\n\n\t\t\t// ── Drone pad: a sustained, NON-resolving key anchor ──\n\t\t\t// Open-fifth tonic drone (root + 5th, no third). Exploratory views use\n\t\t\t// it instead of a tonic triad so a held note keeps its real tension\n\t\t\t// (e.g. the leading tone 7 still strains toward 1) rather than being\n\t\t\t// harmonised into a consonant Imaj/Imaj7. Soft, low, routed through the\n\t\t\t// same filter/reverb as the pad. Sustains until stopDrone().\n\t\t\tthis.dronePad = new this.Tone.PolySynth(this.Tone.Synth, {\n\t\t\t\toscillator: { type: 'triangle' },\n\t\t\t\tenvelope: { attack: 0.6, decay: 0.2, sustain: 0.9, release: 1.5 },\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\t\t}).connect(this.padFilter as any) as TonePolySynth;\n\t\t\tthis.dronePad.volume.value = -16;\n\n\t\t\t// Audio is usable now — do NOT block on sample loading or reverb.\n\t\t\tthis.isInitialized = true;\n\t\t\tthis.lastStage = 'ready';\n\n\t\t\t// Background upgrades — neither blocks readiness.\n\t\t\tthis.upgradeToSamplerInBackground();\n\t\t\tthis.addReverbInBackground();\n\t\t} catch (error) {\n\t\t\tthis.lastStage = 'error:' + (error instanceof Error ? error.message : String(error));\n\t\t\tconsole.error('Failed to initialize audio:', error);\n\t\t} finally {\n\t\t\tthis.isLoading = false;\n\t\t}\n\t}\n\n\t/**\n\t * Attempt to load the Salamander sampler in the background and swap it in\n\t * for the synth piano once (and only if) every sample has decoded. On iOS\n\t * Safari this typically never completes, so we simply stay on the synth —\n\t * no stall is ever surfaced because init already resolved.\n\t */\n\tprivate upgradeToSamplerInBackground(): void {\n\t\tif (!this.Tone || this.samplerUpgradeStarted) return;\n\t\tthis.samplerUpgradeStarted = true;\n\n\t\ttry {\n\t\t\tconst sampler = createSalamanderSampler(this.Tone, {\n\t\t\t\turls: SALAMANDER_URLS_FULL,\n\t\t\t\tbaseUrl: '/audio/salamander/',\n\t\t\t\trelease: 1,\n\t\t\t\tonload: () => {\n\t\t\t\t\t// Swap only after every sample decoded successfully.\n\t\t\t\t\tthis.piano = sampler as ToneSampler;\n\t\t\t\t\tthis.voice = 'sampler';\n\t\t\t\t\tthis.applyPianoVolume();\n\t\t\t\t\tconsole.info('[audio] upgraded piano voice to Salamander samples');\n\t\t\t\t},\n\t\t\t\tonerror: (e: unknown) => {\n\t\t\t\t\tconsole.warn('[audio] sample load failed, staying on synth voice', e);\n\t\t\t\t},\n\t\t\t});\n\t\t\tvoid sampler;\n\t\t} catch (e) {\n\t\t\tconsole.warn('[audio] sampler init threw, staying on synth voice', e);\n\t\t}\n\t}\n\n\t/**\n\t * Generate a reverb in the background and reroute the background pad through\n\t * it once ready: pad → filter → reverb → destination. Reverb.generate()\n\t * runs an OfflineAudioContext render that can hang on iOS Safari, so this is\n\t * deliberately off the init critical path — if it never resolves, the pad\n\t * simply stays dry. Raced against a timeout so we log and move on cleanly.\n\t */\n\tprivate async addReverbInBackground(): Promise<void> {\n\t\tif (!this.Tone || !this.padFilter || this.reverbStarted) return;\n\t\tthis.reverbStarted = true;\n\n\t\ttry {\n\t\t\tconst reverb = await generateReverb(this.Tone, { decay: 3, wet: 0.5 }, 4000);\n\t\t\tif (!reverb) {\n\t\t\t\tconsole.warn('[audio] reverb generate timed out, pad stays dry');\n\t\t\t\treturn;\n\t\t\t}\n\t\t\t(reverb as unknown as ToneNode).toDestination();\n\t\t\t// Reroute the pad: detach the filter from the raw destination and\n\t\t\t// send it through the reverb instead.\n\t\t\tthis.padFilter.disconnect();\n\t\t\tthis.padFilter.connect(reverb);\n\t\t\tconsole.info('[audio] reverb enabled');\n\t\t} catch (e) {\n\t\t\tconsole.warn('[audio] reverb generate failed, pad stays dry', e);\n\t\t}\n\t}\n\n\t/**\n\t * MUST be called SYNCHRONOUSLY from a user-gesture handler (touchstart /\n\t * click / keydown), before any await. Creates and resumes a raw\n\t * AudioContext in the gesture task so iOS Safari actually unlocks audio.\n\t * init() then adopts this context via Tone.setContext(). Idempotent.\n\t */\n\tunlock(): void {\n\t\tif (!browser) return;\n\t\ttry {\n\t\t\tif (!this.rawCtx) {\n\t\t\t\tconst AC = (window.AudioContext ||\n\t\t\t\t\t(window as unknown as { webkitAudioContext?: typeof AudioContext })\n\t\t\t\t\t\t.webkitAudioContext) as typeof AudioContext | undefined;\n\t\t\t\tif (!AC) return;\n\t\t\t\tthis.rawCtx = new AC();\n\t\t\t}\n\t\t\tif (this.rawCtx.state !== 'running') {\n\t\t\t\tthis.rawCtx.resume().catch(() => {});\n\t\t\t}\n\t\t} catch (e) {\n\t\t\tconsole.warn('[audio] unlock failed', e);\n\t\t}\n\t}\n\n\t/**\n\t * iOS Safari can silently leave the AudioContext in 'suspended' or\n\t * 'interrupted' state even after Tone.start() resolves, especially after\n\t * tab backgrounding or initial activation. Call this synchronously from\n\t * a user-gesture handler (or before playback) to wake it up. No-op when\n\t * the context is already running.\n\t */\n\tensureRunning(): void {\n\t\t// Resume the raw context we own (covers the pre-Tone window too).\n\t\tif (this.rawCtx && this.rawCtx.state !== 'running') {\n\t\t\tthis.rawCtx.resume().catch(() => {});\n\t\t}\n\t\tif (!this.Tone) return;\n\t\tconst ctx = this.Tone.getContext().rawContext as AudioContext | undefined;\n\t\tif (ctx && ctx.state !== 'running') {\n\t\t\t// Fire-and-forget resume — keeps the call synchronous so it stays\n\t\t\t// inside the current user-gesture stack.\n\t\t\tctx.resume().catch(() => {});\n\t\t}\n\t}\n\n\t/** Current AudioContext state, for diagnostics. */\n\tget contextState(): string {\n\t\tif (!this.Tone) return 'no-tone';\n\t\tconst ctx = this.Tone.getContext().rawContext as AudioContext | undefined;\n\t\treturn ctx?.state ?? 'no-context';\n\t}\n\n\t/**\n\t * Play a MIDI note\n\t */\n\tplayNote(midiNote: number, duration: number = 0.5, velocity: number = 0.8): void {\n\t\tif (!this.piano || !this.isInitialized) return;\n\t\tthis.ensureRunning();\n\t\tconst noteName = midiToNoteName(midiNote);\n\t\tthis.piano.triggerAttackRelease(noteName, duration, this.Tone!.now(), velocity);\n\t}\n\n\t/**\n\t * Play a scale degree in a given key\n\t */\n\tplayScaleDegree(degree: number, key: string, octave: number = 4, duration: number = 0.5): void {\n\t\tconst midiNote = getMidiNote(degree, key, octave);\n\t\tthis.playNote(midiNote, duration);\n\t}\n\n\t/**\n\t * Start a sustained background chord (tonic chord)\n\t */\n\tstartBackgroundChord(key: string, duration: number = 4): void {\n\t\tif (!this.strings || !this.isInitialized) return;\n\t\tthis.ensureRunning();\n\n\t\tconst useFlats = (KEYS_PREFER_FLATS as readonly string[]).includes(key);\n\n\t\t// Build tonic chord voicing\n\t\tconst root4 = getMidiNote(1, key, 4);\n\t\tconst fifth4 = getMidiNote(5, key, 4);\n\t\tconst root5 = getMidiNote(1, key, 5);\n\t\tconst third5 = getMidiNote(3, key, 5);\n\n\t\tconst notes = [root4, fifth4, root5, third5].map((m) => midiToNoteName(m, useFlats));\n\n\t\tthis.strings.triggerAttackRelease(notes, duration, this.Tone!.now(), 0.3);\n\t}\n\n\t/**\n\t * Start a sustained tonic DRONE as a key anchor — an open fifth (root + 5th,\n\t * no third) in a low octave. Unlike startBackgroundChord (a full tonic\n\t * triad), the missing third means individual scale degrees keep their\n\t * tension instead of being resolved into the tonic chord: a note held over\n\t * this drone sounds as tense/stable as it truly is. Intended for exploratory\n\t * note-by-note views. Sustains until stopDrone() is called; calling again\n\t * restarts cleanly in the new key. Idempotent-safe.\n\t */\n\tstartDrone(key: string): void {\n\t\tif (!this.dronePad || !this.isInitialized) return;\n\t\tthis.ensureRunning();\n\t\tthis.stopDrone();\n\n\t\tconst useFlats = (KEYS_PREFER_FLATS as readonly string[]).includes(key);\n\t\tconst root3 = getMidiNote(1, key, 3);\n\t\tconst fifth3 = getMidiNote(5, key, 3);\n\t\tconst root4 = getMidiNote(1, key, 4);\n\t\tthis.droneNotes = [root3, fifth3, root4].map((m) => midiToNoteName(m, useFlats));\n\n\t\tthis.dronePad.triggerAttack(this.droneNotes, this.Tone!.now());\n\t}\n\n\t/** Stop the sustained drone started by startDrone(). No-op if none playing. */\n\tstopDrone(): void {\n\t\tif (!this.dronePad) return;\n\t\ttry {\n\t\t\tif (this.droneNotes.length > 0) {\n\t\t\t\tthis.dronePad.triggerRelease(this.droneNotes, this.Tone!.now());\n\t\t\t} else {\n\t\t\t\tthis.dronePad.releaseAll?.(this.Tone!.now());\n\t\t\t}\n\t\t} catch (e) {\n\t\t\tconsole.warn('[audio] stopDrone failed', e);\n\t\t}\n\t\tthis.droneNotes = [];\n\t}\n\n\t/**\n\t * Set the piano voice level in dB (0 = unchanged default, negative = quieter).\n\t * Applies to the current voice and is re-applied when the sampler swaps in.\n\t */\n\tsetPianoVolume(db: number): void {\n\t\tthis.pianoVolumeDb = db;\n\t\tthis.applyPianoVolume();\n\t}\n\n\tprivate applyPianoVolume(): void {\n\t\tfor (const voice of [this.synthPiano, this.piano]) {\n\t\t\tconst vol = (voice as { volume?: { value: number } } | null)?.volume;\n\t\t\tif (vol) vol.value = this.pianoVolumeDb;\n\t\t}\n\t}\n\n\t/**\n\t * Play a chord (list of MIDI notes) on the piano sampler.\n\t */\n\tplayChord(midiNotes: number[], duration: number = 1.5, velocity: number = 0.7): void {\n\t\tif (!this.piano || !this.isInitialized) return;\n\t\tthis.ensureRunning();\n\t\tconst names = midiNotes.map((m) => midiToNoteName(m));\n\t\tfor (const n of names) {\n\t\t\tthis.piano.triggerAttackRelease(n, duration, this.Tone!.now(), velocity);\n\t\t}\n\t}\n\n\t/**\n\t * Play a melodic phrase: a sequence of scale degrees with configurable timing.\n\t * Each note plays for `noteDuration` seconds, with `gap` ms gap between notes.\n\t */\n\tasync playPhrase(\n\t\tdegrees: number[],\n\t\tkey: string,\n\t\toctave: number,\n\t\tnoteDuration: number = 0.4,\n\t\tgap: number = 100\n\t): Promise<void> {\n\t\tfor (let i = 0; i < degrees.length; i++) {\n\t\t\tthis.playScaleDegree(degrees[i], key, octave, noteDuration);\n\t\t\tawait this.wait(Math.round(noteDuration * 1000) + gap);\n\t\t}\n\t}\n\n\t/**\n\t * Play a sequence of scale degrees\n\t */\n\tasync playSequence(\n\t\tdegrees: number[],\n\t\tkey: string,\n\t\ttempo: number = 500,\n\t\toctave: number = 4,\n\t\tonNoteStart?: (index: number) => void,\n\t\tonNoteEnd?: (index: number) => void\n\t): Promise<void> {\n\t\tfor (let i = 0; i < degrees.length; i++) {\n\t\t\tonNoteStart?.(i);\n\t\t\tthis.playScaleDegree(degrees[i], key, octave, 0.45);\n\t\t\tawait this.wait(tempo);\n\t\t\tonNoteEnd?.(i);\n\t\t}\n\t}\n\n\t/**\n\t * Utility to wait for a given duration\n\t */\n\tprivate wait(ms: number): Promise<void> {\n\t\treturn new Promise((resolve) => setTimeout(resolve, ms));\n\t}\n\n\t/**\n\t * Check if audio is ready\n\t */\n\tget isReady(): boolean {\n\t\treturn this.isInitialized;\n\t}\n\n\t/**\n\t * Current audio-clock time in SECONDS (`Tone.now()`), or 0 before init.\n\t *\n\t * The scheduling seam for web-core's per-segment audio hook\n\t * (`@real-music-packages/web-core/scene` → `recordSceneSpec`'s `segmentAudio`\n\t * / `BuiltScene.scheduleAudio`). Pair it with `instrument` so an\n\t * AudioEngine-driven app (RET) can satisfy `segmentAudio` exactly like a\n\t * raw promo sampler does — `{ instrument: engine.instrument, audioNow: () => engine.audioNow() }`.\n\t */\n\taudioNow(): number {\n\t\treturn this.Tone ? this.Tone.now() : 0;\n\t}\n\n\t/**\n\t * A `ScheduleTarget`-shaped view of the active piano voice: an object whose\n\t * `triggerAttackRelease(note, dur, time?, velocity?)` forwards to the current\n\t * voice (synth, upgrading to the Salamander sampler when it loads). Unlike\n\t * `playNote`/`playChord` — which hard-code `Tone.now()` — this accepts an\n\t * explicit absolute `time`, which is what offline/deterministic capture needs.\n\t *\n\t * This is the seam web-core's runner consumes: `segmentAudio.instrument =\n\t * engine.instrument`. The declarative `SegmentAudio.schedule` path drives this\n\t * via `applySchedule`; the imperative `onEnter` path can call it directly, or\n\t * use the `scheduleNoteAt` / `scheduleChordAt` convenience wrappers below.\n\t */\n\tget instrument(): {\n\t\ttriggerAttackRelease: (note: unknown, dur: unknown, time?: unknown, velocity?: unknown) => void;\n\t} {\n\t\treturn {\n\t\t\ttriggerAttackRelease: (note, dur, time, velocity) => {\n\t\t\t\tthis.piano?.triggerAttackRelease(\n\t\t\t\t\tnote as string,\n\t\t\t\t\tdur as number | string,\n\t\t\t\t\ttime as number | undefined,\n\t\t\t\t\tvelocity as number | undefined,\n\t\t\t\t);\n\t\t\t},\n\t\t};\n\t}\n\n\t/**\n\t * Schedule a single MIDI note to sound at an explicit absolute audio-clock\n\t * time (seconds). The capture-clock counterpart of `playNote` — use it inside\n\t * a segment's `audio.onEnter` (where you're handed the segment's `startSec`).\n\t */\n\tscheduleNoteAt(midiNote: number, atSec: number, durSec: number = 0.5, velocity: number = 0.8): void {\n\t\tif (!this.piano) return;\n\t\tthis.piano.triggerAttackRelease(midiToNoteName(midiNote), durSec, atSec, velocity);\n\t}\n\n\t/**\n\t * Schedule a chord (list of MIDI notes) to sound at an explicit absolute\n\t * audio-clock time (seconds). The capture-clock counterpart of `playChord`.\n\t */\n\tscheduleChordAt(midiNotes: number[], atSec: number, durSec: number = 1.5, velocity: number = 0.7): void {\n\t\tif (!this.piano) return;\n\t\tfor (const m of midiNotes) {\n\t\t\tthis.piano.triggerAttackRelease(midiToNoteName(m), durSec, atSec, velocity);\n\t\t}\n\t}\n\n\t/** A MediaStream of the engine's full output, tapped additively (speakers keep\n\t *  playing). Returns null until init() has created the audio context. For the\n\t *  promo capture only — not part of normal playback. */\n\tgetCaptureStream(): MediaStream | null {\n\t\tif (!this.Tone || !this.rawCtx) return null;\n\t\tif (!this.captureDest) {\n\t\t\tthis.captureDest = this.rawCtx.createMediaStreamDestination();\n\t\t\t(this.Tone.getDestination() as unknown as { connect: (n: AudioNode) => void }).connect(this.captureDest);\n\t\t}\n\t\treturn this.captureDest.stream;\n\t}\n}\n\n// Singleton instance\nexport const audio = new AudioEngine();\n"],"mappings":"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","names":[]}

package/dist/scene/headless.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Install jsdom globals + a fake 2D canvas context so OSMD can `load()` a score
+ * headlessly. Idempotent. Call once before constructing an OSMD instance in Node.
+ *
+ * No-ops if `window`/`document` already exist (e.g. a real browser, or a vitest
+ * jsdom environment), so it is safe to call unconditionally.
+ */
+declare function setupHeadlessDom(): Promise<void>;
+
+export { setupHeadlessDom };

package/dist/scene/headless.js

@@ -0,0 +1,108 @@
+// src/scene/headless.ts
+var installed = false;
+async function setupHeadlessDom() {
+  if (installed) return;
+  const g = globalThis;
+  if (typeof g.document !== "undefined" && typeof g.window !== "undefined") {
+    ensureFakeContext(g.window);
+    installed = true;
+    return;
+  }
+  const { JSDOM } = await import("jsdom");
+  const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>", {
+    pretendToBeVisual: true
+  });
+  const { window } = dom;
+  ensureFakeContext(window);
+  g.window = window;
+  g.document = window.document;
+  try {
+    g.navigator = window.navigator;
+  } catch {
+  }
+  g.HTMLElement = window.HTMLElement;
+  g.Node = window.Node;
+  g.DOMParser = window.DOMParser;
+  g.XMLSerializer = window.XMLSerializer;
+  g.requestAnimationFrame = (cb) => setTimeout(() => cb(Date.now()), 0);
+  g.cancelAnimationFrame = () => {
+  };
+  installed = true;
+}
+function ensureFakeContext(window) {
+  const proto = window.HTMLCanvasElement?.prototype;
+  if (!proto) return;
+  const fakeCtx = makeFakeContext();
+  proto.getContext = function() {
+    return fakeCtx;
+  };
+}
+function makeFakeContext() {
+  return {
+    font: "10px Arial",
+    fillStyle: "#000",
+    strokeStyle: "#000",
+    lineWidth: 1,
+    textAlign: "left",
+    textBaseline: "alphabetic",
+    globalAlpha: 1,
+    measureText: (s) => ({
+      width: (s ? s.length : 0) * 6,
+      actualBoundingBoxAscent: 8,
+      actualBoundingBoxDescent: 2
+    }),
+    save() {
+    },
+    restore() {
+    },
+    beginPath() {
+    },
+    closePath() {
+    },
+    moveTo() {
+    },
+    lineTo() {
+    },
+    bezierCurveTo() {
+    },
+    quadraticCurveTo() {
+    },
+    arc() {
+    },
+    rect() {
+    },
+    fill() {
+    },
+    stroke() {
+    },
+    fillRect() {
+    },
+    clearRect() {
+    },
+    fillText() {
+    },
+    strokeText() {
+    },
+    translate() {
+    },
+    rotate() {
+    },
+    scale() {
+    },
+    setTransform() {
+    },
+    transform() {
+    },
+    drawImage() {
+    },
+    clip() {
+    },
+    createLinearGradient: () => ({ addColorStop() {
+    } }),
+    getImageData: () => ({ data: new Uint8ClampedArray(4) })
+  };
+}
+export {
+  setupHeadlessDom
+};
+//# sourceMappingURL=headless.js.map

package/dist/scene/headless.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/scene/headless.ts"],"sourcesContent":["// Headless DOM setup for running OSMD outside a browser (Node — CI, batch,\n// whozart's notation-less audio path).\n//\n// OSMD's load() runs graphical layout, which calls canvas 2D text metrics.\n// Bare jsdom returns null for getContext('2d'), so layout throws on scores\n// with lyrics. We install a minimal fake 2D context so layout completes; we\n// never read the pixels — only osmd.sheet (the source model) is consumed by\n// scoreFromMusicXML, so a no-op context is sufficient.\n//\n// The SAME extraction code (scoreFromMusicXML) runs unchanged in a real\n// browser: there the native 2D context handles lyric layout and this helper is\n// never called. This module is the only Node-specific seam.\n//\n// jsdom is a devDependency (used by tests + headless callers); it is imported\n// dynamically so bundling for the browser never pulls it in.\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\n\nlet installed = false;\n\n/**\n * Install jsdom globals + a fake 2D canvas context so OSMD can `load()` a score\n * headlessly. Idempotent. Call once before constructing an OSMD instance in Node.\n *\n * No-ops if `window`/`document` already exist (e.g. a real browser, or a vitest\n * jsdom environment), so it is safe to call unconditionally.\n */\nexport async function setupHeadlessDom(): Promise<void> {\n  if (installed) return;\n  const g = globalThis as any;\n  if (typeof g.document !== 'undefined' && typeof g.window !== 'undefined') {\n    // A DOM is already present (browser or test env). Still ensure a usable 2D\n    // context for OSMD's lyric layout if jsdom didn't provide one.\n    ensureFakeContext(g.window);\n    installed = true;\n    return;\n  }\n\n  // Literal specifier so bundlers can tree-shake it out of browser builds.\n  const { JSDOM } = await import('jsdom');\n  const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>', {\n    pretendToBeVisual: true,\n  });\n  const { window } = dom;\n\n  ensureFakeContext(window);\n\n  g.window = window;\n  g.document = window.document;\n  // Node 26: globalThis.navigator is read-only — tolerate the failure.\n  try {\n    g.navigator = window.navigator;\n  } catch {\n    /* read-only on some Node versions; OSMD doesn't require it */\n  }\n  g.HTMLElement = window.HTMLElement;\n  g.Node = window.Node;\n  g.DOMParser = window.DOMParser;\n  g.XMLSerializer = window.XMLSerializer;\n  g.requestAnimationFrame = (cb: (t: number) => void) => setTimeout(() => cb(Date.now()), 0);\n  g.cancelAnimationFrame = () => {};\n\n  installed = true;\n}\n\n/** Patch HTMLCanvasElement.getContext to return a no-op 2D context. */\nfunction ensureFakeContext(window: any): void {\n  const proto = window.HTMLCanvasElement?.prototype;\n  if (!proto) return;\n  const fakeCtx = makeFakeContext();\n  proto.getContext = function () {\n    return fakeCtx;\n  };\n}\n\n/** A minimal 2D context: text metrics return a rough width; everything else is a no-op. */\nfunction makeFakeContext(): any {\n  return {\n    font: '10px Arial',\n    fillStyle: '#000',\n    strokeStyle: '#000',\n    lineWidth: 1,\n    textAlign: 'left',\n    textBaseline: 'alphabetic',\n    globalAlpha: 1,\n    measureText: (s: string) => ({\n      width: (s ? s.length : 0) * 6,\n      actualBoundingBoxAscent: 8,\n      actualBoundingBoxDescent: 2,\n    }),\n    save() {},\n    restore() {},\n    beginPath() {},\n    closePath() {},\n    moveTo() {},\n    lineTo() {},\n    bezierCurveTo() {},\n    quadraticCurveTo() {},\n    arc() {},\n    rect() {},\n    fill() {},\n    stroke() {},\n    fillRect() {},\n    clearRect() {},\n    fillText() {},\n    strokeText() {},\n    translate() {},\n    rotate() {},\n    scale() {},\n    setTransform() {},\n    transform() {},\n    drawImage() {},\n    clip() {},\n    createLinearGradient: () => ({ addColorStop() {} }),\n    getImageData: () => ({ data: new Uint8ClampedArray(4) }),\n  };\n}\n"],"mappings":";AAkBA,IAAI,YAAY;AAShB,eAAsB,mBAAkC;AACtD,MAAI,UAAW;AACf,QAAM,IAAI;AACV,MAAI,OAAO,EAAE,aAAa,eAAe,OAAO,EAAE,WAAW,aAAa;AAGxE,sBAAkB,EAAE,MAAM;AAC1B,gBAAY;AACZ;AAAA,EACF;AAGA,QAAM,EAAE,MAAM,IAAI,MAAM,OAAO,OAAO;AACtC,QAAM,MAAM,IAAI,MAAM,6CAA6C;AAAA,IACjE,mBAAmB;AAAA,EACrB,CAAC;AACD,QAAM,EAAE,OAAO,IAAI;AAEnB,oBAAkB,MAAM;AAExB,IAAE,SAAS;AACX,IAAE,WAAW,OAAO;AAEpB,MAAI;AACF,MAAE,YAAY,OAAO;AAAA,EACvB,QAAQ;AAAA,EAER;AACA,IAAE,cAAc,OAAO;AACvB,IAAE,OAAO,OAAO;AAChB,IAAE,YAAY,OAAO;AACrB,IAAE,gBAAgB,OAAO;AACzB,IAAE,wBAAwB,CAAC,OAA4B,WAAW,MAAM,GAAG,KAAK,IAAI,CAAC,GAAG,CAAC;AACzF,IAAE,uBAAuB,MAAM;AAAA,EAAC;AAEhC,cAAY;AACd;AAGA,SAAS,kBAAkB,QAAmB;AAC5C,QAAM,QAAQ,OAAO,mBAAmB;AACxC,MAAI,CAAC,MAAO;AACZ,QAAM,UAAU,gBAAgB;AAChC,QAAM,aAAa,WAAY;AAC7B,WAAO;AAAA,EACT;AACF;AAGA,SAAS,kBAAuB;AAC9B,SAAO;AAAA,IACL,MAAM;AAAA,IACN,WAAW;AAAA,IACX,aAAa;AAAA,IACb,WAAW;AAAA,IACX,WAAW;AAAA,IACX,cAAc;AAAA,IACd,aAAa;AAAA,IACb,aAAa,CAAC,OAAe;AAAA,MAC3B,QAAQ,IAAI,EAAE,SAAS,KAAK;AAAA,MAC5B,yBAAyB;AAAA,MACzB,0BAA0B;AAAA,IAC5B;AAAA,IACA,OAAO;AAAA,IAAC;AAAA,IACR,UAAU;AAAA,IAAC;AAAA,IACX,YAAY;AAAA,IAAC;AAAA,IACb,YAAY;AAAA,IAAC;AAAA,IACb,SAAS;AAAA,IAAC;AAAA,IACV,SAAS;AAAA,IAAC;AAAA,IACV,gBAAgB;AAAA,IAAC;AAAA,IACjB,mBAAmB;AAAA,IAAC;AAAA,IACpB,MAAM;AAAA,IAAC;AAAA,IACP,OAAO;AAAA,IAAC;AAAA,IACR,OAAO;AAAA,IAAC;AAAA,IACR,SAAS;AAAA,IAAC;AAAA,IACV,WAAW;AAAA,IAAC;AAAA,IACZ,YAAY;AAAA,IAAC;AAAA,IACb,WAAW;AAAA,IAAC;AAAA,IACZ,aAAa;AAAA,IAAC;AAAA,IACd,YAAY;AAAA,IAAC;AAAA,IACb,SAAS;AAAA,IAAC;AAAA,IACV,QAAQ;AAAA,IAAC;AAAA,IACT,eAAe;AAAA,IAAC;AAAA,IAChB,YAAY;AAAA,IAAC;AAAA,IACb,YAAY;AAAA,IAAC;AAAA,IACb,OAAO;AAAA,IAAC;AAAA,IACR,sBAAsB,OAAO,EAAE,eAAe;AAAA,IAAC,EAAE;AAAA,IACjD,cAAc,OAAO,EAAE,MAAM,IAAI,kBAAkB,CAAC,EAAE;AAAA,EACxD;AACF;","names":[]}