@datamoc/mw_games 0.42.0 → 0.44.2

package/CHANGELOG.md

@@ -7,6 +7,132 @@ the public API may still change between minor versions.
 
 ## [Unreleased]
 
+## [0.44.2] - 2026-10-17
+
+Hardening of `.mwp` content package loading, found by security reviews of 0.44.0 and 0.44.1.
+Versions 0.44.0 and 0.44.1 were tagged and released on GitHub but their npm stages were rejected and
+they were never published, so 0.44.2 is the first public release of everything in their entries below.
+
+### Fixed
+
+- A WAV header with a zero sample rate or block align fell back to its declared `byteRate`, so
+  a lying header could still shorten the measured duration. The rate is now the lowest of the
+  declared one, `sampleRate * blockAlign` and `sampleRate * channels * ceil(bits / 8)`, and a zero in
+  any of them refuses the file as unreadable.
+
+## [0.44.1] - 2026-10-17
+
+> Superseded by 0.44.2 and never published to npm.
+
+Hardening of `.mwp` content package loading, found by a security review of 0.44.0.
+
+### Fixed
+
+- A package could multiply its work through repeated file imports: depth was bounded at 4 but
+  the total was not. Imports now share a budget of 64 reads per package document.
+- An import or a `main` document named like an `Object.prototype` member (`constructor`) crashed
+  the loader with a `TypeError`; lookups are now own-property only and report a
+  `PackageFormatError`.
+- A WAV header declaring a large `byteRate` could shorten the duration measured against
+  `maxAudioSeconds`; the lower of the declared rate and `sampleRate * blockAlign` is used.
+
+## [0.44.0] - 2026-10-17
+
+> Superseded by 0.44.2 and never published to npm.
+
+Retro-audio integration contracts (a MIDI engine registry, streaming playback, budgets, content packages and a command line tool), player-facing audio settings, and the interface follow-ups of the last Pontifex round. The parked items 393, 394, Syzygy and NNUE are closed rather than waiting on files or weights that will not arrive, and a simplification pass over the whole tree removes duplicated code.
+
+### Added
+
+- Pontifex follow-up points 51-54 (roadmap 443-446): `ScrollBox` now owns its `hitArea`
+  (its viewport, kept current by `resize`/`setContentHeight`, with a `viewportWidth`
+  getter); `DropdownView` and `ScrollText` gain `resize(width)`, and `DropdownViewOptions`
+  gains `maxWidth` capping `autoWidth`; a transition requested while one is playing is
+  ignored by default, with `queue: true` / `interrupt: true` in `TransitionOptions` and the
+  `transitionDisposition` rule exported, `Game.transitioning` also reporting a queued
+  transition; and `Dropdown.setHighlight` now opens the list as documented, so
+  `setHighlight(i); confirm()` picks a row and the next opening shows it.
+- Retro-audio integration (roadmap 431-442): a named `MidiSynth` engine
+  registry with fallback diagnostics, the streaming `Playable` contract, bus render budgets
+  and decoder guards, `.mwp` content packages with capability policy and ROM refusal, data
+  sound effects, an off-main-thread audio host, adaptive music, the `mwg-audio` tool, and
+  the `testing` doubles (`FakeRetroPlayer`, fake WebAudio graph) - documented in the
+  README's "Retro audio" section, REFERENCE and `docs/listening-protocol.md`. Player-facing
+  settings (`AudioSettings` with PAL/NTSC, dynamics and softening rules), live Web MIDI
+  (`connectWebMidi`), dropped `.syx` banks with DX7 patch names and audition (`SyxBank`),
+  and the oscilloscope/tracker data cores (`waveformEnvelope`, `trackerPattern`) complete
+  item 441.
+
+### Changed
+
+- Simplification pass over the tree, with no change to the public API: one shared radix-2 FFT
+  in `audio`, `HexSkirmish.reachableCosts` built on `core`'s `weightedFlood` (a negative
+  terrain move cost is now ignored instead of accepted), `tourney` and `Tactics` using the
+  `Engine` job default and `core`'s `cellInside`, a single byte-joining helper in the
+  `mwl` package container, and hand-written clamps replaced by `core`'s `clamp` across
+  `ui`, `render`, `battle`, `physics` and `audio`.
+- Roadmap: items 393 (Ableton and Reaper groove formats), 394 (the Magenta humanizer tier),
+  Syzygy and NNUE are closed; 401 is the only numbered item left, waiting on a port session.
+
+## [0.43.0] - 2026-10-17
+
+Scrolling, tooltips and screen transitions for interface-heavy games, a MIDI music player and
+SoundFont tooling, and the shipped command line tools made to work from an installed package on
+Node 20.19. `@datamoc/pyroeis` moves to 0.9.1, which ends the last moderate audit advisory.
+
+### Added
+
+- Scrolling and transitions asked for by a bridge game (Pontifex feedback 45-50):
+  - `ScrollBox`: `touch` (drag to scroll, coasting on release, `ScrollDrag`), `handleKey` for line, page and
+    ends, a draggable scrollbar thumb and a clickable track, and `autoHeight`. A drag no longer clicks the row
+    it ends on.
+  - `DropdownView`: `maxVisibleRows` (the list scrolls), an opaque backdrop, `autoWidth`, opening with the chosen
+    row in view, `handleKey`, `handleOutsideClick` and `fitBelow`.
+  - `ScrollText` (a wrapped label that sizes itself and scrolls), `MarqueeLabel` (a long line sliding inside
+    its width, still under reduced motion), `ellipsize` and `truncateLines`.
+  - `TooltipHost`: tooltips on a touch long-press and on disabled buttons, from rectangles instead of pointer
+    events. `Button` gains `tooltip`, `setIcon` and a second icon for the selected state (`iconSelected`).
+  - `Game.switchScene(Next, { transition, duration, easing, pause })`, `Game.transition(swap, options)` and
+    `Scene2D.transitionTo`: `tileShrink`, `shrink`, `pop`, `grow`, `slide`, `iris` and `dissolve` over a snapshot of
+    the outgoing scene, skipped under reduced motion, with `Game.transitioning` and `Game.active`. `Window.open`
+    and `Window.close` take an animation (`pop`, `grow`, `slide`, `fade`). The bridge example switches level
+    with `tileShrink`.
+  - The dist grew 3.8% with them; the size baseline is moved to match.
+- `limits` (`SoundFontLimits`: `sampleFrames`, `totalFrames`) on `decodeSoundFont`, `loadSoundFont` and
+  `webAudioSampleDecoder` raises or lowers what a SoundFont 3 may decode to, instead of the fixed 16 M
+  frames per sample and 128 M per font. The sample-rate bounds stay: the format itself stops at 50 kHz.
+- `@example`s for the `3d` functions that need no renderer (`gridPoint3D`, `cellAt`, `heightAt`,
+  `buildHeightIndex`, `resolveCapsuleAgainstGrid`, `parseVox`). The generated API reference now covers
+  the subpaths the root barrel does not re-export (`3d`, `physics`, `ai/lua`, `mwl/pyroeis`, `testing`,
+  `threads`, `headless`, `assets/binary`), so the examples index links 803 of 813 symbols to a page.
+- `npm run build:bridge-tutorial` regenerates the bridge tutorial from `tools/templates` and the example's
+  own source. `npm run bins:smoke` packs the project, installs it in an empty folder and runs every `mwg-*`
+  bin with `--help`; CI runs it, with the library build, on Node 20.19.0, the floor `engines` claims.
+- `.gitattributes` (`* text=auto eol=lf`) ends the CRLF warnings on Windows checkouts.
+- An optional, reproducible 314 KB SoundFont subset covering six essential presets,
+  with provenance and synthetic fallback for the instruments outside it.
+- `AudioBus` loads embedded audio and MIDI by default through `createAudioLoader`, with
+  shared decoding, worker MIDI rendering and optional SoundFont settings across lifetimes.
+- `MusicPlayer` controls rendered MIDI or decoded buffers with pause, resume, seek,
+  volume and a track-completion signal; `toAudioBuffer` copies rendered stereo samples
+  into a Web Audio buffer. The README shows the supplied SoundFont and worker playback path.
+- Page byte budgets and potentially unused asset reports in the standalone build pipeline.
+- XPBD link payloads, explicit rupture, geometric queries and state comparison helpers.
+- Schema-directed `nodesToObjects` conversion and optional literal unions generated from
+  MWL table columns. Optional attributes are documented alongside the schema.
+- Generated starter projects include a pre-commit hook for typecheck and tests, an activation
+  command and ignores for local agent state.
+- Sawtooth sound synthesis, playback attempt counts and a shared browser test exposure hook.
+
+### Fixed
+
+- `mwg-uci`, `mwg-openings` and `mwg-tablebases` imported `../src/...`, which the package does not ship, so
+  they failed in every installed copy; they load `dist` there, as the other tools already did.
+- The bridge example keeps a saved best only when the new crossing costs less, or costs the same and sags
+  less, instead of replacing it by any cheaper one.
+- Fixed waits that failed on a loaded machine: the browser smoke waits for drawn frames instead of 250 ms,
+  the driver test polls for its tap instead of sleeping 300 ms, and the WebP noise test is seeded.
+
 ## [0.42.0] - 2026-10-16
 
 The documentation and asset follow-ups to 0.41.0: SVG minification, a policy for the instruments a

