@datamoc/mw_games 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to `mwg` are documented here. Format follows
 [Semantic Versioning](https://semver.org/) as of this first release - a 0.y.z version means
 the public API may still change between minor versions.
 
+## [0.18.0] - 2026-09-25
+
+### Added
+
+- `audio.parseMidi` keeps program-change, control-change and pitch-bend events and reports
+  the controller-111 loop marker as `loopStartTick`; `scheduleMidi` notes carry their channel
+  voice (`MidiVoice`: program, bank, gain, pan) and `midiLoopStart` resolves the marker to seconds.
+- `audio.renderMidiToBuffer` renders a parsed MIDI file to stereo PCM frames, offline and
+  deterministic, voiced by an optional game-supplied `SoundFont` or the built-in waveform
+  synth, with the loop region attached.
+- `audio.parseSoundFont` reads SoundFont 2 bytes into layered preset voices.
+- `audio.Channel` (a seekable buffered WebAudio voice with volume, pitch, pan and a loop
+  region) and `audio.AudioBus` (independent BGM/BGS loops, ME jingles that suspend and resume
+  the BGM, overlapping SE one-shots, save and replay with playheads, plain-data snapshots).
+## [0.17.1] - 2026-09-25
+
+### Fixed
+
+- A page built on a Windows checkout refused its own inline script. The HTML parser turns
+  newlines into LF before it hashes an inline script, while `contentSecurityPolicy` hashed the
+  CRLF bytes a `core.autocrlf=true` checkout hands over, so Chrome computed a different hash
+  from the one the policy allowed. The page logged a Content-Security-Policy violation that
+  `mwg-smoke`, the visual smoke and `mwg-bench` read as a page error, the source-page fallback
+  script never ran, and the same build on Linux stayed quiet - which is why no browser job had
+  caught it. Inline scripts are now hashed after CRLF and lone CR become LF; the standalone
+  page's unpacker scripts stay hashed as written, since no parser touches those. A CRLF
+  checkout and an LF checkout now produce the same policy, pinned by a test.
+- The committed-artifact checks no longer read the checkout's line endings. `api:check`,
+  `stats:check`, `sbom:check` and the committed-SBOM test compared generated text against the
+  committed file byte for byte, so a Windows clone failed them on a tree `git diff` called
+  clean; `bundle.distRaw` summed the bytes `tsc` copies out of a source file's comments, which
+  recorded who generated the file rather than what ships.
+
+### Changed
+
+- The `check` job runs on `windows-latest` alongside `ubuntu-latest`, so the two failures above
+  fail the push instead of reaching a Windows contributor. The gates themselves are unchanged,
+  and `fail-fast` is off so one OS failing still shows the other.
+
 ## [0.17.0] - 2026-09-25
 
 ### Security

package/README.md

@@ -15,7 +15,7 @@ playable in the browser with no download, plus the generated API reference.
 planning or porting a demanding game with mwg, with links to the [mwg reference](https://github.com/datamoc/mwg/blob/main/REFERENCE.md)
 and the [mwg Pixel Dungeon study](https://datamoc.github.io/mwg-pixel-dungeon/).
 
-> **Status: pre-alpha (v0.17.0).** Every module in the shared floor below, plus optional
+> **Status: pre-alpha (v0.17.1).** Every module in the shared floor below, plus optional
 > 3D, mobile (Capacitor) and desktop (WebView2) packaging, is built and tested - see
 > [ROADMAP.md](https://github.com/datamoc/mwg/blob/main/ROADMAP.md) for open work, and
 > [CLOSED.md](https://github.com/datamoc/mwg/blob/main/CLOSED.md) for the full, numbered shipped history.

package/dist/audio/Channels.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Buffered WebAudio voices for music and jingles: a `Channel` plays one looping track
+ * with volume, pitch, pan, a loop region and a seekable playhead, and an `AudioBus`
+ * wires channels into the four lifetimes a role-playing game needs from its audio.
+ * BGM and BGS are two independent looping streams, ME is an interrupting jingle that
+ * pauses the BGM and resumes it where it left off, SE is overlapping one-shots, each
+ * with its own volume, pitch and pan per play.
+ *
+ * The browser owns the clock and the nodes, so both classes take the pieces they
+ * cannot build themselves as injectables: the `AudioContext` in the constructor and,
+ * for the bus, a `load` function turning a kind and a name into a decoded buffer.
+ * Tests hand in fakes for both, the same way `Sound` and `Music` take `create()`.
+ */
+/** seconds within a buffer: the region a looping track repeats */
+export interface LoopRegion {
+    start: number;
+    end: number;
+}
+export interface ChannelPlayOptions {
+    /** level, 0 to 1 */
+    volume?: number;
+    /** playback ratio, 1 unchanged, above 1 higher and faster */
+    pitch?: number;
+    /** stereo position, -1 (left) to 1 (right) */
+    pan?: number;
+    /** start offset in seconds */
+    pos?: number;
+    /** region to repeat, null repeats the whole buffer */
+    loop?: LoopRegion | null;
+    /** false plays once through for jingles; true repeats */
+    repeat?: boolean;
+}
+/** plain-data playback state: parameters plus playhead, without the buffer */
+export interface ChannelState {
+    volume: number;
+    pitch: number;
+    pan: number;
+    pos: number;
+}
+/**
+ * One buffered voice: a decoded track with a loop region and a playhead the game can
+ * read and move. Replaying the same buffer restarts it; changing parameters mid-play
+ * never does.
+ *
+ * @example
+ * ```ts
+ * import { Channel } from '@datamoc/mw_games/audio';
+ *
+ * declare const context: AudioContext;
+ * declare const buffer: AudioBuffer;
+ *
+ * const channel = new Channel(context);
+ * channel.play(buffer, { volume: 0.8, pitch: 1, pan: 0, loop: { start: 1, end: 4 } });
+ * console.log(channel.position());
+ * channel.stop();
+ * ```
+ */
+export declare class Channel {
+    private readonly context;
+    private readonly destination;
+    private source;
+    private gainNode;
+    private pannerNode;
+    private buffer;
+    private params;
+    private loopRegion;
+    private repeat;
+    private startedAt;
+    private offset;
+    constructor(context: AudioContext, destination?: AudioNode);
+    get isPlaying(): boolean;
+    get duration(): number;
+    /** starts the buffer with these parameters, stopping whatever played before */
+    play(buffer: AudioBuffer, options?: ChannelPlayOptions): void;
+    /** retunes the playing voice in place: no restart, no seek */
+    update(params: {
+        volume?: number;
+        pitch?: number;
+        pan?: number;
+    }): void;
+    /** stops the voice, fading out over `fadeSeconds` first when positive */
+    stop(fadeSeconds?: number): void;
+    /** seconds into the buffer, wrapping inside the loop region while it repeats */
+    position(): number;
+    /** moves the playhead, restarting the voice when it plays */
+    seek(pos: number): void;
+    /** plain-data state for saves and transfers: parameters plus playhead */
+    state(): ChannelState;
+    /** applies plain-data state, restarting the voice at its playhead when it plays */
+    restore(state: ChannelState): void;
+    private clearNodes;
+}
+export type BusKind = 'bgm' | 'bgs' | 'me' | 'se';
+/**
+ * A named track request in role-playing units: volume 0 to 100, pitch 50 to 150
+ * percent, pan -100 to 100, an optional resume position in seconds.
+ */
+export interface BusTrack {
+    name: string;
+    volume?: number;
+    pitch?: number;
+    pan?: number;
+    pos?: number;
+}
+/** a resolved track request: every parameter filled in, ready to store or restore */
+export interface SavedBusTrack {
+    name: string;
+    volume: number;
+    pitch: number;
+    pan: number;
+    pos: number;
+}
+/** a decoded track: its buffer plus the region it repeats, if any */
+export interface LoadedTrack {
+    buffer: AudioBuffer;
+    loop?: LoopRegion | null;
+}
+/** turns a kind and a name into a decoded buffer, or null when it cannot */
+export type BusLoader = (kind: BusKind, name: string) => Promise<LoadedTrack | null>;
+/** plain-data bus state for saves and transfers: tracks plus memorized ones */
+export interface BusSnapshot {
+    bgm: SavedBusTrack | null;
+    bgs: SavedBusTrack | null;
+    savedBgm: SavedBusTrack | null;
+    savedBgs: SavedBusTrack | null;
+}
+export interface AudioBusOptions {
+    destination?: AudioNode;
+    load?: BusLoader;
+}
+/**
+ * The four audio lifetimes of a role-playing game over two `Channel` voices: BGM and
+ * BGS loop independently, an ME jingle suspends the BGM and resumes it where it left
+ * off, SE plays overlapping one-shots. Replaying the current track only retunes it;
+ * save and replay memorize a track with its playhead for menus and transfers.
+ *
+ * @example
+ * ```ts
+ * import { AudioBus } from '@datamoc/mw_games/audio';
+ *
+ * declare const context: AudioContext;
+ *
+ * const bus = new AudioBus(context, { load: (_kind, _name) => Promise.resolve(null) });
+ * void bus.playBgm({ name: 'town', volume: 90, pitch: 100, pan: 0 });
+ * console.log(bus.snapshot());
+ * ```
+ */
+export declare class AudioBus {
+    private readonly context;
+    private readonly destination;
+    private readonly load;
+    private readonly bgmChannel;
+    private readonly bgsChannel;
+    private readonly tracks;
+    private readonly saved;
+    private readonly requests;
+    private me;
+    private meToken;
+    private suspendedBgm;
+    private readonly seNodes;
+    constructor(context: AudioContext, options?: AudioBusOptions);
+    /** loops this BGM, or retunes it when it already loops */
+    playBgm(track: BusTrack): Promise<void>;
+    /** loops this BGS, or retunes it when it already loops */
+    playBgs(track: BusTrack): Promise<void>;
+    stopBgm(): void;
+    stopBgs(): void;
+    fadeOutBgm(seconds?: number): void;
+    fadeOutBgs(seconds?: number): void;
+    /** the intended track with its live playhead, or the one an ME suspended */
+    currentTrack(kind: 'bgm' | 'bgs'): SavedBusTrack | null;
+    /** memorizes the playing BGM with its playhead; replay restores it */
+    saveBgm(): SavedBusTrack | null;
+    /** memorizes the playing BGS with its playhead; replay restores it */
+    saveBgs(): SavedBusTrack | null;
+    replayBgm(): Promise<void>;
+    replayBgs(): Promise<void>;
+    /**
+     * Plays a jingle once, suspending the BGM and resuming it where it left off when
+     * the jingle ends. A BGM started mid-jingle takes over instead of being resumed over.
+     */
+    playMe(track: BusTrack): Promise<void>;
+    /** stops the jingle, resuming the suspended BGM unless told not to */
+    stopMe(resume?: boolean): void;
+    /** plays one overlapping sound effect */
+    playSe(track: BusTrack): Promise<void>;
+    stopSe(): void;
+    stopAll(): void;
+    /** plain-data bus state for saves and transfers */
+    snapshot(): BusSnapshot;
+    /** replays plain-data bus state, reloading every named track */
+    restore(state: BusSnapshot | null | undefined): void;
+    private static normalize;
+    private playLoop;
+    private stopMeNodes;
+    private finishMe;
+}
+//# sourceMappingURL=Channels.d.ts.map

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

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