@datamoc/mw_games 0.25.0 → 0.27.0

package/CHANGELOG.md

@@ -7,6 +7,198 @@ the public API may still change between minor versions.
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-10-07
+
+Two strands in one release. A run is durable and drives the AI (roadmap 396-397): the
+versioned replay envelope refuses another game or framework build by name, `LastRun` keeps
+the newest recording, `runCheckpoint`/`resumeRunPlayer` restore a run mid-run, and the
+`file://` plumbing (download, picker, Blob read) ships with it; `imitationFromReplay` turns
+a recorded run into training samples against its own seeded environment, `runSeededEpisode`
+plays a whole run from a named seed behind any deterministic chooser, and `ai.Suggester`
+is the throttled, non-mutating hint source. The render and UI strand: `Flights` owns live
+projectile flights, `Beam`/`Beams` draw one-shot beams, `TextPrompt` asks for one line with
+IME and screen-reader support, `MessageLog.lastEntries` reads retained entries back, and
+`ParticleEmitter.attach` follows a target; `core.FloatSource` narrows the injectable random
+stream for float-only helpers.
+
+### Added
+
+- `core.FloatSource` splits `core.RandomSource`: helpers that draw floats only
+  (`float`, `chance`, `weighted`, `weightedKey`) accept the narrower
+  `{ float(): number }`, so a float-only stream needs no dead `int`. The
+  integer helpers (`int`, `range`, `normalRange`, `element`, `shuffle`) keep
+  requiring the full source; `element` stays wide deliberately, because it
+  draws through `int()` and re-spelling that draw would change its stream.
+
+- `MessageLog.lastEntries(n)` reads the newest retained entries back as plain
+  `{ text, level }` records, oldest first, without scraping rendered children:
+  entries the wrapped-line budget already dropped are gone, over-count reads
+  everything retained, and zero or negative reads nothing. The slice lives in
+  the pure `takeLastEntries` beside the existing `linesToDrop` budget, so the
+  readback contract is testable without a renderer.
+
+- `ParticleEmitter.attach(target)` follows a display object or position thunk on
+  every update tick and every `burst()`, with `offsetX`/`offsetY`, an `enabled`
+  callback gating tick emission, and auto-detach for destroyed targets;
+  `detach()` keeps the last position. The follow math is tested headless through
+  textureless emitters.
+
+- `Flights` owns a scene's live projectile flights over the existing `Projectile`:
+  `add(sprite | texture, from, to, { speed, tint?, spin?, fadeIn?, onArrive? })`
+  returns a handle, `update(dt)` drives positions with per-flight spin and fade,
+  each arrival dispatches once after leaving the list, and `cancel()`/`clear()`
+  forget without dispatching. Caller sprites stay caller-owned; texture-built
+  sprites are parented here and destroyed with their flight.
+
+- `Beam`/`Beams` draw one-shot beams between two screen points: a fading line by
+  default, a fading repeating texture strip with `texture`, additive blend unless
+  opted out, `retarget` for tracking endpoints, and `update` reporting expiry
+  exactly once so the `Beams` group can remove finished beams itself.
+
+- `TextPrompt` asks for one line of text over a `TextModel`: typing through
+  `onText` (the newest open prompt wins), caret and edits through
+  `left`/`right`/`backspace`/`delete` actions, `confirm` gated by `validate` and
+  `cancel` giving up. IME compositions preview until they commit, and the
+  message plus validation errors announce through `screenReader` (assertive for
+  the errors), with an injectable announcer for tests.
+
+- A run is durable now (roadmap 396): `exportReplayFile`/`importReplayFile` wrap a
+  recording in a versioned, self-describing envelope that refuses another game or
+  framework build by name, `LastRun` keeps the newest recording (one deep, bounded,
+  over the same storage a save slot uses), and `runCheckpoint`/`resumeRunPlayer`
+  pair the partial recording with the saved state so a restored run resumes mid-run
+  instead of restarting - `Recorder` and `Player` both take `fromFrame`, and
+  `parseReplayEvents` factors out the half of `deserializeReplay`'s check that
+  validates an already-parsed array. The `file://` plumbing rides along:
+  `downloadReplayFile` (a Blob download, never `fetch()`), `pickReplayFile`
+  (the file picker, null on cancel) and `readReplayFile` (any `Blob`, headless
+  Node included).
+
+- Replays train and drive the AI (roadmap 397): `imitationFromReplay` walks a
+  recorded run against the same seeded `TrainingEnvironment` it was played on and
+  returns the `(observation, action)` samples a game's own trainer fits;
+  `runSeededEpisode` plays a whole run with any deterministic chooser (a heuristic,
+  a `NeuralPolicy`'s argmax, not just a `NeuralModel` like `runRollouts`) from a
+  named seed, recording every chosen action so runs compare across builds and
+  policies; and `ai.Suggester` is the in-game suggestion mode, the same decision
+  call pointed at a hint UI instead of the world, throttled by a frame-count budget
+  and never mutating state to compute a hint.
+
+## [0.26.1] - 2026-10-07
+
+The 0.26.0 follow-up: its Chrome end-to-end test failed on every CI run, so the
+`tools/browser-driver` Chrome engine never actually worked on a CI machine (a cold
+Windows runner never reached the debugging endpoint in the old budget; an Ubuntu
+runner crashed in Chrome's sandbox). Chrome now launches against its own profile,
+the endpoint is watched on both output streams with a cold-start budget and a
+diagnostic that names what the browser printed, `close` releases the profile and
+the stdio pipes only after the child exits, and the CI workflows pass
+`--no-sandbox` on Linux through the driver's own `MWG_DRIVER_CHROME_ARGS` channel.
+0.26.0 was tagged before this was known and its npm publish never ran.
+
+### Fixed
+
+- `tools/browser-driver`'s Chrome engine launches against its own profile
+  (`options.profileDir`, or a temp dir the driver creates and removes on `close`)
+  instead of the machine's default one, watches both stdout and stderr for the
+  debugging endpoint (which stream a build prints it on is not something to bet
+  on), waits up to 30 s instead of 15 (a cold CI machine's first Chrome start can
+  outrun the old budget), and names what the browser printed when the endpoint
+  never arrives. This is the fix for the Chrome end-to-end test failing on every
+  CI run since the driver landed: the default profile on a fresh runner never
+  reached the endpoint in time. `close` now also destroys the child's stdio
+  pipes (surviving browser helper processes could hold a suite open past the
+  browser's own death) and releases the profile only after the child exits.
+  The failing configuration is now diagnosed, not just reported: the timeout
+  names what the browser printed. CI's Linux jobs pass `--no-sandbox` through
+  the driver's `MWG_DRIVER_CHROME_ARGS` channel, since an Ubuntu 23.10+ runner
+  that disables unprivileged user namespaces is a property of that machine,
+  not of the tool.
+
+## [0.26.0] - 2026-10-07
+
+The machine-readable surface and the audit tooling around it: `api-surface.json` ships as the
+`./api-manifest` subpath (one `{ name, kind, subpath, declaringModule }` row per export), the
+blessed `mwg/headless` entry imports every renderer-free module in one line, `tools/audit-adoptions`
+checks a consumer's imports and local definitions against that manifest, and the dependency-free
+`tools/browser-driver` harness drives real Chrome and Firefox. `core` gained injectable `RandomSource`
+streams for every derived helper and the shared square-grid rulers (`chebyshev`, `manhattan`,
+`euclidean`, `distance` by `DistanceMetric`), the coverage gate now enforces `two-d/ui` instead of
+excluding the whole tree, and the bundle-size baseline is refreshed for the growth those brought.
+
+### Added
+
+- Exported the types a public signature already names: `mwl` move/evolution/matchup
+  definitions, `core` achievement criteria and hex shape types, particle curve and spawn
+  area types, screen effect steps, `rpg` route targets, asset loader options, and the
+  `core.HttpTransport` base class its four clients already extend.
+
+- `core.NEIGHBOURS4`/`NEIGHBOURS8`/`CIRCLE8` share one frozen square-grid offset table
+  instead of each module keeping its own: axial, row-major eight, and the clockwise ring
+  (`roguelike`'s `neighbourOffsets` returns these now); `core.euclidean` is the
+  straight-line ruler beside `roguelike`'s `chebyshevDistance`.
+
+- `core.chebyshev` is the king-move ruler beside `euclidean` (a diagonal costs one
+  step) and `core.manhattan` the orthogonal-step count; `core.distance` measures with
+  the ruler a `DistanceMetric` names, so a data-authored rule picks its geometry by
+  name. `roguelike`'s `chebyshevDistance` delegates to `chebyshev` instead of spelling
+  the arithmetic out again.
+
+- `api-surface.json` is the machine-readable API surface: one
+  `{ name, kind, subpath, declaringModule }` entry per export per subpath,
+  generated by the same `tools/api-report.mjs` pass that maintains
+  `API_REPORT.md`, shipped in the package behind the `./api-manifest` subpath,
+  and pinned by `tests/api-manifest.test.ts` (shape and coverage) plus the
+  existing `--check` (agreement with the declarations). `node
+  tools/api-report.mjs --diff OLD NEW` diffs two releases' surfaces, and the
+  report parser no longer drops `export type { ... }` re-export lists.
+
+- `core.RandomSource` lets every derived helper (`chance`, `element`,
+  `weighted`, `weightedKey`, `shuffle`, `int`, `range`, `normalRange`) draw
+  from an injected stream: pass a rule-local `Generator` (or any
+  `float`/`int` pair) as the trailing `source` and the ambient stream is left
+  untouched, with identical draws and the same `null` reporting.
+
+- `node tools/api-report.mjs --diff OLD NEW` lists added, removed and
+  kind-changed exports between two `api-surface.json` manifests, so a version
+  bump yields a one-command surface diff.
+
+- `mwg/headless` is the blessed renderer-free entry: `core`, `simulation`,
+  `mwl`, `i18n`, `actors`, `world`, `battle`, `roguelike`, `board`, `audio`,
+  `rpg`, `ai`, `testing` and the two renderer-free asset halves, in one import
+  with no DOM or WebGL globals. `tests/headless-smoke.test.ts` imports it in
+  plain Node, walks the reachable graph for a renderer leak, and replays a
+  seeded scenario through it.
+
+- `tools/audit-adoptions` (also `mwg-audit-adoptions`) is the shipped consumer
+  adoption auditor: manifest plus reasons file plus config (type-only
+  directories, subpath deny-lists, per-pattern import budgets), reporting
+  unadopted exports, stale reasons, shadowing collisions and config violations
+  with `file:line` and a non-zero exit.
+
+- `two-d/pixi-interop` now states the interop-only rationale on each
+  re-exported primitive's own declaration: every histogram symbol
+  (`Rectangle`, `Texture`, `Container`, `Sprite`, `Graphics`, `FillGradient`,
+  `TilingSprite`) already has a facade family, so the note names the
+  Pixi-typed seam that keeps the raw export, and `tests/pixi-interop-coverage`
+  pins both halves.
+
+- `tools/browser-driver` is the dependency-free browser harness: a self-served
+  static directory on an OS-chosen free port, Chrome over CDP and Firefox over
+  WebDriver BiDi behind one surface (`goto`/`waitReady`/`tap` at canvas
+  fractions/`evaluate`/`script`/`screenshot`/`consoleErrors`/`close`), reusing
+  the `browser-smoke` readiness contract. Verified live on both engines.
+
+### Changed
+
+- The coverage gate now enforces `two-d/ui` instead of excluding the whole tree:
+  the widget tests the suite already ran carry it (97.3/92.6/94.3 against the
+  88/89/82 floors), so the exclusion was stale, and a wildcard also left every
+  new UI file silently ungated. `EventDialogue` stays excluded as intended, under
+  its real path (`two-d/ui`, where the old flag pointed at a nonexistent
+  `two-d/stage` copy), and `SelectionModel` gained a direct contract test that
+  covers it fully, where before only its embedding widgets exercised it.
+
 ## [0.25.0] - 2026-10-05
 
 Framework support for the Pixel Dungeon port's simulation and content proposals: numeric

package/README.md

@@ -336,6 +336,21 @@ edited in a proper editor, without any of those options requiring changes to the
 It also keeps the content out of the bundle: `tools/compile-resources` treats a map file
 exactly like a sprite sheet, so adding a hundred maps does not touch the build at all.
 
+### Objects for behavior, data for content
+
+Content is data (above), but a game's *behavior* belongs in classes. A monster kept as
+loose scene fields works for one tutorial room and collapses for a dungeon: give it a
+class holding its state and the methods that change it, built on the framework's own
+bricks (`core.Scene` scenes, `actors.StatBlock` stats, `battle.Creature` opponents,
+`roguelike.Level` maps, `rpg.GridMover` movement, `core.EntityRegistry` identity).
+Subclass the brick that already owns the concern instead of reimplementing it beside an
+interface; no new base class is needed for ordinary actors.
+
+The boundary is where serialization starts. `simulation` commands survive
+`structuredClone`, `core.SaveSystem` stores JSON-serialisable state, and MWL rows are
+records by design, so classes stop where those begin: flatten at the boundary the way
+`rpg.GameState` does, and rebuild objects on load rather than storing them.
+
 ### On writing direction
 
 Supporting more than one language is mostly bookkeeping. Supporting more than one writing