package/README.md

@@ -8,6 +8,10 @@ events, quests, stats and turn order underneath are the same either way.
 Licensed under the [MPL-2.0](LICENSE): games built with `mwg` carry no licence obligation
 of their own; improvements to `mwg`'s own files are shared back.
 
+The canonical npm package is `@datamoc/mw_games`; use that name for installation, imports,
+tools and bundled data such as `data/microgm-opt.sf2`. `@datamoc/mwg` remains a compatible
+re-export package for existing projects. The recipes here consistently use the canonical name.
+
 **[Live examples and API docs](https://datamoc.github.io/mwg/)**: every example below,
 playable in the browser with no download, plus the generated API reference.
 
@@ -15,7 +19,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.36).** Every module in the shared floor below, plus optional
+> **Status: pre-alpha.** 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.
@@ -184,6 +188,85 @@ private or trustworthy, since the page that rewrites a save can recompute any ch
 never put a secret in a save or in settings (an account token, a password, a licence key), and
 treat a save as the player's own editable file, which it is.
 
+## Loading assets and input
+
+`await load(['vehicles/car.svg'], { resolution: 2 })` rasterizes SVG assets at twice
+their logical resolution, keeping them sharp when a camera zooms in. Import `load` from
+`@datamoc/mw_games/assets`. `loadSvgParts(path, { resolution: 2 })` loads top-level SVG
+groups as textures in their authored stacking order.
+
+Input events live under the `Input` namespace: import `{ Input }` from
+`@datamoc/mw_games/core` and subscribe with `Input.onAction.add(...)`. `onAction` is not a
+direct core export. `Input.attachPointer` supplies pointer and drag events for mouse and touch.
+
+## Audio
+
+Use `AudioBus` for one playback API across ordinary audio and MIDI assets. Its default
+loader reads embedded assets, detects MIDI by its header and renders it on a worker.
+`playBgm`/`playBgs` loop, while `playMe`/`playSe` play once; all take the same
+`{ name, volume, pitch, pan }` fields (volume 0-100, pitch 100 unchanged, pan -100 to 100).
+Pass `load: createAudioLoader(context, { midi: { soundFontBytes, missingProgram: 'synth' } })`
+to use a SoundFont. `Sound` remains useful for pooled HTML audio effects and `MusicPlayer`
+for a seekable jukebox.
+
+`Sound` pools short effects. `sound.play(0.7, 1.1)` sets gain and pitch for that play;
+`synthesizeSound({ waveform: 'sawtooth', frequency: 110, duration: 0.2 })` makes a pooled
+effect without an asset file. `Sound.plays` counts started playback attempts for browser tests.
+
+For MIDI music, copy the supplied `data/microgm-opt.sf2` from the installed package into
+your assets folder alongside the `.mid` files. `mwgPage({ assets: 'assets' })` automatically
+reduces the embedded SoundFont to the programs those MIDI files use. Load both through
+`loadBinary`, then render once on a worker and play the resulting buffer:
+
+For a smaller starting bank, `data/microgm-essential.sf2` supplies piano, guitar, violin,
+trumpet, flute and standard drums in 314 KB. Use it instead of the full bank below, with
+`missingProgram: 'synth'` for the remaining instruments. Both banks retain their WTFPL licence.
+
+```ts
+import { loadBinary, getBinary } from '@datamoc/mw_games/assets';
+import { MusicPlayer, renderMidiToBufferAsync } from '@datamoc/mw_games/audio';
+
+const player = new MusicPlayer(new AudioContext(), { volume: 0.7 });
+await loadBinary(['music/theme.mid', 'soundfonts/microgm-opt.sf2']);
+player.load(await renderMidiToBufferAsync(getBinary('music/theme.mid'), {
+  soundFontBytes: getBinary('soundfonts/microgm-opt.sf2'),
+  missingProgram: 'synth',
+}));
+player.play({ repeat: true });
+```
+
+Start playback from a player gesture. Call `player.update()` each frame to dispatch
+`onEnded` for a nonrepeating track; that signal lets the game choose its next track.
+`pause()`, `resume()`, `position()` and `seek(seconds)` share the same playhead.
+`toAudioBuffer(context, rendered)` also converts a render for direct `Channel` use.
+`missingProgram: 'synth'` voices instruments absent from the font with the built-in synth.
+
+To catch page growth, set `mwgPage({ maxPageBytes: 1_500_000 })`. Its build report lists
+embedded paths not found literally in the generated game script as potentially unused;
+paths assembled at runtime need manual review. `assetFiles` selects exact asset paths to embed.
+
+### Retro audio
+
+A retro-instrument package (an MT-32, OPL or chip synth of its own) plugs into mwg through
+contracts mwg owns, so the core never depends on the package. It registers a `MidiSynth`
+under a name with `registerMidiSynth('retro:mt32', factory)`; content then asks for that
+name and `resolveMidiSynth` walks the request, the SoundFont and the built-in synth in
+order, firing `onMidiSynthFallback` whenever a different engine ends up voicing the file.
+Endless or machine-code formats (NSF, SID, SPC) play through the streaming `Playable`
+contract (`StreamPlayable`, `StreamChannel`) under named decoder guards
+(`decoderLimits`, `DecodeBudgetError`): input ceilings, an instruction budget per second
+of sound, and bounded inflation, so untrusted files fail by name instead of hanging.
+Rendered tracks are budgeted (`TrackCache`, `createBudgetedLoader`): a five-minute stereo
+render is about 100 MB, so the bus caps decoded megabytes rather than keeping every track
+forever. Synthesised effects are data, not files: `SfxBank` builds them from definitions
+with a fixed seed, so audio never disturbs a lockstep simulation (its triggers are
+deterministic; the audio itself is not in the lockstep state, and A/V sync follows the
+game frame counter, not the wall clock). The `mwg-audio` tool inspects, converts, renders,
+budgets and compares these formats from the command line, and `spectralDistance` gives a
+first automated check between two renders. What no automation settles is whether a render
+sounds right: the A/B listening protocol in `docs/listening-protocol.md` is the place to
+record those verdicts.
+
 ## Capability spec
 
 The definition of done for 1.0, drawn from what each of the nine references actually

