@datamoc/mw_games 0.1.2 → 0.2.1

package/dist/assets/Streaming.js

@@ -0,0 +1,79 @@
+import { load, release } from './index.js';
+/**
+ * Game-directed background asset staging with bounded, least-recently-used eviction.
+ *
+ * It deliberately does not guess a player's next map: the game supplies bundles it considers
+ * likely. This works with compiled data URIs as a decode/GPU warm-up and with server or
+ * desktop hosts as ordinary asynchronous streaming.
+ */
+export class AssetStream {
+    constructor(options = {}) {
+        this.entries = new Map();
+        this.clock = 0;
+        this.budgetBytes = options.budgetBytes ?? Number.POSITIVE_INFINITY;
+        if (!(this.budgetBytes >= 0))
+            throw new Error('asset stream budget must not be negative');
+        this.loadAssets = options.load ?? load;
+        this.releaseAssets = options.release ?? release;
+    }
+    /** loads one bundle now, then evicts older ready bundles if its budget requires it */
+    async preload(bundle) {
+        if (!bundle.id)
+            throw new Error('asset bundle needs an id');
+        if (bundle.estimatedBytes !== undefined && bundle.estimatedBytes < 0)
+            throw new Error('asset bundle size must not be negative');
+        const existing = this.entries.get(bundle.id);
+        if (existing?.ready) {
+            existing.lastUsed = ++this.clock;
+            return;
+        }
+        const paths = bundle.paths.filter((path) => !this.isRetained(path));
+        if (paths.length > 0)
+            await this.loadAssets([...paths]);
+        this.entries.set(bundle.id, { ...bundle, lastUsed: ++this.clock, ready: true });
+        await this.enforceBudget(bundle.id);
+    }
+    /** preloads bundles in highest-priority-first order; callers may intentionally not await it */
+    async preloadLikely(bundles) {
+        for (const bundle of [...bundles].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0)))
+            await this.preload(bundle);
+    }
+    /** marks a ready bundle as recently used at the moment a scene adopts it */
+    use(id) {
+        const entry = this.entries.get(id);
+        if (!entry?.ready)
+            return false;
+        entry.lastUsed = ++this.clock;
+        return true;
+    }
+    isReady(id) {
+        return this.entries.get(id)?.ready ?? false;
+    }
+    /** explicitly unloads one bundle, even when the configured budget has room */
+    async unload(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return;
+        this.entries.delete(id);
+        const paths = entry.paths.filter((path) => !this.isRetained(path));
+        if (paths.length > 0)
+            await this.releaseAssets(paths);
+    }
+    get estimatedBytes() {
+        return [...this.entries.values()].reduce((sum, entry) => sum + (entry.estimatedBytes ?? 0), 0);
+    }
+    async enforceBudget(protectedId) {
+        while (this.estimatedBytes > this.budgetBytes) {
+            const candidate = [...this.entries.values()]
+                .filter((entry) => entry.id !== protectedId)
+                .sort((a, b) => a.lastUsed - b.lastUsed)[0];
+            if (!candidate)
+                return;
+            await this.unload(candidate.id);
+        }
+    }
+    isRetained(path) {
+        return [...this.entries.values()].some((entry) => entry.ready && entry.paths.includes(path));
+    }
+}
+//# sourceMappingURL=Streaming.js.map

package/dist/assets/Streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Streaming.js","sourceRoot":"","sources":["../../src/assets/Streaming.ts"],"names":[],"mappings":"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"}

package/dist/assets/index.d.ts

@@ -34,4 +34,17 @@ export declare function load(paths: string[]): Promise<void>;
 export declare function texture(path: string): Texture;
 /** a loaded asset of any other kind, such as parsed JSON */
 export declare function get<T>(path: string): T;
