@datamoc/mw_games 0.40.0 → 0.42.0

package/CHANGELOG.md

@@ -7,6 +7,121 @@ the public API may still change between minor versions.
 
 ## [Unreleased]
 
+## [0.42.0] - 2026-10-16
+
+The documentation and asset follow-ups to 0.41.0: SVG minification, a policy for the instruments a
+SoundFont lacks, a playable bridge game with its tutorial, an examples index, and function-level
+examples. One behaviour changes: a drum kit a font lacks now falls back to the standard kit instead of
+a melodic preset.
+
+### Added
+
+- Function-level `@example`s where the examples used to sit on a file or an interface, so an
+  editor's hover shows them: `SaveSystem` (with a migration), `parseDialogueLines`,
+  `parseTwee` (walking a story), `motionDuration` (reduced motion on a slide and on a
+  meaningful bar) and `Theme` (a custom theme, `themeChanged`, the high-contrast swap).
+- `XpbdWorld` documents a bridge: a Warren truss with beams, a `tensionOnly` cable note and a
+  breaking load, tested to hold a light cart, break under a heavy one and repeat exactly.
+- `REFERENCE.md` records what subsetting the bundled bank costs (piano and drums 264 KB,
+  eight essential programs 421 KB, sixteen 585 KB) and what plays for a program the font lacks.
+- `svgo: true` on `compileResources`, `emitPage` and `mwgPage` (and `--svgo` on `mwg-emit`) minifies
+  embedded `.svg` assets through the optional `svgo` package, version 4 or newer, imported only when
+  used. Ids and the `viewBox` are left alone, a file is embedded optimised only when that is smaller,
+  and one svgo cannot parse fails the build by name. On the repository's own 30 SVGs: 13.6%
+  smaller, worst rendered pixel difference 1 in 255. `@datamoc/mw_games/tools/svg-optimise` is the
+  standalone half.
+- `missingProgram: 'piano' | 'synth'` on `parseSoundFont`, `loadSoundFont` and
+  `renderMidiToBufferAsync`: what plays for a program the font lacks, the font's own piano as
+  before or the built-in synthesizer, so a game with a trimmed bank hears the synthesizer's timbre
+  for an instrument it did not ship instead of a piano line.
+- `missingSoundFontPrograms` (`audio`) lists the programs a MIDI usage asks for that a SoundFont 2 or
+  3 does not carry. The asset compiler runs it: each embedded font's result has a `missing` list and
+  `mwg-emit` and `compile-resources` warn about them.
+- `examples/bridge` and the "Build a bridge game" tutorial (`webpage/tutorials/bridge`): a playable
+  truss builder on `XpbdWorld` (three levels, a budget, cables, beams coloured by load, breaking),
+  a deterministic replay of the player's build through `Recorder`/`Player`, best results through
+  `SaveSystem`, reduced motion and the high-contrast theme. The simulation is renderer-free and
+  tested, every tutorial snippet is checked to appear verbatim in the example, and the interface
+  step points at `examples/mwl-presentation` for HUD and windows described as MWL content.
+- An examples index (`tools/build-example-index.mjs`, written by `npm run webpage:docs` to
+  `documentation/examples.html`): for each public module every exported symbol with an `@example`,
+  its first lines and a link to its API page, plus the runnable examples that import the module.
+
+### Fixed
+
+- A request for a drum kit the font lacks falls back to the standard kit, never to a melodic
+  preset: it used to take the same program number from bank 0, so a font with a piano and no drums
+  played the piano where the kick should be.
+
+## [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