package/REFERENCE.md

@@ -530,6 +530,14 @@ batcher/high-shader internals are confined to `ColorTransformBatcher.ts`.
   `sequence(steps)` (item 302) chains fade/hold/flash steps end to end as one call, for the
   hold-then-fade-back transition the four individual methods cannot express alone; `update`
   keeps returning false at every step boundary, true only once the whole sequence finishes.
+- `SceneTransition`/`TransitionOptions`/`TransitionRunner`/`TransitionDisposition` + `transitionDisposition`, `tileShrink`, `shrink`, `pop`, `grow`, `slide`, `iris`
+  and `dissolve` - screen transitions: `Game.switchScene(Next, { transition, duration, easing })` photographs the
+  outgoing scene and animates it away (or grows the new one over it), `Scene2D.transitionTo(swap, options)` does
+  the same for a scene changing its own content, `Game.transitioning` tells a scene to ignore input, a second
+  transition requested while one plays is ignored unless its options say `queue: true` or `interrupt: true`
+  (`transitionDisposition` is that rule as a plain function), and
+  reduced motion skips it. `tileDelays`, `tileProgress`, `popScale`, `openAnimationFrame` and `resolveEasing` are the
+  timing as plain functions.
 - `ActorAnimator` - an idle/move/action animation state machine with one interruption rule.
 - `StatusVisuals` - composes every active status effect's colour additively onto a sprite's
   `colorAdd` (item 301), instead of one status winning by declaration order; each channel clips