+/** true once `load` has resolved for this path and it has not since been `release`d */
+export declare function isLoaded(path: string): boolean;
+/**
+ * Frees assets `load` brought in, destroying any texture among them so it stops holding GPU
+ * memory. For a game with many discrete zones - each with its own tileset or sprite sheet -
+ * this is the counterpart to `world.World.unload`: that drops a map's own state, this drops
+ * the assets it pointed at, once a game decides the player has left an area for good. A path
+ * never loaded (or already released) is silently skipped rather than treated as an error,
+ * since a game unloading a zone it may or may not have visited shouldn't have to check first.
+ */
+export declare function release(paths: string[]): Promise<void>;
+export { AssetStream } from './Streaming.ts';
+export type { AssetBundle, AssetStreamOptions } from './Streaming.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/assets/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/assets/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,OAAO,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;;;GAUG;AAEH,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,MAAM;QACf,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACxC;CACD;AAKD,mEAAmE;AACnE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE1C;AAMD,2EAA2E;AAC3E,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED,wBAAgB,KAAK,IAAI,MAAM,EAAE,CAEhC;AAED,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGzC;AAED,wEAAwE;AACxE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAW5C;AAED;;;;;GAKG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAQzD;AAED,4DAA4D;AAC5D,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAK7C;AAED,4DAA4D;AAC5D,wBAAgB,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAKtC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/assets/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,OAAO,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;;;GAUG;AAEH,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,MAAM;QACf,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACxC;CACD;AAKD,mEAAmE;AACnE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE1C;AAMD,2EAA2E;AAC3E,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED,wBAAgB,KAAK,IAAI,MAAM,EAAE,CAEhC;AAED,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGzC;AAED,wEAAwE;AACxE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAW5C;AAED;;;;;GAKG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAQzD;AAED,4DAA4D;AAC5D,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAK7C;AAED,4DAA4D;AAC5D,wBAAgB,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAKtC;AAED,uFAAuF;AACvF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9C;AAED;;;;;;;GAOG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAI5D;AAED,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/assets/index.js

@@ -59,4 +59,23 @@ export function get(path) {
     }
     return Assets.get(path);
 }
+/** true once `load` has resolved for this path and it has not since been `release`d */
+export function isLoaded(path) {
+    return Assets.cache.has(path);
+}
+/**
+ * Frees assets `load` brought in, destroying any texture among them so it stops holding GPU
+ * memory. For a game with many discrete zones - each with its own tileset or sprite sheet -
+ * this is the counterpart to `world.World.unload`: that drops a map's own state, this drops
+ * the assets it pointed at, once a game decides the player has left an area for good. A path
+ * never loaded (or already released) is silently skipped rather than treated as an error,
+ * since a game unloading a zone it may or may not have visited shouldn't have to check first.
+ */
+export async function release(paths) {
+    const loaded = paths.filter((path) => Assets.cache.has(path));
+    if (loaded.length === 0)
+        return;
+    await Assets.unload(loaded);
+}
+export { AssetStream } from './Streaming.js';
 //# sourceMappingURL=index.js.map

package/dist/assets/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/assets/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAoB1C,kFAAkF;AAClF,IAAI,IAAI,GAAG,EAAE,CAAC;AAEd,mEAAmE;AACnE,MAAM,UAAU,OAAO,CAAC,IAAY;IACnC,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC;AAC9D,CAAC;AAED,SAAS,QAAQ;IAChB,OAAO,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC;AAC1E,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,UAAU;IACzB,OAAO,QAAQ,EAAE,KAAK,SAAS,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,KAAK;IACpB,OAAO,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,IAAY;IAC/B,MAAM,GAAG,GAAG,QAAQ,EAAE,CAAC;IACvB,OAAO,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACjC,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,OAAO,CAAC,IAAY;IACnC,MAAM,GAAG,GAAG,QAAQ,EAAE,CAAC;IACvB,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,GAAG,IAAI,CAAC;IAE7B,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IACxB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACd,UAAU,IAAI,mFAAmF,CACjG,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,KAAe;IACzC,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IAChE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAEjC,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC5B,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,OAAO,CAAC,IAAY;IACnC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,iDAAiD,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAU,IAAI,CAAC,CAAC;AAClC,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,GAAG,CAAI,IAAY;IAClC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,UAAU,IAAI,iDAAiD,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAI,IAAI,CAAC,CAAC;AAC5B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/assets/index.ts"],"names":[],"mappings":"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"}

