@datamoc/mw_games 0.42.0 → 0.43.0

package/CHANGELOG.md

@@ -7,6 +7,65 @@ the public API may still change between minor versions.
 
 ## [Unreleased]
 
+## [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,63 @@ 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.
+
 ## Capability spec
 
 The definition of done for 1.0, drawn from what each of the nine references actually

package/REFERENCE.md

@@ -530,6 +530,12 @@ 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` + `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, 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 +669,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,7 +703,11 @@ 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; `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.
 - `TextModel`/`TextModelOptions` - the editing state behind a text field, fed by `core.Input`'s
@@ -727,8 +739,19 @@ 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`. `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`.
+- `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 +797,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 +922,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,6 +997,15 @@ 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,
@@ -1528,6 +1570,8 @@ 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.
@@ -1747,6 +1791,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 +1818,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