@@ -663,7 +671,9 @@ Windows, lists, message boxes, HUD widgets - all themed from one live-swappable
 - `BitmapLabel`/`bitmapLabelStyle` - bitmap-font-backed text, for a HUD value redrawn
   every frame where `Label`'s per-string texture re-render would be wasteful.
 - `NinePatch` - a resizable nine-slice panel.
-- `Window` - a themed panel container. `close()` frees the window and its contents and is
+- `Window` - a themed panel container. `open({ animation, from })` plays `pop`, `grow`, `slide` or `fade`
+  (`WindowAnimation`) and `close({ animation })` plays it backwards before closing, both driven by
+  `update(dt)` and skipped under reduced motion. `close()` frees the window and its contents and is
   idempotent; `closed` is the guard for the caller's reference afterwards (input and `place` on a
   closed window are no-ops), and `WindowStack.push` refuses one with a named error. A window's own
   area is not clickable, so a click travels to whatever is under it; `blocker: true` adds the
@@ -695,9 +705,15 @@ Windows, lists, message boxes, HUD widgets - all themed from one live-swappable
 - `Spinner`/`SpinnerOptions` + `spinValue` - an up/down numeric stepper; `spinValue` is the rule
   (snap to the step, then clamp at the ends or wrap past them).
 - `DropdownView`/`DropdownViewOptions` - the widget over a `Dropdown` model: a button showing the choice
