@datamoc/mw_games 0.39.1 → 0.41.0

package/CHANGELOG.md

@@ -7,6 +7,95 @@ the public API may still change between minor versions.
 
 ## [Unreleased]
 
+## [0.41.0] - 2026-10-16
+
+`microgm-opt` stays the default SoundFont, and a game that wants another one can now pick it:
+a licence-classified catalogue of a per-instrument collection, a tool that fetches only the
+instruments the game plays, and SoundFont 3 support from the build to the browser, so the
+font reaches the page compressed and is decoded at load.
+
+### Added
+
+- `mwg-soundfonts` (`list`, `fetch`, `convert`, and `@datamoc/mw_games/tools/soundfonts`):
+  `data/soundfont-catalog.json` lists the bundled bank and 18 fonts of the marmooo
+  free-soundfonts collection with each licence classified (public domain, permissive and
+  attribution fetch freely; share-alike, copyleft and unclear ones need `--accept-licence`;
+  TimGM6mb is listed as GPL-2.0 where the collection says public domain). `fetch` takes the
+  instruments named by `--midi` files or `--programs` and merges them into one SoundFont 3 with
+  a `.credits.txt` beside it: nothing is decoded, so no `ffmpeg`. `--sf2` and `convert` decode
+  to a plain SoundFont 2 instead (Ogg Vorbis through `ffmpeg`, a developer-machine tool), about
+  eight times larger.
+- `loadSoundFont`, `decodeSoundFont` and `webAudioSampleDecoder` (`audio`): a game reads the
+  SoundFont 2 or 3 it ships with `loadSoundFont`, a SoundFont 3 decoded once at load through
+  `decodeAudioData` (each sample in a context at its own rate, so no resampling), or through a
+  decoder the caller passes. Checked in Chrome against `ffmpeg`: the same frames, rates and
+  loop points, and the same render. `decodeSoundFont` returns the SoundFont 2 bytes for
+  anything that takes them.
+- `compileResources`, `emitPage` and `mwgPage` embed `.sf3` assets and subset them to the
+  programs the game's MIDI files use, the Ogg bytes copied untouched.
+- `mergeSoundFonts` (`audio`): joins SoundFont 2 files, or SoundFont 3 files with their Ogg
+  bytes untouched, into one, the first font winning a shared (bank, program).
+
+### Fixed
+
+- `parseSoundFont` refuses a SoundFont 3 by name (pointing at `loadSoundFont`) instead of
+  reading its Ogg bytes as PCM and playing noise.
+- A SoundFont whose sample offsets point outside its sample data is refused when read, rather
+  than read beyond it.
+- Decoding a SoundFont 3 bounds what the file can make it allocate: a sample rate outside 400 to
+  200000 Hz is refused, a decoded sample is capped at sixteen million frames and a whole font at
+  134 million (256 MB of audio), in both `decodeSoundFont` and the WebAudio decoder.
+- `mwg-soundfonts` treats the font as untrusted input: a sample whose offsets point outside the
+  sample data is refused instead of copied from beyond it, and `ffmpeg` only ever receives bytes
+  that start with the Ogg magic, with the demuxer forced to Ogg and only the `pipe` protocol
+  allowed, so a crafted "sample" cannot be probed as a playlist that names local files.
+
+## [0.40.1] - 2026-10-15
+
+The published package now carries its documentation the way npm expects to find it: a
+homepage that opens the documentation site, the reference and the tools guide inside the
+tarball, declared Node support, and a `--help` on every command line tool.
+
+### Added
+
+- `package.json` declares `homepage` (the documentation site, so `npm docs` opens it
+  instead of the GitHub README), `bugs` and `engines` (`node >=20.19.0`), and exports
+  `./package.json` so a tool can read an installed module's metadata. `@datamoc/mwg`
+  inherits all of them, plus the keywords it lacked.
+- `REFERENCE.md` and `tools.md` ship in the tarball, so the README's relative links
+  resolve offline from `node_modules`.
+- `REFERENCE.md` sections for `skeleton`, `physics` and `mwl/pyroeis`.
+- JSDoc on the exported symbols of the least documented entry points
+  (`mwl/presentation`, `ai/lua`, `physics/xpbd`, `two-d/presentation`, `3d`, `mwl/pyroeis`,
+  `physics`).
+
+### Fixed
+
+- `mwg-bench`, `mwg-size`, `mwg-sbom`, `mwg-lockstep-server`, `mwg-mwl`, `mwg-uci` now print
+  their usage for `--help` instead of running. `mwg-init --help` no longer creates a folder
+  named `--help`, `mwg-scenarios --help` no longer hangs, and `mwg-placeholder-assets --help`
+  no longer rewrites the assets.
+
+## [0.40.0] - 2026-10-15
+
+A game that plays sampled MIDI no longer ships a whole SoundFont: the asset
+compiler subsets the bank to the instruments its tracks actually use, and the
+package now carries a small WTFPL General MIDI bank to subset from.
+
+### Added
+
+- Build-time SoundFont subsetting: `compileResources`, `emitPage` and `mwgPage` now
+  embed `.mid`/`.midi` and `.sf2` assets, and every embedded SoundFont is subset to
+  the programs the embedded MIDI files actually use (`collectSoundFontUsage` over
+  the shipped tracks, drums as bank 128). `soundFont: false` embeds a font whole,
+  `soundFontUsage` (or `--soundfont-usage=bank:program,...`) names the programs
+  explicitly, and a font with no shipped MIDI embeds whole. An unreadable MIDI or
+  SoundFont fails the build by name instead of shipping silently. The result and
+  both CLIs report each font's kept programs and byte saving: the reference bank
+  `data/microgm-opt.sf2` (2.6 MB, 137 presets, WTFPL, shipped in the npm package
+  for a game to copy into its assets) embeds as 25 KB for a piano-only track.
+
+
 ## [0.39.1] - 2026-10-15
 
 Fixes the 0.39.0 publish gate on Linux: the WebP skip-shrink test asserted one