package/dist/audio/Captions.d.ts

@@ -0,0 +1,15 @@
+import { Signal } from '../core/Signal.ts';
+/**
+ * A visual cue for a sound effect a deaf or hard-of-hearing player cannot hear - a footstep,
+ * a monster's growl, a door creaking. Dialogue already has its own on-screen text (`mwg/stage`'s
+ * `MessageBox` is how every line is shown at all, not an addition over voiced audio), so this
+ * exists for `Sound` alone, not `Music`: background music is not ordinarily captioned the way
+ * an important sound effect is.
+ */
+export interface CaptionEvent {
+    /** shown by a captioning overlay - "footsteps", "door creaks", "a growl nearby" */
+    text: string;
+}
+/** fires whenever a captioned `Sound` plays - a captioning overlay subscribes here, entirely decoupled from `Sound` itself, which never imports anything UI-shaped */
+export declare const onCaption: Signal<CaptionEvent>;
+//# sourceMappingURL=Captions.d.ts.map

package/dist/audio/Captions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Captions.d.ts","sourceRoot":"","sources":["../../src/audio/Captions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC5B,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;CACb;AAED,sKAAsK;AACtK,eAAO,MAAM,SAAS,sBAA6B,CAAC"}

package/dist/audio/Captions.js

@@ -0,0 +1,4 @@
+import { Signal } from '../core/Signal.js';
+/** fires whenever a captioned `Sound` plays - a captioning overlay subscribes here, entirely decoupled from `Sound` itself, which never imports anything UI-shaped */
+export const onCaption = new Signal();
+//# sourceMappingURL=Captions.js.map

package/dist/audio/Captions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Captions.js","sourceRoot":"","sources":["../../src/audio/Captions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAc3C,sKAAsK;AACtK,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,MAAM,EAAgB,CAAC"}

package/dist/audio/Midi.d.ts

@@ -0,0 +1,75 @@
+import { type ToneOptions, type Waveform } from './Synth.ts';
+import type { Playable } from './Playable.ts';
+/**
+ * A Standard MIDI File (SMF) reader plus a player that voices each note through
+ * `audio.synthesizeTone` - `.mid` is a small, patent-free, well-documented event format
+ * (timing and note-on/note-off, not audio), so reading one is ordinary format engineering,
+ * and playback needed exactly the instrument item 120's waveform synth already supplies: a
+ * crude but real, entirely generated-not-borrowed one, closer to a chiptune cover than a
+ * sampled orchestra.
+ */
+export interface MidiNoteEvent {
+    tick: number;
+    type: 'noteOn' | 'noteOff';
+    note: number;
+    velocity: number;
+    channel: number;
+}
+export interface MidiTempoEvent {
+    tick: number;
+    type: 'tempo';
+    /** microseconds per quarter note */
+    microsecondsPerQuarter: number;
+}
+export type MidiEvent = MidiNoteEvent | MidiTempoEvent;
+export interface MidiFile {
+    ticksPerQuarter: number;
+    /** every note-on/note-off and tempo-change event from every track, merged and sorted by tick */
+    events: readonly MidiEvent[];
+}
+/** Reads format 0/1 Standard MIDI File bytes into a flat, tick-ordered event list. */
+export declare function parseMidi(data: ArrayBuffer | ArrayBufferView): MidiFile;
+export interface ScheduledNote {
+    /** seconds from the start of playback */
+    time: number;
+    duration: number;
+    note: number;
+    velocity: number;
+    channel: number;
+}
+/**
+ * Resolves a parsed file's tick-based events into real-time seconds, honouring tempo
+ * changes and pairing each note-on with its matching note-off to find a duration. A
+ * note-on with no matching note-off (a malformed or truncated file) still sounds, for a
+ * short default duration, rather than being dropped silently.
+ */
+export declare function scheduleMidi(file: MidiFile): ScheduledNote[];
+/** MIDI note 69 (A4) is 440 Hz; each semitone is a twelfth root of two step */
+export declare function noteToFrequency(note: number): number;
+export interface MidiPlayerOptions {
+    waveform?: Waveform;
+    /** peak volume; scaled per note by that note's own MIDI velocity */
+    volume?: number;
+    /** voices one scheduled note; defaults to `audio.playTone` */
+    play?: (options: ToneOptions) => Playable;
+}
+/** Plays a parsed `MidiFile` back through `mwg/audio`'s waveform synth, one tone per note, driven by `update(dt)` like every other dt-driven piece of `mwg/core`. */
+export declare class MidiPlayer {
+    private readonly notes;
+    private readonly playFn;
+    private readonly waveform;
+    private readonly volume;
+    private elapsed;
+    private index;
+    private playing;
+    constructor(file: MidiFile, options?: MidiPlayerOptions);
+    play(): void;
+    pause(): void;
+    /** stops and rewinds to the beginning */
+    stop(): void;
+    update(dt: number): void;
+    get isPlaying(): boolean;
+    /** total playback length in seconds, from the last scheduled note's own end */
+    get duration(): number;
+}
+//# sourceMappingURL=Midi.d.ts.map