-  that opens a column of `Button`s, the chosen one marked with `Button.setSelected`.
+  that opens a column of `Button`s on an opaque backdrop, the highlighted one marked with
+  `Button.setSelected`. `maxVisibleRows` makes a long list scroll (wheel, touch, keys, scrollbar) and it opens with
+  the chosen row in view; `autoWidth` fits the longest label, `maxWidth` caps that widening, and `resize(width)`
+  re-lays the button and list in place; `handleKey` (arrows, Page, Home/End, Enter,
+  Escape) and `handleOutsideClick` are what the scene forwards from its own input; `fitBelow` limits the
+  rows to what the viewport leaves under the button.
 - `Dropdown`/`DropdownOption`/`DropdownOptions` - a renderer-free option button: a selected entry,
-  an open list, a highlight that starts on the selection and skips disabled options.
+  an open list, a highlight that starts on the selection and skips disabled options. `setHighlight(i)`
+  opens the list on that row, so `setHighlight(i); confirm()` is a whole programmatic pick.
 - `TextModel`/`TextModelOptions` - the editing state behind a text field, fed by `core.Input`'s
   `onText`: caret, anchor, selection-replacing edits, a length cap and a mask. Renderer-free.
   `multiline` keeps real newlines with row navigation (`lineCount`, `caretLine`, `lineRange`,
@@ -727,8 +743,20 @@ Windows, lists, message boxes, HUD widgets - all themed from one live-swappable
   highlight.
 - `TreeView`/`TreeNode`/`TreeRow`/`TreeViewOptions` - a renderer-free collapsible tree, flattened to
   the rows on screen; collapsing the branch the highlight is inside lands it on the branch.
-- `ScrollBox`/`ScrollBoxOptions` + `scrollOffset` - a clipped viewport with a themed scrollbar;
-  `scrollOffset` is the clamping rule the wheel, `scrollBy` and `scrollIntoView` all share.
+- `ScrollBox`/`ScrollBoxOptions`/`ScrollKey` + `scrollOffset` - a clipped viewport with a themed scrollbar;
+  `scrollOffset` is the clamping rule the wheel, `scrollBy` and `scrollIntoView` all share. `touch: true` lets a
+  finger drag the content (a drag cancels the tap on the row under it) and coast on release, `handleKey`
+  scrolls by line, page and to either end, the thumb drags and the track jumps, and `autoHeight` sizes the
+  viewport to the content up to `height`. The box owns its `hitArea` (its viewport, kept current by `resize` and
+  `setContentHeight`), so the wheel reaches it without a row under the pointer. `update(dt)` drives the coasting.
+- `ScrollDrag` - touch scrolling as plain numbers (`start`/`move`/`end`/`step`): how far the content follows a
+  finger and how it coasts after release, with no pointer events or clock of its own.
+- `ScrollText`/`ScrollTextOptions` - a wrapped `Label` in a self-sizing `ScrollBox`: as tall as the text up to
+  `maxHeight`, scrolling beyond it, re-measured by `setText` and re-wrapped in place by `resize(width)`.
+- `MarqueeLabel`/`MarqueeLabelOptions` + `marqueeOffset` - one line that stays on one line: a long text slides
+  back and forth in a clipped window (and holds still, cut short, under reduced motion).
+- `ellipsize` and `truncateLines` - cut a text to a width or a number of lines, ending in an ellipsis, with the
+  caller supplying the measuring function.
 - `flowLayout(items, width, { gap, align })` - left-to-right rows that wrap, returning each item's
   position and the total height: a toolbar that takes two rows on a phone.
 - `Grid`/`GridSpec`/`GridTrack` + `resolveAnchor`/`anchorAlign` with `Anchor`/`AnchorSpec`/
@@ -774,6 +802,10 @@ Windows, lists, message boxes, HUD widgets - all themed from one live-swappable
 - `Toast` - a queued, timed pop-up notification (fade in, hold, fade out).
 - `Tooltip` - a hover explanation over a themed `Window`: a frame-driven hover delay, and
   edge-aware placement that flips rather than letting the panel run off screen.
+- `TooltipHost`/`TooltipHostOptions`/`TooltipTarget` - drives one `Tooltip` from rectangles: a press that rests
+  for `longPress` seconds shows the text on a touch screen, and a disabled `Button` (which gets no pointer
+  events) is still explained from its bounds and its `tooltip`. `attach(pointer)` wires an
+  `Input.attachPointer` tracker.
 - `HelpScreen` - a topic-list-plus-body help/controls screen.
 - `StatsScreen` - a player-stats display screen.
 - `LoadingScreen` - a progress-bar loading screen wired to `core.LoadQueue`.
@@ -895,11 +927,17 @@ reach the compiled asset map without it.
   (`force`, smoothed `ratio`, `peakRatio`) and `onBreak` when a link passes its strength; `ground` (a height or a function of x) holds nodes
   on a surface with `groundFriction`. The engine of
   Pontifex, generalised: bridges, trusses, cranes, anything where the question is which beam fails.
+  `XpbdWorld<T>`/`XpbdLink<T>`/`XpbdLinkSpec<T>` carry game-owned link `data` without
+  affecting the solver. `breakLink(index)` dispatches rupture once. `linksInBox` includes
+  segment crossings; `linksNear` orders nearby unbroken segments by distance. `snapshot()`
+  returns positions, velocities, load state and queued forces as detached arrays; `hash()`
+  compares their exact numeric bits for runs with the same configuration. Payloads and ground
+  callbacks are excluded. The bridge example applies a moving vehicle's weight with `applyForce`.
 - `PhysicsWorld` (`@datamoc/mw_games/physics`) - rigid bodies and constraints in plain TypeScript, no engine
   dependency: `addBox`/`addCircle`/`addConstraint`/`remove`, `update(dt)` from
   `Scene.update`, `onContact`, `alpha` for interpolation. A constraint with `maxStretch` breaks when pulled
   that far past its rest length (`onBreak`, `stretchOf`). Bodies never spin; `angle` is a display offset.
-- `synthesizeTone`/`synthesizeSound`/`playTone`/`Waveform` - a runtime square/triangle/sine/noise
+- `synthesizeTone`/`synthesizeSound`/`playTone`/`Waveform` - a runtime square/triangle/sine/noise/sawtooth
   waveform synth for a procedural tone or SFX, no sample library; `synthesizeSound` returns a
   pooled `Sound` over the tone.
 - `parseMidi`/`scheduleMidi`/`midiLoopStart`/`noteToFrequency`/`MidiPlayer` - a small `.mid` file player
@@ -964,12 +1002,72 @@ reach the compiled asset map without it.
   the page (FluidR3's piano, guitar and drums: 2.7 MB, against 20 MB decoded to a SoundFont 2),
   and `loadSoundFont` decodes it at load, so prefer it over a SoundFont 2 for anything but the
   smallest banks.
+- `createAudioLoader`/`AudioLoaderOptions` - a cached loader for embedded audio and MIDI,
+  shared by all `AudioBus` lifetimes. MIDI is detected by header and rendered on a worker;
+  other files use `decodeAudioData`. Options select SoundFont/render settings or a byte source.
+  `AudioBus` uses this loader by default, so `playBgm` and `playSe` accept asset paths with
+  the same volume, pitch and pan fields. BGM/BGS loop; ME/SE play once.
+- `MusicPlayer`/`MusicPlayerOptions`/`MusicPlayOptions` - one loaded `AudioBuffer` or
+  `RenderedMidi`, with play, pause, resume, seek, position, volume and an `onEnded` signal.
+  Call `update()` each frame to dispatch track completion and choose the next track.
+  `toAudioBuffer(context, rendered)` copies rendered stereo samples into an `AudioBuffer`.
 - `Channel`/`AudioBus` - buffered WebAudio music: a `Channel` plays one looping track with
   volume, pitch, pan, a loop region and a seekable playhead, and an `AudioBus` wires two of
   them into independent BGM/BGS loops, ME jingles that suspend and resume the BGM,
   overlapping SE one-shots, save and replay with playheads, and plain-data snapshots.
   `AudioBus.setMixer(kind, { volume, muted })` scales a whole kind on top of each track's
   own volume, without changing what snapshots report.
+- `MidiSynth`/`MidiSynthFactory`/`MidiSynthRequest` + `registerMidiSynth`, `unregisterMidiSynth`,
+  `midiSynthNames`, `resolveMidiSynth`, `renderMidiThroughSynth`, `renderMidiStems`,
+  `onMidiSynthFallback` and `INTERNAL_MIDI_ENGINES` - the named-engine contract for MIDI:
+  a package registers a synth under a name (`retro:mt32`), content asks for it by name, and
+  resolution walks the request, then the internal names (`gm-soundfont`, `builtin`), firing
+  `onMidiSynthFallback` whenever another engine voices the file instead. `timedMidiMessages`
+  is the raw timed message stream a synth is driven by.
+- `StreamPlayable`/`StreamChannel` - the streaming half of the `Playable` contract: seek and
+  `currentTime` on a synthesised stream, `playbackRate` by resampling, and a playhead counted
+  in frames, so endless formats (NSF, SID) play without a whole-track render.
+- `TrackCache`/`createBudgetedLoader`/`BusBudgetPolicy` + `bufferBytes` - bus render budgets:
+  an LRU cache of decoded tracks under a megabyte and entry cap, with `maxSeconds`, mono or
+  half-rate rendering for ambience through `fitToBudget` and `resampleStereo`.
+- `DEFAULT_DECODER_LIMITS`/`decoderLimits`/`DecodeBudgetError`/`InstructionBudget` +
+  `assertInputSize`, `guardBlockSource` and `inflateBounded` - the decoder guards for
+  untrusted retro formats: input and inflate ceilings, an instruction budget per second of
+  sound, and one named error per breach instead of a hang.
+- `SfxBank`/`SfxSound`/`SfxArbiter` + `sfxSeed` - data sound effects: synthesised chip
+  effects with a deterministic seed, arbitrated against the `se` bus by priority, firing
+  captions like a file effect.
+- `AudioSettings`/`AudioSettingsData`/`AudioRegion`/`OutputStage` + `regionPlaybackRate`,
+  `softenCutoff` and `dynamicsLimit` - the player-facing audio settings in one plain-data
+  object: volume per bus (applied to an `AudioBus` by `applyToBus`), the preferred MIDI
+  engine name, PAL or NTSC region (a tune authored for one runs slower or faster on the
+  other, `regionPlaybackRate`), a faithful or clean output stage, caption display, a
+  dynamics control (a soft limiter, `dynamicsLimit`) and bright-sound softening (a falling
+  low-pass cutoff, `softenCutoff`). A CPU and underrun indicator reads `AudioCoreHost`'s
+  stats and `onAudioUnderrun`.
+- `waveformEnvelope`/`channelEnvelopes`/`WaveformBucket` and
+  `trackerPattern`/`trackerNoteName`/`TrackerRow` - the data cores of the audio views: a
+  waveform as per-bucket min/max pairs per channel (what an oscilloscope draws), and a
+  MIDI file as tracker rows, one column per channel on the file's own tick grid. A game
+  draws them with its own widgets; the reduction and the grid live here and are tested as
+  arithmetic.
+- `SyxBank`/`SyxPatch` + `splitSysex` and `dx7PatchNames` - a `.syx` bank a player drops:
+  its whole sysex messages, the patch names of every checksummed DX7 32-voice bulk dump in
+  it (another maker's bank names nothing rather than guessing), and an `audition` that
+  loads a patch into a `MidiSynth` and renders one note through it for a settings screen.
+- `connectWebMidi`/`requestWebMidiInput`/`WebMidiConnection` - live Web MIDI into a
+  `MidiSynth`: every input port of a `MIDIAccess` is wired to the synth (channel messages
+  to `event`, sysex to `sysex`, transport dropped), and `requestWebMidiInput` is the
+  browser entry that returns null where Web MIDI does not exist or was refused.
+- `AdaptiveMusic` - adaptive tracks: mute and unmute stems of a running track with a fade,
+  and switch between two versions at the same frame position; `loopRegionFromFile` reads
+  the loop region a file declares as the default.
+- `AudioCoreHost` + `onAudioUnderrun` - the off-main-thread audio host: a synthesis core in
+  a worker behind the same `Playable` facade, with a main-thread fallback and an underrun
+  signal feeding bounded telemetry.
+- `encodeWav`/`decodeWav`/`wavInfo` and `spectralDistance` - WAVE as plain bytes (the
+  `mwg-audio` tool's convert and compare verbs over the same code), and a spectral distance
+  between two renders for a listening check that can be automated.
 - `parseVorbisLoopTags`/`loopRegionFromTags` - read the `LOOPSTART`/`LOOPLENGTH` comments an
   Ogg Vorbis file carries (a bounded walk of the first pages, null on anything malformed) and
   turn them into the seconds-based `LoopRegion` a `Channel` or the bus loader hands back.
@@ -1528,9 +1626,17 @@ nothing here reaches a shipped game unless a test imports it.
 - `memoryStorage` - a `SaveStorage` held in memory, for `SaveSystem`, `Settings`, `Collection`,
   `PlayerStats` and the other stored values; the same class `core` falls back to where
   `localStorage` is missing.
+- `exposeForTests(name, object)` - publishes inspectable game state under
+  `window.__mwg_test__[name]` for browser tests; does nothing outside a browser.
 - `fakeAudio`/`fakeAudioWithEnded`/`FakePlayable` - a `Playable` for `Sound`/`Music`'s `create`
   that counts its plays; the second also has the `onended` slot a backend reporting track ends
   has.
+- `FakeAudioContext`/`FakeBuffer`/`FakeBufferSource`/`FakeGain`/`FakeBlockSource` - a fake
+  WebAudio graph for the audio tests: sources, gains and buffers a test can inspect, and a
+  block source for a `StreamChannel`, with no real `AudioContext` anywhere.
+- `FakeRetroPlayer` - a `MidiSynth` double for a retro engine: it records every message it
+  was driven with and renders a flat level while a note is on, so a renderer test reads what
+  was sent and what sounded, with `FakeAudioContext.advance()` as the clock it moves by hand.
 - `FakeSocket` - a `WebSocketLike` for `LockstepClient`'s `create`: `sent`, `receive(message)`,
   `receiveRaw(text)`, `close()`.
 - `fakeFetch`/`FakeFetchCall` - a `fetch` for every `HttpTransport` client, answering with a
@@ -1549,6 +1655,10 @@ a module worker loaded from `file://` fails CORS whatever the policy says), and
 spawns a worker pays nothing for it, and imports `@datamoc/mw_games/threads` when it
 wants one.
 
+- `openWorker(source, events)` - opens a long-lived worker from a self-contained script
+  (blob worker in a browser, `node:worker_threads` in Node, null where neither exists) and
+  returns its message link; `spawn` is the one-task use of it, a service such as the audio
+  core host keeps its worker and talks to it.
 - `spawn(fn, args?, options?)` - runs `fn` on a worker and resolves with its value. The
   task is serialized with `Function.prototype.toString`, so it must be self-contained:
   no closures over module scope, no imports, no bound or native functions - everything it
@@ -1747,6 +1857,11 @@ consumes generated data and does not parse `.mwl` source files in the browser.
   `id=rebels` validates) keys `world.sides` and `world.gold`, marks a map keep (`rebels Kh`), and
   is what `unit.side`, `MwlMessage.side` and every `side`/`side_filter` filter hold. `MwlSideRef`
   is just that id.
+- `nodesToObjects`/`MwlObject` - converts compiled nodes to JSON objects using the tag
+  schema: declared numbers and booleans become typed fields, child tags become ordered
+  arrays, and a `cardinality.max` of 1 selects a single object. Missing optional fields stay
+  absent. Check the returned diagnostics for conversion errors and field collisions.
+  Attributes not listed in `MwlTagSchema.required` are optional; use `number`, not `number?`.
 - `readAttributes` / `readChildren` - shared typed readers for compiled nodes. They coerce
   scalars and lists and return source-located diagnostics instead of silently guessing.
 - `MwlNode.attributeLocations` / `valueLocations` - parsed JSON5 nodes retain the exact key and
@@ -1769,6 +1884,9 @@ consumes generated data and does not parse `.mwl` source files in the browser.
   absent cell omits the key), and `emitTableTypes` emits one named row interface plus one
   typed accessor per table for a game's build script to write and import, so a changed
   column type or a removed column fails type-checking at every use.
+  `emitTableTypes(tables, { literalColumns: ['id', 'sprite'] })` also exports sorted,
+  deduplicated readonly value lists and literal unions such as `VehiclesSprite` from the
+  current string-column values. Regenerate them with the catalog to catch stale game ids.
 - `MwlValidationOptions.tableReferences`/`MwlTableReference` (item 362) - declarative
   cross-table checks, so no game hand-rolls one validator per table: a column declares
   `references: { table, column }` or `oneOf: [...]`, and `validateCatalog` checks every cell
@@ -1809,6 +1927,16 @@ consumes generated data and does not parse `.mwl` source files in the browser.
   `emitHooksDeclaration`, `emitModule`, `emitTableTypes`, `encodeSave`, `evaluateExpression`,
   `execute`,
   `extractCatalog`, `hookTypes`, `inventoryItem`, `isGettext`, `isMwlId`, `itemDefinition`,
+  `PACKAGE_TAGS`, `PACKAGE_ASSET_KINDS`, `PACKAGE_MEDIA_KINDS`, `PACKAGE_SCRIPT_ACTIONS`,
+  `KNOWN_PACKAGE_CAPABILITIES`, `DEFAULT_PACKAGE_LIMITS`, `PackageError`, `PackageFormatError`,
+  `PackageIntegrityError`, `PackageLimitError`, `PackagePathError`, `PackageConflictError`,
+  `encodePackage`, `decodePackage`, `verifyPackage`, `loadPackage`, `mergePackage`,
+  `compilePackages`, `packageContent`, `packageRef`, `parsePackageRef`, `parsePackageDocument`,
+  `checkPackagePath`, `checkPackagePolicy`, `checkConditionSyntax`, `compareVersions`,
+  `satisfiesVersionRange`, `requestedCapabilities`, `detectRomImage`, `registerRomDigest`,
+  `generateCredits` and `sha256Hex` (self-contained `.mwp` content packages: one compressed
+  container with per-entry digests and declared limits, a capability policy the game accepts
+  or refuses, `id@version` namespaces in saves, and a ROM-image refusal with generated credits),
   `parseExpression`, `parseHookReference`, `parseMapFile`, `parseTerrain`, `parseValue`, `preprocess`,
   `schema01`, `typedRows`, `validateCatalogNodes`, `validateHookReferences`, `loadContent`, and `validateWorld`.
 - `parseMapFile`/`MwlMapFile` (item 284) - reads a Wesnoth-shaped `.map`: the `key=value` header