package/dist/audio/Midi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Midi.d.ts","sourceRoot":"","sources":["../../src/audio/Midi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;;;GAOG;AAEH,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,oCAAoC;IACpC,sBAAsB,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,cAAc,CAAC;AAEvD,MAAM,WAAW,QAAQ;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,gGAAgG;IAChG,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;CAC7B;AAID,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,eAAe,GAAG,QAAQ,CAqFvE;AAED,MAAM,WAAW,aAAa;IAC7B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,aAAa,EAAE,CAmC5D;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,QAAQ,CAAC;CAC1C;AAED,qKAAqK;AACrK,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAC5D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,OAAO,CAAS;IAExB,YAAY,IAAI,EAAE,QAAQ,EAAE,OAAO,GAAE,iBAAsB,EAK1D;IAED,IAAI,IAAI,IAAI,CAEX;IAED,KAAK,IAAI,IAAI,CAEZ;IAED,yCAAyC;IACzC,IAAI,IAAI,IAAI,CAIX;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAgBvB;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,+EAA+E;IAC/E,IAAI,QAAQ,IAAI,MAAM,CAGrB;CACD"}

package/dist/audio/Midi.js

@@ -0,0 +1,186 @@
+import { playTone } from './Synth.js';
+const DEFAULT_TEMPO = 500000; // 120 BPM
+/** Reads format 0/1 Standard MIDI File bytes into a flat, tick-ordered event list. */
+export function parseMidi(data) {
+    const bytes = data instanceof ArrayBuffer
+        ? new Uint8Array(data)
+        : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let offset = 0;
+    const readAscii = (length) => {
+        let text = '';
+        for (let i = 0; i < length; i++)
+            text += String.fromCharCode(bytes[offset + i]);
+        offset += length;
+        return text;
+    };
+    const readUint32 = () => { const v = view.getUint32(offset, false); offset += 4; return v; };
+    const readUint16 = () => { const v = view.getUint16(offset, false); offset += 2; return v; };
+    const readVLQ = () => {
+        let value = 0;
+        for (;;) {
+            const byte = bytes[offset++];
+            value = (value << 7) | (byte & 0x7f);
+            if (!(byte & 0x80))
+                return value;
+        }
+    };
+    if (readAscii(4) !== 'MThd' || readUint32() !== 6)
+        throw new Error('invalid MIDI header chunk');
+    const format = readUint16();
+    const trackCount = readUint16();
+    const division = readUint16();
+    if (format !== 0 && format !== 1)
+        throw new Error(`unsupported MIDI format ${format}`);
+    if (division & 0x8000)
+        throw new Error('SMPTE-based MIDI timing is not supported');
+    const ticksPerQuarter = division;
+    const events = [];
+    for (let t = 0; t < trackCount; t++) {
+        const chunkId = readAscii(4);
+        const chunkLength = readUint32();
+        if (chunkId !== 'MTrk') {
+            offset += chunkLength; //an unknown chunk type is skipped, not an error
+            continue;
+        }
+        const end = offset + chunkLength;
+        let tick = 0;
+        let runningStatus = 0;
+        while (offset < end) {
+            tick += readVLQ();
+            let statusByte = bytes[offset];
+            if (statusByte < 0x80) {
+                statusByte = runningStatus; //this byte is actually the first data byte
+            }
+            else {
+                offset++;
+                if (statusByte < 0xf0)
+                    runningStatus = statusByte; //meta/sysex never become running status
+            }
+            if (statusByte === 0xff) {
+                const metaType = bytes[offset++];
+                const length = readVLQ();
+                if (metaType === 0x51 && length === 3) {
+                    const microsecondsPerQuarter = (bytes[offset] << 16) | (bytes[offset + 1] << 8) | bytes[offset + 2];
+                    events.push({ tick, type: 'tempo', microsecondsPerQuarter });
+                }
+                offset += length;
+            }
+            else if (statusByte === 0xf0 || statusByte === 0xf7) {
+                offset += readVLQ();
+            }
+            else {
+                const type = statusByte & 0xf0;
+                const channel = statusByte & 0x0f;
+                if (type === 0x80 || type === 0x90) {
+                    const note = bytes[offset++];
+                    const velocity = bytes[offset++];
+                    const isNoteOn = type === 0x90 && velocity > 0;
+                    events.push({ tick, type: isNoteOn ? 'noteOn' : 'noteOff', note, velocity, channel });
+                }
+                else if (type === 0xa0 || type === 0xb0 || type === 0xe0) {
+                    offset += 2;
+                }
+                else if (type === 0xc0 || type === 0xd0) {
+                    offset += 1;
+                }
+                else {
+                    throw new Error(`unsupported MIDI status byte 0x${statusByte.toString(16)}`);
+                }
+            }
+        }
+    }
+    events.sort((a, b) => a.tick - b.tick);
+    return { ticksPerQuarter, events };
+}
+/**
+ * Resolves a parsed file's tick-based events into real-time seconds, honouring tempo
+ * changes and pairing each note-on with its matching note-off to find a duration. A
+ * note-on with no matching note-off (a malformed or truncated file) still sounds, for a
+ * short default duration, rather than being dropped silently.
+ */
+export function scheduleMidi(file) {
+    const notes = [];
+    const active = new Map();
+    let tempo = DEFAULT_TEMPO;
+    let lastTick = 0;
+    let time = 0;
+    for (const event of file.events) {
+        time += ((event.tick - lastTick) * tempo) / file.ticksPerQuarter / 1_000_000;
+        lastTick = event.tick;
+        if (event.type === 'tempo') {
+            tempo = event.microsecondsPerQuarter;
+            continue;
+        }
+        const key = `${event.channel}:${event.note}`;
+        if (event.type === 'noteOn') {
+            active.set(key, { time, velocity: event.velocity });
+        }
+        else {
+            const start = active.get(key);
+            if (start) {
+                notes.push({ time: start.time, duration: Math.max(0.01, time - start.time), note: event.note, velocity: start.velocity, channel: event.channel });
+                active.delete(key);
+            }
+        }
+    }
+    for (const [key, start] of active) {
+        const [channel, note] = key.split(':').map(Number);
+        notes.push({ time: start.time, duration: 0.3, note, velocity: start.velocity, channel });
+    }
+    return notes.sort((a, b) => a.time - b.time);
+}
+/** MIDI note 69 (A4) is 440 Hz; each semitone is a twelfth root of two step */
+export function noteToFrequency(note) {
+    return 440 * 2 ** ((note - 69) / 12);
+}
+/** Plays a parsed `MidiFile` back through `mwg/audio`'s waveform synth, one tone per note, driven by `update(dt)` like every other dt-driven piece of `mwg/core`. */
+export class MidiPlayer {
+    constructor(file, options = {}) {
+        this.elapsed = 0;
+        this.index = 0;
+        this.playing = false;
+        this.notes = scheduleMidi(file);
+        this.playFn = options.play ?? playTone;
+        this.waveform = options.waveform ?? 'square';
+        this.volume = options.volume ?? 0.2;
+    }
+    play() {
+        this.playing = this.index < this.notes.length;
+    }
+    pause() {
+        this.playing = false;
+    }
+    /** stops and rewinds to the beginning */
+    stop() {
+        this.playing = false;
+        this.elapsed = 0;
+        this.index = 0;
+    }
+    update(dt) {
+        if (!this.playing)
+            return;
+        this.elapsed += dt;
+        while (this.index < this.notes.length && this.notes[this.index].time <= this.elapsed) {
+            const note = this.notes[this.index];
+            this.playFn({
+                waveform: this.waveform,
+                frequency: noteToFrequency(note.note),
+                duration: note.duration,
+                volume: this.volume * (note.velocity / 127),
+            });
+            this.index++;
+        }
+        if (this.index >= this.notes.length)
+            this.playing = false;
+    }
+    get isPlaying() {
+        return this.playing;
+    }
+    /** total playback length in seconds, from the last scheduled note's own end */
+    get duration() {
+        const last = this.notes.at(-1);
+        return last ? last.time + last.duration : 0;
+    }
+}
+//# sourceMappingURL=Midi.js.map

package/dist/audio/Midi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Midi.js","sourceRoot":"","sources":["../../src/audio/Midi.ts"],"names":[],"mappings":"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"}

package/dist/audio/Music.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Music.d.ts","sourceRoot":"","sources":["../../src/audio/Music.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAW3D,MAAM,WAAW,YAAY;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC;CACpC;AAED;;;;GAIG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,MAAM,CAA6B;IAC3C,MAAM,EAAE,MAAM,CAAC;IAEf,YAAY,OAAO,GAAE,YAAiB,EAGrC;IAED,4EAA4E;IAC5E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,SAAI,GAAG,IAAI,CA4BzC;IAED,IAAI,CAAC,YAAY,SAAI,GAAG,IAAI,CAU3B;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAevB;CACD"}
+{"version":3,"file":"Music.d.ts","sourceRoot":"","sources":["../../src/audio/Music.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAW3D,MAAM,WAAW,YAAY;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC;CACpC;AAED;;;;GAIG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,MAAM,CAA6B;IAC3C,MAAM,EAAE,MAAM,CAAC;IAEf,YAAY,OAAO,GAAE,YAAiB,EAGrC;IAED,4EAA4E;IAC5E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,SAAI,GAAG,IAAI,CA+BzC;IAED,IAAI,CAAC,YAAY,SAAI,GAAG,IAAI,CAU3B;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAevB;CACD"}

package/dist/audio/Music.js

@@ -19,12 +19,15 @@ export class Music {
         this.current = incoming;
         if (fadeDuration <= 0) {
             incoming.volume = this.volume;
-            void incoming.play();
+            // a rejection here means the switch itself (or the previous.pause() right below)
+            // interrupted this play()'s own in-flight load - expected during a track switch,
+            // so swallow it the standard way rather than let it surface as unhandled.
+            void Promise.resolve(incoming.play()).catch(() => { });
             previous?.pause();
             return;
         }
         incoming.volume = 0;
-        void incoming.play();
+        void Promise.resolve(incoming.play()).catch(() => { });
         this.fades.push({ audio: incoming, elapsed: 0, duration: fadeDuration, from: 0, to: this.volume, stopAtEnd: false });
         if (previous) {
             this.fades.push({

package/dist/audio/Music.js.map

@@ -1 +1 @@
-{"version":3,"file":"Music.js","sourceRoot":"","sources":["../../src/audio/Music.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Music.js","sourceRoot":"","sources":["../../src/audio/Music.ts"],"names":[],"mappings":"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"}

package/dist/audio/Orchestrator.d.ts

@@ -0,0 +1,40 @@
+import type { Music } from './Music.ts';
+import type { Sound } from './Sound.ts';
+/** what playing this state's music should look like - `fadeDuration` follows `Music.play`'s own default */
+export interface OrchestratorState {
+    track: string;
+    fadeDuration?: number;
+}
+/**
+ * The data a game writes once instead of scattering `Music.play`/`Sound.play` calls across
+ * every place a fight starts or a menu opens: name the states ("exploring", "combat",
+ * "boss", "menu") and the cues ("hit", "levelUp"), and call `enter`/`trigger` by name from
+ * then on.
+ *
+ * `enter` is idempotent by track, not by state name - two state names that happen to map to
+ * the same track will not refade into each other either, since there is nothing to refade
+ * to. Re-entering "combat" mid-fight (the same fight, the same track) must not reset the
+ * music, which is the one behaviour a direct `Music.play` call at every call site cannot
+ * give you for free: the orchestrator remembers the current track and treats entering an
+ * already-current one as a no-op.
+ *
+ * Cues are separate from states because they are fire-and-forget one-shots (`Sound`, not
+ * `Music`) - folding them into `enter` would conflate "this is where we are" with "this just
+ * happened".
+ */
+export declare class Orchestrator {
+    private states;
+    private cues;
+    private currentTrack;
+    private music;
+    constructor(music: Music);
+    /** defines or replaces one state's music mapping */
+    define(state: string, mapping: OrchestratorState): void;
+    /** switches to `state`'s track, crossfading; a no-op if that track is already playing */
+    enter(state: string): void;
+    /** registers the one-shot sound played by `trigger(event)` */
+    on(event: string, cue: Sound): void;
+    /** plays the sound registered for `event`, if any; silently does nothing otherwise */
+    trigger(event: string): void;
+}
+//# sourceMappingURL=Orchestrator.d.ts.map

package/dist/audio/Orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Orchestrator.d.ts","sourceRoot":"","sources":["../../src/audio/Orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,2GAA2G;AAC3G,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,MAAM,CAAwC;IACtD,OAAO,CAAC,IAAI,CAA4B;IACxC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,KAAK,CAAQ;IAErB,YAAY,KAAK,EAAE,KAAK,EAEvB;IAED,oDAAoD;IACpD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAEtD;IAED,yFAAyF;IACzF,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAQzB;IAED,8DAA8D;IAC9D,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,CAElC;IAED,sFAAsF;IACtF,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE3B;CACD"}

package/dist/audio/Orchestrator.js

@@ -0,0 +1,48 @@
+/**
+ * The data a game writes once instead of scattering `Music.play`/`Sound.play` calls across
+ * every place a fight starts or a menu opens: name the states ("exploring", "combat",
+ * "boss", "menu") and the cues ("hit", "levelUp"), and call `enter`/`trigger` by name from
+ * then on.
+ *
+ * `enter` is idempotent by track, not by state name - two state names that happen to map to
+ * the same track will not refade into each other either, since there is nothing to refade
+ * to. Re-entering "combat" mid-fight (the same fight, the same track) must not reset the
+ * music, which is the one behaviour a direct `Music.play` call at every call site cannot
+ * give you for free: the orchestrator remembers the current track and treats entering an
+ * already-current one as a no-op.
+ *
+ * Cues are separate from states because they are fire-and-forget one-shots (`Sound`, not
+ * `Music`) - folding them into `enter` would conflate "this is where we are" with "this just
+ * happened".
+ */
+export class Orchestrator {
+    constructor(music) {
+        this.states = new Map();
+        this.cues = new Map();
+        this.currentTrack = null;
+        this.music = music;
+    }
+    /** defines or replaces one state's music mapping */
+    define(state, mapping) {
+        this.states.set(state, mapping);
+    }
+    /** switches to `state`'s track, crossfading; a no-op if that track is already playing */
+    enter(state) {
+        const mapping = this.states.get(state);
+        if (!mapping)
+            throw new Error(`Orchestrator: no state defined for "${state}"`);
+        if (mapping.track === this.currentTrack)
+            return;
+        this.music.play(mapping.track, mapping.fadeDuration);
+        this.currentTrack = mapping.track;
+    }
+    /** registers the one-shot sound played by `trigger(event)` */
+    on(event, cue) {
+        this.cues.set(event, cue);
+    }
+    /** plays the sound registered for `event`, if any; silently does nothing otherwise */
+    trigger(event) {
+        this.cues.get(event)?.play();
+    }
+}
+//# sourceMappingURL=Orchestrator.js.map

package/dist/audio/Orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Orchestrator.js","sourceRoot":"","sources":["../../src/audio/Orchestrator.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,YAAY;IAMxB,YAAY,KAAY;QALhB,WAAM,GAAG,IAAI,GAAG,EAA6B,CAAC;QAC9C,SAAI,GAAG,IAAI,GAAG,EAAiB,CAAC;QAChC,iBAAY,GAAkB,IAAI,CAAC;QAI1C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;IAED,oDAAoD;IACpD,MAAM,CAAC,KAAa,EAAE,OAA0B;QAC/C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,yFAAyF;IACzF,KAAK,CAAC,KAAa;QAClB,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,KAAK,GAAG,CAAC,CAAC;QAE/E,IAAI,OAAO,CAAC,KAAK,KAAK,IAAI,CAAC,YAAY;YAAE,OAAO;QAEhD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;QACrD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC;IACnC,CAAC;IAED,8DAA8D;IAC9D,EAAE,CAAC,KAAa,EAAE,GAAU;QAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,sFAAsF;IACtF,OAAO,CAAC,KAAa;QACpB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IAC9B,CAAC;CACD"}

package/dist/audio/Sound.d.ts

@@ -5,6 +5,8 @@ export interface SoundOptions {
     volume?: number;
     /** creates one playable instance for the resolved path; defaults to a real `Audio` element */
     create?: (path: string) => Playable;
+    /** shown by a captioning overlay (via `Captions.onCaption`) every time this sound plays */
+    caption?: string;
 }
 /**
  * A sound effect, pooled so the same clip can overlap itself. A dozen arrows landing in the
@@ -15,6 +17,7 @@ export interface SoundOptions {
 export declare class Sound {
     private pool;
     private next;
+    private caption?;
     volume: number;
     constructor(path: string, options?: SoundOptions);
     play(): void;

package/dist/audio/Sound.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Sound.d.ts","sourceRoot":"","sources":["../../src/audio/Sound.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE3D,MAAM,WAAW,YAAY;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC;CACpC;AAED;;;;;GAKG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,IAAI,CAAK;IACjB,MAAM,EAAE,MAAM,CAAC;IAEf,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,EAKnD;IAED,IAAI,IAAI,IAAI,CAOX;IAED,OAAO,IAAI,IAAI,CAKd;CACD"}
+{"version":3,"file":"Sound.d.ts","sourceRoot":"","sources":["../../src/audio/Sound.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG3D,MAAM,WAAW,YAAY;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC;IAEpC,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,MAAM,EAAE,MAAM,CAAC;IAEf,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,EAMnD;IAED,IAAI,IAAI,IAAI,CAYX;IAED,OAAO,IAAI,IAAI,CAKd;CACD"}