@datamoc/mw_games 0.40.0 → 0.41.0

package/REFERENCE.md

@@ -0,0 +1,2115 @@
+# mwg reference
+
+A one-line-per-export index of `@datamoc/mw_games`'s public API - what exists and where,
+not how to use it. The published Documentation page is this file rendered as HTML; the
+full generated API (every parameter, every doc comment) lives beside it at
+`webpage/documentation/api/` (both from `npm run webpage:docs`). For *why* the framework
+is shaped this way and what it's for, see `README.md`'s capability spec. For architecture
+and build commands, see `DEVELOPMENT.md`. For the order things shipped in and the reasoning
+behind it, see `CLOSED.md`; for what's still open, see `ROADMAP.md`.
+
+Every module is its own barrel: `import { X } from '@datamoc/mw_games/core'` (or the
+matching subpath for any module below), or `import { X } from '@datamoc/mw_games'` for the
+root re-export.
+
+**Two rendering worlds, and a core that belongs to neither.** `mwg/two-d` is everything drawn
+through PixiJS (`Game`, `Scene2D`, and the `render`, `ui` and `stage` modules beneath it);
+`mwg/3d` is everything drawn through Babylon. `mwg/core` holds what both need and neither
+renders: the scene lifecycle, `SceneStack`, input, saves, RNG, signals, achievements.
+
+**Which entry points reach a renderer**, checked by a test that walks the real import graph
+(`tests/renderer-isolation.test.ts`) rather than by good intentions:
+
+| renderer-free | Pixi | Babylon |
+| --- | --- | --- |
+| `core`, `i18n`, `actors`, `world`, `battle`, `simulation`, `roguelike`, `board`, `audio`, `rpg`, `ai`, `mwl`, `assets/paths` | `two-d` (and `two-d/render`, `two-d/ui`, `two-d/stage`), `assets` | `three-d` (the `3d` subpath) |
+
+`roguelike` adds only `rot-js`, and `pixi.js`, `@babylonjs/core`/`@babylonjs/loaders` and
+`@capacitor/core` are optional peer dependencies rather than installed ones, so a project names
+only the renderer it actually draws with. A Babylon game importing `core` + `3d` pulls in no Pixi
+at all, and a 2D game importing `core` + `two-d` pulls in no Babylon. `rpg` is renderer-free too:
+its event interpreter takes an injected `DialoguePresenter` rather than building a widget, so
+a 3D game can run map events, dialogue and quests without a 2D renderer anywhere in reach.
+
+## MWL presentation
+
+The optional compiler at `@datamoc/mw_games/mwl/presentation` is renderer-free. The
+runtime at `@datamoc/mw_games/two-d/presentation` imports Pixi and is kept off the root
+barrel. The browser consumes compiled data, with no MWL parser or network requests.
+
+- `compilePresentation(files, manifest)` validates and compiles top-level
+  `theme_definition`, `presentation_context`, `component_variant`, `ui_component` and
+  `scene_definition` nodes. It checks named actions/adapters, binding types, assets,
+  reusable-component cycles, duplicate IDs, overrides and token references at build time,
+  with source-file/line diagnostics. The manifest's asset names must be generated files
+  that the game's asset build actually includes.
+- `emitPresentationModule(data)` emits deterministic TypeScript data, `PresentationId`
+  (including keyed instance paths) and `PresentationSceneId` literal types. A game's build
+  script writes this module plus `data.messages` and `data.assets` into its existing MWL
+  artifact pipeline. See `examples/mwl-presentation/generate.mjs`.
+- `MwlPresentation(data, sceneId, options)` mounts existing `Button`, `Label`, `Bar`,
+  `Window`, `WindowStack` and `Camera` components. `get(id)`, `focusId`, `palette` and
+  `activeContext` expose instances and presentation state. `update(dt)`, `resize(width,
+  height)`, `setContext(id)` and `destroy()` drive its lifecycle; `handleAction(action)`
+  offers modal windows input first. Register destruction with the owning scene's
+  `onDestroy`; it detaches input, theme, controller and adapter subscriptions.
+
+Declare the TypeScript manifest with `values: { name: 'string' | 'number' | 'boolean' }`,
+or `{ type: 'items', fields: { id: 'string', text: 'string', selected: 'boolean' } }` for
+collections, plus `actions`, optional `adapters` and `assets` name lists. The runtime's
+`options.state()` supplies those values; `options.actions` implements the named callbacks.
+Repeated-item actions receive the current item, even after reorder. Optional `subscribe`
+returns a disposer, and `translate` resolves authored/gettext text. Asset textures must
+be loaded before mounting. `PresentationAdapter` exposes a view plus optional `update`,
+`resize`, `restyle` and `destroy`: the runtime destroys the view, while the adapter
+detaches its own subscriptions. Cleanup continues even if an adapter throws.
+
+Scenes contain `scene_camera` (zoom, position or fit dimensions), `scene_layer` (world or
+screen space, optional generated image or named procedural adapter) and UI trees.
+`ui_mount` expands a reusable component at build time. UI trees use `ui_container`,
+`ui_row` (wrapping by default), `ui_column`, `ui_grid` (equal grow columns), `ui_label`,
+`ui_button`, `ui_bar`, `ui_window`, `ui_repeat` and `ui_adapter`. Every node has an `id`;
+runtime paths start with the scene ID and join descendant IDs with `/`. Repeats insert
+the URI-encoded stable key before their single template child's ID, preserving instances
+and focus on updates. A reusable component using item fields may declare `items_binding`
+so even an unused template can be validated against its collection.
+
+Properties include pixel dimensions, anchors, offsets (`x`, `y`), spacing, alpha and
+semantic color tokens. Bindings use `text_binding`, `title_binding`, `value_binding`,
+`max_binding`, `color_binding`, `visible_binding`, `selected_binding` and
+`disabled_binding`; item fields use `item.field`. Buttons name an `action`, windows may
+name a `close_action`, and repeats declare `items_binding` plus a string/number `key`.
+Window close actions should update the controller's visibility binding. Closed windows
+stay closed until their visibility transitions false then true; reopening creates a
+fresh window, because existing `Window.close()` destroys its contents.
+
+Themes require `panel`, `text`, `accent`, `success`, `warning`, `danger` and `selection`
+24-bit color tokens; games may add scenery tokens and choose font/padding metrics.
+Text/panel contrast must reach 4.5, and danger/selection against panel must reach 3.
+Contexts choose a theme and may override tokens or authored-node properties using
+`ui_override.target`, such as `component:controls/toolbar` or `scene:bridge/decor`.
+Image overrides on scene layers select generated scenery. Precedence is base properties,
+context overrides, component variant, then `ui_state` (`idle`, `hover`, `pressed`,
+`disabled`, `selected`, `focused`). A game's biome schema selects a context; MWG defines
+no biome rules. Context switches preserve mounted adapters and controller state.
+
+One active presentation owns the existing global UI theme. Destruction restores its prior
+theme if nobody replaced it meanwhile. Existing widgets also expose local palette updates:
+`Button.setColors` (`ButtonColors`), `Window.setColors` (`WindowColors`) and
+`Bar.setBackground`, for variants that must follow token changes without remounting.
+
+## Conventions
+
+Three rules the whole API follows, so a name means one thing everywhere:
+
+- **`advance(turns)` moves a clock forward in whole turns or rounds; `update(dt)` moves one
+  forward in real seconds.** `TurnClock`, `Charges`, `Field`, `Barrier` and `AbilityCycle`
+  take turns; everything in `render`, `ui`, `audio` and `world.EnvironmentClock` takes `dt`.
+  Anything that is not time passing gets its own verb rather than borrowing one of these
+  (`QuestLog.advanceStage`, `BossPhases.check`).
+- **`toJSON()` / `static fromJSON(defs, data)` is how a class saves and reloads.** Definitions
+  a game owns (item tables, quest definitions, growth curves, terrain kinds) are supplied
+  fresh as `defs` rather than written into the save, so rebalancing reaches old saves.
+  Namespace-level state uses `exportX`/`importX` free functions instead (`Input` bindings);
+  `Random.Generator` keeps `getState`/`setState`, which resumes a live stream in place rather
+  than producing a payload.
+- **"Nothing to pick" is always `null`**, never `-1` or `undefined`: `Random.weighted`,
+  `Random.element`, `Random.weightedKey`, `rollEncounter`, `rollLoot`, `rollAffix`,
+  `pickBuilder`.
+
+## Contents
+
+[core](#core) · [two-d](#two-d) · [render](#two-drender) · [ui](#two-dui) · [stage](#two-dstage) ·
+[assets](#assets) · [audio](#audio) · [battle](#battle) · [board](#board) ·
+[actors](#actors) · [roguelike](#roguelike) · [rpg](#rpg) · [simulation](#simulation) ·
+[three-d](#three-d-optional) · [world](#world) · [i18n](#i18n) · [mwl](#mwl) · [mwl/pyroeis](#mwlpyroeis) ·
+[skeleton](#skeleton) · [physics](#physics) · [ai](#ai) ·
+[testing](#testing) · [threads](#threads) · [headless](#headless)
+
+## `core`
+
+The scene lifecycle, signals, RNG, input, and every save/telemetry/replay primitive - the one
+module every game imports, whichever renderer it uses, and the only one that depends on no
+other `mwg` module and no renderer at all.
+
+- `Scene` - one screen of the game, as lifecycle only: `create`, `update(dt)`, `resize`, the
+  `onSuspend`/`onResume` pair a pushed scene needs, and a `destroy` that fires once. It owns
+  no display node; `two-d.Scene2D` adds the Pixi container, and a Babylon game supplies its own.
+- `SceneStack` - `push`/`pop`/`replace`: suspends the current scene, layers another over or
+  instead of it, and resumes with a result once it pops (minigames, pause menus). Generic over
+  the scene type and typed against the lifecycle above, so it drives a 3D game just as well.
+- `SceneComponentHost`/`SceneComponent` - composes a scene out of named sections (map logic,
+  encounter logic, UI wiring), each its own module implementing whichever `Scene` lifecycle
+  hooks it needs, instead of one scene class accreting every responsibility. A scene owns one
+  host and forwards `update`/`resize`/`onSuspend`/`onResume`/`destroy` to it - composition, not
+  a base class, so it works the same whether the scene extends `Scene` or `two-d.Scene2D`.
+- `Registry` - a named lookup registered once and read back by name: `register`/`get`/`has`/
+  `list`, throwing on a duplicate or missing name by that name. The dispatch primitive
+  underneath a catalog of factories or handlers (`SceneComponentHost` uses one internally) -
+  a game still imports and registers each entry itself, no auto-discovery.
+- `createHandles`/`Handles` - numeric leases for values a plain-data command cannot carry
+  (callbacks, RNG streams, query closures): `put` stores a value and returns its id, `get`
+  resolves it, `drop`/`clear` end leases, and `with` scopes a lease so the drop runs even
+  when the body throws. Ids start at 1 and are never reused.
+- `Logger` - categories, four severity levels, a filter, and a sink tests can capture,
+  instead of bare `console.log`/`console.error`.
+Three shapes cover what "an event" means here, kept deliberately distinct rather than folded
+into one bus: a **GameEvent** is a rule's ordered *output* - what happened, described after the
+fact - realised as the generic `Event` type parameter `simulation`'s `SimulationRule`/
+`SimulationRuntimeRule` already return, never something a handler reacts to mid-calculation. A
+**Hook** (`HookRegistry`, below) is a point of *modification* a rule consults while it runs -
+`modifyDamage`, "can this creature act this turn" - synchronous, and read back by the same rule
+that asked. A **Signal** is a plain *notification* with no bearing on any rule - `sceneChanged`,
+`saveCompleted`. Reaching for a global bus that several `AttackRequested`/`DamageCalculated`/
+`HpChanged`-style events all dispatch onto, each triggering the next, is the shape to avoid: it
+turns a rule's synchronous, readable logic into a chain no single function owns.
+
+- `Signal` - a typed event emitter: one event, one payload, LIFO listeners, and a listener
+  can consume it.
+- `HookRegistry`/`Hook` - many events keyed by name, dispatched in registration order, with a
+  `source` tag so everything one ability or worn item registered comes off in a single
+  `offSource` call. `battle.BattleHooks` and `roguelike.CombatHooks` are both this with their
+  argument types fixed; they were two copies of one class until they were merged.
+- `PresentationQueue` - plays a batch of simulation events one at a time, at whatever pace
+  `play(event)` (a tween, a sound, a floating number) says to wait before the next - the
+  presentation-side counterpart to a `SimulationRuntime.dispatch()`/`runScenario()` result, kept
+  out of the logical commit that already happened. The same queued/timed shape as `two-d.ui.
+  Toast`, generalised to any event type and needing no renderer.
+- `parseCSV`/`CsvOptions`/`CsvColumnType` - a header-row CSV into an array of typed row
+  objects, so a content designer edits a spreadsheet instead of a `.ts` object literal for a
+  table shaped like `actors.AffixTable`. `columns` names which fields coerce to
+  `'number'`/`'boolean'`/`'list'` (semicolon-separated)/`'map'` (semicolon-separated
+  `key=value` pairs); an empty cell omits that field entirely, the same as an optional
+  property never set. Takes a raw string with no opinion on how it was loaded, the same
+  boundary `i18n.parseFTL` already draws.
+- `clamp` - `value` restricted to `[min, max]`. Shared so `two-d.render.Camera`'s bounds
+  clamp and `rpg.Collision`'s tile-edge resolver stop being the same three-line function
+  written twice.
+- `parseDialogueLines`/`DialogueLine` - the terse `@id text`/`-`-alternation dialogue-text
+  parsing engine behind both `two-d/stage.parseDialogueText` and `rpg.parseDialogueText`, so
+  the two-speaker state machine lives once instead of twice: each module's own wrapper only
+  renames `DialogueLine.speaker` onto its own command shape (`StageCommand.as` versus
+  `EventCommand.speaker`).
+- `parseTwee`/`TweeCommand`/`TweeChoice`/`TweeStory` - the Twee-notation parsing engine
+  behind both `two-d/stage.importTwee` and `rpg.importTwee`, for the same reason: passages,
+  `[[links]]` and `StoryData`/`StoryTitle` parse once here, and `TweeCommand`/`TweeChoice`
+  are structurally compatible with both `StoryScript`/`StageChoice` and
+  `EventStoryScript`/`EventChoice`, so each module's wrapper needs no per-field conversion.
+- `Random` (namespace) - seeded RNG: `int`, `float`, `weighted`, `element`, `shuffle` and the
+  rest; every "pick one" returns `null` when there is nothing to pick.
+- `Generator` - the seeded RNG class `Random` wraps directly, for a game that wants its own instance.
+- `JavaRandom`/`JavaRandomDraw`/`JavaRandomOptions` - `java.util.Random`'s 48-bit generator bit for bit
+  (`nextInt`, `nextInt(bound)`, `nextLong`, `nextDouble`, `nextFloat`, `nextBoolean`), so a
+  game ported from the JVM replays the same seed; `onDraw` logs every underlying draw for a
+  parity diff against a JVM run. Not for general use, that is `Generator`.
+- `MersenneTwister`/`MersenneTwisterState` - MT19937 with `mt_rng`'s `seed`/`discard`/
+  `discardCount` bookkeeping, for a port that consumes the reference's raw 32-bit stream; the
+  engine matches the standard test vector, while the int mapping is MWG's own unbiased
+  reduction (C++'s `uniform_int_distribution` is implementation-defined).
+- `RandomStreams` - named, independent MT19937 streams over one base seed, so a loot draw and
+  an AI draw never shift each other, with `getState`/`setState` for a save and `reseed`.
+- `Input` (namespace, so `Input.onAction`, not a bare `onAction` import) - named-action input: `bind`/`isDown`/`justPressed`/`justReleased`
+  over keyboard, `bindButton`/`bindAxis`/`pollGamepads` over a gamepad,
+  `bindTouch`/`pressTouch`/`releaseTouch`/`attachSwipe` over touch, `attachPointer` for
+  down/move/drag/up signals with target-relative and (through `toWorld`) world positions, `actionsForKey` for
+  rebind-conflict detection, `rumble` for gamepad haptics. `onText` carries the character a
+  key press produces (via `textFromKey`/`dispatchText`) and `onAction` the named action a
+  key fires, each with its own programmatic counterpart (`dispatchText`,
+  `dispatchAction`) so an on-screen keyboard feeds the same signals a physical key
+  travels; `onComposition` follows an IME through `start`/`update`/`end`, so a free text
+  field can be built on top.
+- `PlayerInput` - a per-player scoped `Input`, for local multiplayer/split-screen.
+- `StoredValue`/`defaultStorage` - one JSON value under one storage key (`read(fallback)`/
+  `write`/`remove`) over the same storage `SaveSystem` uses: a game's structured progress or
+  best scores without a save slot.
+- `FixedStepper` - turns the variable `Scene.update(dt)` into fixed simulation steps
+  (`advance(dt, tick)`, a `maxSubsteps` cap, `alpha` for interpolated drawing): the deterministic,
+  refresh-rate-independent loop a physics solver or lockstep game needs.
+- `SaveSystem` - named, versioned save slots over `localStorage` (in-memory fallback under
+  `file://`); a `migrations` chain, and `importExternal` as a plug-in point for a foreign
+  save format's own `normalize` function. `load`, `list` and `importSlot` read every slot
+  through `parseInbound` plus a `{ meta: { version, savedAt }, state }` shape check: a
+  corrupt or tampered slot loads as `null` and is left out of `list`.
+- `StateRegistry`/`StateExtension`/`StateRestoreDiagnostic` - named game-owned state extensions with deep-cloned
+  snapshots and transaction rollback, with independent versions, ordered migrations and
+  explicit handling of extensions absent from a restored save, so custom save data has one
+  atomic boundary.
+- `ActionJournal` - serializable ordered action and outcome batches with checkpoints,
+  incremental reads, truncation and validated restore for replay, undo and synchronization.
+  Actions and events are copied on `append`, so both must be plain data.
+- `cloneData`/`uncloneablePath` - `structuredClone` with an error naming the first value that
+  cannot be copied (`action.target.reactions.rules[0].when`), and that path on its own. The
+  journal and `simulation.SimulationRuntime` use it, so a command carrying a live actor fails
+  with where and why instead of a bare `DataCloneError`.
+- `scramble`/`unscramble` - light save-data obfuscation, not encryption.
+- `SaveSyncClient` - pushes/pulls save data to a server the game supplies.
+- `LockstepClient` - deterministic multiplayer over an injectable WebSocket, tick-driven.
+  Server messages are size-capped (`maxMessageBytes`, 1 MB) and type-checked; a malformed one
+  is dropped and reported on `onProtocolError` instead of throwing out of `onmessage`.
+- `stateChecksum`/`SyncGuard` - out-of-sync detection for lockstep: a key-order-stable 32-bit
+  checksum of JSON state, and a guard comparing the checksums two peers compute for each tick,
+  recording the first tick they disagree on.
+- `RunHistory` - a local record of completed runs (score, cause of death, whatever a game's
+  own `summary` holds), distinct from `SaveSystem`'s continuable slots.
+- `PlayerStats` - a lifetime running total folded in one run's summary at a time, distinct
+  from `RunHistory`'s per-run records.
+- `TelemetryClient` - sends usage/error events to a server the game supplies.
+- `NewsClient`/`NewsSeenTracker` - a game's own patch-notes/announcement feed, with a
+  seen-tracker so a player is only notified of what's actually new.
+- `checkSize`/`checkNoControlCharacters`/`sanitizeInboundText`/`validateSchema`/`parseInbound` -
+  security sanitization of inbound data: an imported save, a network payload, player-typed
+  text. `parseInbound` is the whole pass in one call (size, control characters, `JSON.parse`
+  refusing `__proto__`/`constructor`/`prototype` at any depth), and every `core` reader of
+  JSON it did not just produce uses it: save slots, `Collection`, stored values, settings,
+  `NewsClient` and `LockstepClient`. Under `file://` Chromium shares one `localStorage`
+  between every local page, so a game's own storage is inbound data too.
+- `Collection` - named, queryable record collections over `localStorage`
+  (`all`/`get`/`put`/`remove`/`where`/`clear`) - a quest log or bestiary, not a save blob.
+- `Recorder`/`Player`/`serializeReplay`/`deserializeReplay` - records `Input.onAction`
+  against `Game`'s own frame counter and replays it deterministically, for testing.
+  Both resume mid-run: `Recorder` takes `fromFrame` so a restored run continues its
+  recording where the checkpoint left it, and `Player` takes `fromFrame` so playback
+  skips what the restored state already contains. `parseReplayEvents` validates an
+  already-parsed event array, the half of the check `deserializeReplay` applies after
+  its own `JSON.parse`.
+- `exportReplayFile`/`importReplayFile`/`LastRun`/`runCheckpoint`/`resumeRunPlayer` -
+  a run made durable (roadmap 396). The file is a versioned, self-describing envelope
+  (`format: 'mwg-replay'`, `version`, `framework`, `game`, optional `seed` and
+  `recordedAt`, `events`), and import refuses another game or another framework build
+  by name, treating the file as inbound data the way a save slot is treated.
+  `LastRun` keeps the newest recording, one deep and bounded, through the same storage
+  a save slot uses; `runCheckpoint(recorder, state)` pairs the partial recording with
+  the game state a save already captured, and `resumeRunPlayer` turns the restored
+  checkpoint back into a mid-run `Player`. The `file://` plumbing rides along:
+  `downloadReplayFile` is a Blob download (no `fetch()`), `pickReplayFile` is the file
+  picker resolving null on cancel, and `readReplayFile` reads any `Blob`, headless
+  Node included.
+- `Achievements` - counters crossing a target unlock a named milestone; `drainNew()`
+  queues unlocks for a UI to announce. An achievement can name several `criteria`
+  instead of one `counter`/`target` (item 273's sub-achievements, "recruit every unit
+  type"), unlocking only once every criterion is met; `subProgress` reads them individually.
+- `Settings`/`GameSettings`/`SettingsOptions`/`CustomSettingValue` - persisted player
+  settings over the same storage `SaveSystem` uses (in-memory fallback under `file://`):
+  music and sound-effect levels, master mute, zoom preference, key bindings (applied to
+  `Input` on load), and a game-defined `custom` bag for the rest (`hints`, `violence`,
+  ...). `defaultSettings` names the fresh-game values, `effectiveMusicVolume`/
+  `effectiveSfxVolume` read 0 while muted, corrupt storage reads as defaults.
+- `Session` - counts launches over the same storage `SaveSystem` uses, for a native
+  wrapper's own rating-prompt timing; never prompts itself.
+- `FeedbackClient`/`HttpTransport`/`HttpTransportOptions` - an injectable HTTPS JSON transport for
+  player-submitted feedback; the game owns the endpoint, consent flow, and server-side storage.
+  Every `HttpTransportOptions` client (`FeedbackClient`, `NewsClient`, `SaveSyncClient`,
+  `TelemetryClient`) and `LockstepClient` refuses an `http:`/`ws:` url to anything but
+  `localhost`/`127.0.0.1`/`[::1]` unless `allowInsecure: true`, and a response body is read up
+  to `maxResponseBytes` (10 MB), refused as soon as it passes the limit.
+- `Spawner` - a `dt`-driven, timed, escalating wave spawner (a horde mode, a survival
+  minigame), distinct from `roguelike.Scheduler`'s turn-order primitive.
+- `hexNeighbors`/`hexDistance`/`hexLine`/`hexRange`/`hexToPixel`/`pixelToHex` with
+  `HexShape`/`HexOrientation`/`HexOffset` - hex grid geometry: cube-based neighbours, lines and
+  ranges, and the pixel projection in both orientations and both offset parities, defaulting to the
+  flat-top odd-q layout this module always had. `pixelToHex` answers with the nearest cell centre
+  rather than a closed-form inverse per combination, so it cannot disagree with `hexToPixel` at a
+  hex's edge.
+- `weightedFlood`/`WeightedCell`/`WeightedFloodOptions` - renderer- and rules-neutral Dijkstra
+  flood over any cell topology, with injected costs, blockers, budget and stopping rules.
+- `cellInside`/`cellIndex`/`cellX`/`cellY`/`cellKey`/`cellFromKey` - bounded-grid indexing:
+  the row-major arithmetic and bounds check that `roguelike.Level` and the `board` modules used
+  to spell out for themselves, now stated once (the Wesnoth port asked for exactly this, to stop
+  duplicating it in its own systems). `cellInside` is the shared bounds check and `cellIndex` is
+  deliberately *unchecked* arithmetic, so a loop that has already proved its coordinates pays
+  nothing while a module that wants a throw or a `-1` keeps that policy in its own method;
+  `cellKey`/`cellFromKey` are the `'x,y'` spelling for `Map`/`Set` membership.
+- `NEIGHBOURS4`/`NEIGHBOURS8`/`CIRCLE8`/`euclidean`/`chebyshev` - one frozen offset table per square
+  neighbourhood, shared instead of copied: axial north/east/south/west, the eight
+  surrounding cells in row-major order, and the same ring clockwise from north (the
+  sequence `roguelike`'s `neighbourOffsets(8)` always returned, now returned as-is from
+  here). `euclidean` is the straight-line ruler, `chebyshev` the king-move one (a
+  diagonal costs one step), and `manhattan` the orthogonal-step count; `distance` measures
+  with the ruler a `DistanceMetric` names, so a data-authored rule picks its geometry by
+  name. `roguelike`'s `chebyshevDistance` delegates to `chebyshev`.
+- `Blob` - a spreading volume field over a grid: a per-cell number that `spread` diffuses a
+  share of into its open 4-neighbours and decays the rest (`decay: 1` conserves and only
+  moves volume around). `seed` adds to a cell, `clear` zeroes one cell and leaves its
+  neighbours alone, and `cellsAbove` lists what a game applies its effect on; what a volume
+  means (fire, gas, ooze, water) stays the game's own reading.
+- `reducedMotion`/`setReducedMotion`/`prefersReducedMotion`/`watchReducedMotion` - the one
+  answer to "should this animate": the OS `prefers-reduced-motion` preference, overridable per
+  game, with a change subscription for something long-lived that has to stop mid-flight.
+  `motionDuration(duration, intent)` is the policy built on it, and `MotionIntent` is the
+  caller's declaration: a `decorative` motion (the default) collapses, a `meaningful` one is
+  shortened rather than deleted, because a change that motion conveys stays readable. `Tweener`,
+  `Camera` (shake and follow), `ScreenEffects`, `ParticleEmitter` and `FloatingText` consult it.
+  `AnimatedSprite` deliberately does not: a frame cycle is usually game state.
+- `Tweener`/`Easing`/`TweenOptions` - a generic `tween(duration, apply, ease?)` plus a small
+  linear/quad/cubic easing-curve set. The third argument also takes `{ ease, intent, alternate }`:
+  `alternate` is the non-vestibular variant to run instead under reduced motion (a fade where a
+  slide was), and it is ignored while the preference is off.
+- `UndoHistory` - gameplay-level undo/redo over pushed, reference-held states.
+- `LoadQueue` - a reusable loading-screen lifecycle: named tasks, aggregate progress,
+  cancellation.
+- `EntityRegistry`/`EntityId` - assigns and looks up stable string ids for live objects, so
+  events, saves, AI targets and buffs can name a creature or item without holding it; not an
+  ECS, and distinct from `Collection`'s persisted, queryable records. `idOf` is what a game
+  passes as `roguelike.Scheduler.toJSON`'s or `simulation.SimulationRuntime`'s `actorId`.
+- `ReactionTable`/`ReactionRule` - declarative `when`/`action` rules checked against any
+  state shape (a `StatBlock`'s values, a plain object's own fields), firing edge-triggered
+  so a still-true condition never re-fires; `once` retires a rule after its first firing. The
+  generic alternative to a branch cascade of `if HP < n` checks in game code, and works the
+  same for a character or an inanimate object such as an item's durability.
+
+## `two-d`
+
+Everything drawn through PixiJS, and the counterpart to `three-d`. The barrel re-exports
+`render`, `ui` and `stage` below, so `mwg/two-d` is a one-stop 2D import; the granular
+subpaths (`mwg/two-d/render`, `mwg/two-d/ui`, `mwg/two-d/stage`) are what a game watching its
+bundle should reach for.
+
+- `Game` - owns the Pixi `Application`, the frame loop, and the current scene; reachable as
+  the singleton `Game.current`. `step(dt)` drives one frame by hand, which defeats Chrome's
+  background-tab throttling of `requestAnimationFrame`. With `autoPause` (the default) it
+  suspends the loop and silences its `audio` rig (`AudioSuspendRig`, an `Orchestrator`
+  fits) on page hide and resumes both on show, via `suspend`/`resume`: the clock parks at
+  0, the top scene hears `onSuspend`/`onResume`, and the player's mute setting is never
+  touched. `qualityScaling` steps the backing-store ratio down after sustained
+  over-budget frames (and back up only after a much longer streak inside budget) via a
+  `QualityScaler` over the static fit, off unless given. It draws at the display's
+  `devicePixelRatio`, reduced to the largest whole number whose backing store fits the device's
+  `MAX_TEXTURE_SIZE`, with a warning naming the limit when that happens: WebGL clamps a larger
+  request silently, so a device with a small limit renders softer rather than not at all.
+- `Scene2D` - `core.Scene`'s lifecycle plus the `stage` container everything this screen draws
+  hangs off, destroyed with the scene. This is what a 2D game extends.
+
+### `two-d/render`
+
+Pixi-backed 2D rendering: sprites, tile maps, camera, animation. All Pixi
+batcher/high-shader internals are confined to `ColorTransformBatcher.ts`.
+
+- `ColorTransformBatcher`/`packColorAdd`/`packTintAdd`/`NO_COLOR_ADD` - a per-sprite
+  `texel × M + A` colour transform (multiply *and* add) in the batch shader.
+- `TintedSprite`/`registerColorTransform` - a sprite drawn through the colour-transform
+  batcher; register the extension once via `GameOptions.extensions`.
+- `parseImagePath`/`imageModifier`/`colorShiftMatrix`/`applyImageModifiers`/`croppedTexture` - parses common
+  image suffix modifiers such as `~FL`, `~GS`, `~SCALE` and `~CROP`, then applies the supported
+  Pixi presentation changes without mutating shared source textures. `channelScaleMatrix`
+  (`~R`/`~G`/`~B`) builds the `ColorMatrixFilter` matrix `applyImageModifiers` also applies for
+  `~O` (opacity) and `~CHAN` (`channelSwapMatrix` - a channel-source swap/constant, not
+  Wesnoth's own per-channel formula language). `applyTextureModifiers`/`ImageTextureProbe`
+  cover the modifiers that need real pixel access, a sibling texture, or have to rotate the
+  actual art rather than a sprite transform: `~RC`/`~PAL` (exact palette swap - see
+  `recolorTexture` below - accepting hex or, via `probe.resolveColor`, a named colour;
+  `parseColorPairs`/`parsePaletteLists` are the argument parsers, the latter reconstructing
+  `~PAL`'s two comma-separated colour lists since `parseImagePath`'s own comma split does not
+  respect that list boundary), `~BLIT`/`~MASK` (composite/mask against a `probe.resolveTexture`-
+  resolved sibling texture at an offset - it receives the argument exactly as written, nested
+  modifiers included, not a bare path; `maskPixels` is `~MASK`'s renderer-free alpha-multiply
+  core), `~BLEND` (`blendPixels`, an exact per-pixel lerp towards a colour, baked once - not the
+  runtime `ColorMatrixFilter` approximation `blendMatrix` still offers on its own) and `~ROTATE`
+  (`rotatePixels`, which rotates the source pixels and expands the surface, unlike a sprite's own
+  `rotation`; `~ROTATE(degrees)` samples nearest-neighbour, exact at quarter turns, and
+  `~ROTATE(degrees,linear)` blends the four pixels around each sample point instead - what a
+  non-square angle onto a hex grid needs. `parseRotateMode` is the second argument's parser, and
+  both modes sample premultiplied so a transparent neighbour contributes coverage and never
+  colour. It is bake-time work: measured, `linear` costs 2.4 to 4.2 times `nearest` per image -
+  0.45 ms against 0.12 ms for a 64x64 tile at 60 degrees, 3.6 ms against 1.5 ms at 256x256 - for a
+  visibly smooth edge, once, while the texture is built).
+  `spriteColorMatrix(sprite, matrix)` (item 309) attaches any of the matrix
+  builders above (or `blendMatrix`, or a game's own) to a sprite as a `ColorMatrixFilter`, the
+  one remaining case that needed a direct `pixi.js` import just to construct that one class.
+  `applyAllImageModifiers(sprite, parsed, probe?, scale?)` (item 310) is the two-step recipe
+  `applyImageModifiers`'s own doc comment names, run for a caller in one call: it bakes
+  `applyTextureModifiers`'s exact pixel-level result into `sprite.texture` first, then applies
+  the sprite-property/filter modifiers on top, so a `~BLEND`/`~ROTATE` path never silently gets
+  `applyImageModifiers`'s no-op for them.
+- `remapPixels`/`paletteRangeMapping`/`recolorTexture`/`withTextureCanvas`/`PaletteMapping`/
+  `PaletteRange`/`PaletteRemapMode` - palette-remap recolouring (team colour by range, not
+  multiply/add): `remapPixels` is the renderer-free core, `'exact'` by default (a pixel is
+  repainted only on an exact match to a `from` colour, correct for a short specific list like
+  `~RC`/`~PAL` and for a `paletteRangeMapping` over a reference palette, where the pixels outside
+  it are the ones the art deliberately left alone) or `'nearest'` (every opaque pixel repainted by
+  closest match, which a palette covering the whole image wants - the wrong mode for a sparse
+  list, where it silently recolours the entire image). `paletteRangeMapping` builds a
+  `[color_range]`-shaped mapping: the reference palette's *first* colour is its anchor and becomes
+  `mid`, and every other entry is shaded by its own brightness, darker towards `min` and brighter
+  towards `max`, with the floored average and truncated blend a Wesnoth `[color_range]` team
+  colour is defined in, so a range's shades come out byte for byte as the engine's own. The
+  reference after its anchor needs no order. `recolorTexture` is the canvas-backed wrapper, built
+  on the shared `withTextureCanvas` helper `applyTextureModifiers` above also uses.
+- `AnimatedSprite`/`Animation` - frame-sequence sprite animation. A frame may carry its own
+  duration (Wesnoth's `image=a.png:120,b.png:80`), and an animation may start partway into itself
+  or after a delay (`startTime`, which is what `start_time=-450` on an attack means: begin four and
+  a half frames in, so the hit lines up with the damage frame). A frame may also carry an offset,
+  reported through `AnimatedSprite.frameOffset` for the caller to add where it positions the sprite,
+  because that position is the caller's (`GridMover`, a walk tween) and a sprite that overwrote it
+  every frame would undo it every frame.
+- `SpriteGroup`/`isOnScreen` (item 369) - animate only what is on screen: `update(camera, dt)`
+  advances the members inside `camera.view` (plus `margin`) and leaves the rest on their current
+  frame, so a crowd of `AnimatedSprite`s (or `ParticleEmitter`s, which satisfy the same
+  `SpriteGroupMember` shape) costs no CPU off screen. Never freezes anything visible: under a
+  rotated camera the tested box is the over-inclusive one `TileMap.cull` uses.
+- `SpriteSheet` - a grid-sliced sprite sheet, or, built with no frame size, one whose frames are
+  its own `rect(index, x, y, width, height)` declarations: a hand-packed icon atlas, a strip of bar
+  segments, an item whose art is smaller than its cell. A rect is cached under its index like any
+  grid frame, so `get`/`region`/`name`/`pick` treat the two the same and no site hand-builds a
+  `Texture`.
+- `Camera`/`createCamera`/`snapZoom` - world-to-screen camera; `snapZoom` keeps tile edges
+  pixel-aligned at a fractional zoom. Fixed-angle view rotation (item 285): `grid` picks four
+  quarter turns (square, the default) or six 60-degree steps (hex), `setRotationStep`/`rotate`
+  move through them, `toScreen`/`toWorld` invert the turn so a click still lands on the cell aimed
+  at, `view` reports the box around the turned viewport for culling, and `uprightRotation` is the
+  angle that keeps a label drawn into the world upright. Free rotation (item 286): `rotateTo` turns
+  to any angle immediately and `animateRotationTo` eases towards one, shorter way around the turn,
+  sharing the same angle and the same `toScreen`/`toWorld`/`view` math the stepped API uses.
+  `shakeScreen(intensity, duration)` (item 303) is `shake` taking screen pixels instead of world
+  units, dividing by the current `zoom` once so a caller thinking in screen pixels (a convention
+  several engines use for this call) does not have to at every call site.
+- `Viewport`/`splitScreenHalves` - a camera scoped to one screen region, for split-screen.
+- `createColorBlindnessFilter`/`COLOR_BLINDNESS_MATRICES` - accessibility colour filters.
+- `Minimap`/`newlyRevealed`/`minimapCellCenter`/`MinimapMarker` - bakes an explored-cell set
+  into a persistent `RenderTexture`, never redrawing an already-baked cell, and supports
+  several game-owned unit or quest markers.
+- `TileMap`/`EMPTY`/`tileFrame`/`tileFrameSheet`/`tileFrameIndex` - tile map rendering:
+  square/hex/isometric/staggered projections, multi-sheet tiles, elevation columns.
+- `LayeredSprite` - layered character sprites (body/hair/equipment as separate layers).
+- `SkeletalSprite`/`ArticulatedChain`/`ChainRig` (items 399/400) - bones driving drawn
+  parts: the pose math lives in the renderer-free `skeleton` module (bone tree, keyframed
+  clips, crossfade, priority layers), `SkeletalSprite` binds a part to a bone by name and
+  `update(dt)` places it at the bone's world transform, and `ArticulatedChain` is the
+  follower rule a keyframe cannot express - a serpent's spine whose segments ease toward
+  their parent's previous position within per-segment rotation limits.- `Projectile` - tweens a sprite in a straight line for a thrown/shot visual flourish; an
+  optional `animation` (item 311) advances flight frames with the tween's own elapsed time, read
+  back through `frame`/`frameOffset` so the caller can apply the frame's offset where it already
+  positions the sprite. `Flights` owns the live ones: `add(sprite | texture, from, to,
+  { speed, tint?, spin? | spinDegrees?, fadeIn?, onArrive? })` returns a handle, `update(dt)` drives
+  positions and dispatches each arrival exactly once, `cancel()`/`clear()` forget without
+  dispatching; caller sprites stay caller-owned while texture-built sprites are parented
+  here and destroyed with their flight. `spinDegrees` is `spin` in degrees per second
+  (converted once, so an authored angular speed needs no radian arithmetic at the call
+  site) and `fadeIn: 'progress'` (or `true`) eases the sprite's alpha 0 to 1 along the
+  tween's own progress instead of seconds from launch.
+- `LightningArc` - the position data for a jittered line between two points (a bolt, a tether):
+  `points` tapers to zero offset at both endpoints, `retarget` moves either endpoint for a
+  tether following two moving units, and an optional `flickerInterval` re-rolls the jitter on a
+  timer. Geometry only, drawn by the caller through `Shape2D`'s `Graphics`. `Beam` is the
+  drawn one-shot counterpart (a fading line, or a texture strip - repeating by default,
+  or `BeamTextureOptions`' `stretch: true` for art that spans the whole beam once, with an
+  `anchor` placing it across the thickness - additive by default, `retarget` moving
+  either end, `thin` narrowing the body as it fades, `update` reporting expiry once);
+  `Beams` owns the live ones with `add`/`update`/`clear` and destroys finished beams.
+- `SpriteAttachment` - ties a second sprite's position to a first one's: `follow(x, y)` applies
+  an offset, and an optional `duration` makes `update(dt)` report `done` once it elapses, so a
+  permanent shadow and a temporary status icon are the same class with different options.
+  Renderer-neutral like `Projectile`/`LightningArc`; z-order and parenting stay the caller's.
+- `LiquidLayer`/`LiquidLayerOptions` - an animated liquid surface under a map: one scrolling
+  tiling quad per liquid cell with its own visibility tint (`setCellColor`), and `ripple` rings
+  that grow and fade; pure decoration, every child opts out of pointer events.
+- `FogLayer`/`paintFogPixels`/`FogCell`/`FogColor`/`FogLayerOptions` - a smooth fog-of-war
+  overlay: a small linear-filtered canvas with `resolution` pixels per tile, so fog edges blur
+  across cells and one cell can be shaded in parts; `paintFogPixels` is the same shading as a
+  pure function over an RGBA buffer.
+- `TileMap.stampRect` copies a block of frames into a layer at a tile position and throws when
+  it does not fit; `AutotileSet.mode: 'mixed'` reads the MV A4 sheet's alternating rows with the
+  floor table (wall tops) and the wall table (wall faces).
+- `Halo`/`HALO_ANIMATION` - the glow around a unit, an aura, a shrine's light: an `AnimatedSprite`
+  drawn additively (Wesnoth's `[halo] blend_mode=add`) whose `follow(x, y)` applies the halo's own
+  offset once instead of in every game that draws one. Z-order stays the caller's, because a halo
+  that belongs behind its unit is added before it and one that belongs in front is added after, and
+  a framework that guessed would be wrong half the time.
+- `ParticleEmitter`/`Particle` - a pooled, seeded particle emitter (sparks, dust, rain):
+  `burst`/`start`/`stop` over a pool allocated once at `max`. Runs the whole simulation with
+  no `texture` given, which is how it is tested without a renderer. `ParticleSpawnArea` gives
+  births a local `rect` or `ellipse` extent instead of the emitter's single origin. `scale` and
+  `alpha` take a `ParticleCurve` (`t` over the particle's life) as well as the birth-to-death
+  pair, `tint` takes a `[from, to]` range each particle draws its own colour from channel by
+  channel, and `flicker` wobbles the scale every frame with a seeded draw (dropped under reduced
+  motion). All three draws happen only when used, so an existing emitter's seeded spray is
+  unchanged. `attach(target)` follows a display object or position thunk on every tick (with `offsetX`/`offsetY`, an `enabled` callback gating tick emission, a `visible` callback hiding the whole spray (fog-of-war gates) while the simulation steps on behind the invisibility, and auto-detach for destroyed targets); `detach()` keeps the last position.
+- `ScreenEffects`/`ScreenEffectStep` - a full-screen colour wash: `fadeOut`/`fadeIn`/`flash`/
+  `setTint`, driven by `update(dt)` returning true on the frame an effect completes.
+  `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.
+- `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
+  at 1 rather than wrapping. Never touches the multiply `tint`, so a sprite's own identity
+  tint (a team colour) survives underneath. `flash(color, strength, duration)` layers a
+  one-shot, linearly-decaying pulse (a hit, a heal) on top of whatever is active.
+- `SpriteMotion` - squash, hop, bob, wobble, spin, shear and flip over any display object's
+  transform through a `Tweener` (item 404). Effects compose from the rest pose captured at
+  construction, never drift, return a `MotionHandle` (`done`, `cancel()`), and follow
+  `setReducedMotion`; `destroy` restores the rest pose, flips included.
+- `ClothSprite` - a `physics` `Cloth` mesh drawn as a textured sprite on the 414 mesh
+  path (item 423): owns the simulation, `update(dt)` steps it and re-uploads the vertex
+  buffer, the top edge starts pinned, UVs are never rewritten. `setWind`/`pinPoint`/
+  `unpinPoint` tune it, and it honours `setReducedMotion`.
+- `Spring` - a damped 2D chase spring for secondary motion (item 424): the anchor
+  teleports, the bob lags, overshoots and settles through pure arithmetic, O(1) per
+  update, deterministic for a fixed `update(dt)` sequence. `place(target)` parks a
+  follower on the bob; honours `setReducedMotion`. `SpringSprite` draws the
+  anchor-to-bob line, redrawn by an explicit `sync()` after stepping.
+- `HazeLayer`/`hazeField`/`paintHazePixels` - an atmospheric haze sheet, never fog of war:
+  translucent drifting weather with soft edges, density and per-plane wind, on a small
+  canvas scaled up with linear filtering. `paintHazePixels` is the same shading as a pure
+  function over an RGBA buffer, which is how it is tested without a renderer.
+- `NeonGlow`/`glowFalloff`/`paintGlowPixels` - a soft additive halo baked from a shape or
+  mask, with colour, radius, intensity and flicker; a global bloom stays optional.
+- `loadTiledMap`/`TiledMapData`/`TiledTilesetData`/`TilesetSheet`/`LoadedTiledMap` - loads
+  Tiled JSON maps into a `TileMap`: orthogonal, isometric and staggered orientations, multiple
+  tilesets (embedded or external `.tsx`). Lives here rather than in `rpg` because what it
+  builds is a `TileMap` out of `SpriteSheet`s.
+- `blobIndex`/`autotileFrames`/`BLOB_SHAPES` - auto-tiling: the 47-shape "blob tile"
+  reduction of 8-neighbour terrain matches.
+- `rpgmAutotileFrame`/`RpgmAutotileAtlas` - renderer-neutral RPG Maker MV autotile atlas
+  geometry: decode one of the four atlas slots, select its four 24px source quadrants for a
+  shape, and describe their 48px output position. `RpgmAutotileAtlas` caches repeated frame
+  descriptions. `RPGM_FLOOR_AUTOTILE_TABLE`/`RPGM_WALL_AUTOTILE_TABLE` are the standard MV
+  shape tables, `RPGM_AUTOTILE_SLOT_BASES`/`RPGM_AUTOTILE_SLOT_COUNTS` the family address
+  facts, and `rpgmAutotileSlot` classifies a raw map id into its family (item 370).
+- `TileMap` `addAutotileLayer` over `AutotileSet`/`AutotileCell` - a native autotile layer:
+  raw MV ids or XP values route to the set claiming them, and the map assembles each
+  cell's quadrant halves straight from the source sheet (item 370). `setAutotileFrame`/
+  `getAutotileFrame` advance and read the animation frame; `setTile`/`getTile` keep
+  working with raw ids. `XP_AUTOTILE_PATTERNS`/`XP_NEIGHBORS_TO_PATTERN` are the XP
+  template and neighbourhood tables, `xpAutotileRef`/`xpAutotilePattern` decode and
+  compute XP cells, and `autotileCellParts`/`assertAutotileLayout` resolve and validate
+  one cell's pieces renderer-free.
+- `AutotileSet.tableEdge` with `rpgmTableEdgeCells` over `RpgmTableEdgeMap` - the front-edge strip
+  the engine draws under an A2 table: `rpgmTableEdgeCells` finds the cells that get one (table
+  above, none here, no A3/A4 wall on the ground layer) and the set draws its two half-height
+  pieces. `TileMap` `addShadowLayer` over `ShadowLayerOptions` adds the engine's shadow bits
+  (map layer 4) as translucent quarter-tile quads.
+- `resolveTerrainGraphics`/`matchTerrainRule`/`squareRotate`/`hexRotate` over `TerrainRule`/
+  `TerrainCondition`/`TerrainImage`/`TerrainPlacement`/`TerrainFlagsAt` - a rule-driven
+  `[terrain_graphics]`-style transition pass for what `Autotile`'s fixed 47-shape table cannot
+  express: flag conditions at arbitrary offsets, one rule placing more than one image (so a
+  piece bigger than one cell is the rule's own data, not something `TileMap` has to hold),
+  `rotations` (`squareRotate`'s 4 exact steps or `hexRotate`'s 6) and `probability` breaking a
+  tie among rules matching at equal specificity. Returns plain placement data.
+- `TerrainGraphicsLayer` over `TerrainGraphicsLayerOptions` - the renderer for that data: one
+  `Sprite2D` per placement, added in `layer` order (a stable sort, so the rule pass's own
+  row-major walk survives within a layer), each resolved through the asset resolver at the pixel
+  position the caller's `project` callback reports. `setPlacements` redraws; z-order against the
+  rest of the scene is the caller's, as it is for `Halo`.
+- `inspectGraphicsCapabilities`/`detectWebGpu`/`RENDERING_DECISIONS` - checks
+  WebGL/WebGPU/WGSL support and records this project's own rendering-backend decisions.
+- `Container2D`/`Texture2D`/`Rectangle2D`/`Rect`/`TextureRegion`/`rectOf` - the renderer
+  boundary names for common 2D values. The first three work in both type and value positions,
+  so a game can construct a container or use texture and rectangle constants without naming
+  `pixi.js`. For the rare need the facade does not cover, `two-d/pixi-interop` re-exports the
+  underlying Pixi classes explicitly.
+- `Node2D`/`Shape2D`/`Text2D`/`Sprite2D`/`TiledSprite`/`Gradient` - bare, MWG-named
+  re-exports of Pixi's `Container`/`Graphics`/`Text`/`Sprite`/`TilingSprite`/`FillGradient`:
+  a plain grouping layer, vector drawing, one-off text, a plain untinted sprite, a
+  repeating/scrolling texture, and a gradient fill/stroke, none of which needed new
+  behaviour, only a name a game can import without naming `pixi.js` itself. Prefer
+  `ui.Label`/`BitmapLabel` over `Text2D` for anything styled through `ui.theme()`, and
+  `render.TintedSprite` over `Sprite2D` the moment a colour transform is needed.
+- `createLayers(parent, names)` (item 312) - builds one labeled `Node2D` per name, attached to
+  `parent` in the order given and returned keyed by name, so a game's conventionally-ordered
+  layer stack (terrain, units, effects, UI, ...) is one call rather than a dozen hand-wired
+  containers.
+
+### `two-d/ui`
+
+Windows, lists, message boxes, HUD widgets - all themed from one live-swappable `Theme`.
+
+- `theme`/`setTheme`/`defaultTheme`/`highContrastTheme`/`themeChanged` - the active theme;
+  `setTheme` fires `themeChanged` so already-built widgets restyle in place.
+- `Label` - a themed text wrapper over Pixi `Text`; `stroke`/`resolution`/`roundPixels`
+  options, useful for text over artwork.
+- `parseMarkup`/`stripMarkup`/`markupToHtml`/`escapeHtml` over `MarkupSpan`/`MarkupOptions` - inline
+  markup (`<b>`, `<i>`, `<span color='…' size='…'>`, `<br/>`, `<img>path</img>`, `$name`, and the
+  five entities) as a renderer-neutral contract: a `MarkupSpan` is a `MarkdownSpan` plus the colour,
+  size and image a renderer may use, kept as written because resolving them is the renderer's
+  business. Unknown tags, malformed tags and unset variables stay literal rather than disappearing,
+  and `markupToHtml` is the escaped HTML fragment for a renderer that speaks HTML text - it now
+  also renders colour and size, as an inline style. `MarkupOptions.tags` (item 313) names extra
+  tags to treat as styling containers; a run inside one carries its name in `MarkupSpan.tag`, so a
+  renderer can resolve its style (Pixi's `tagStyles`) while the parser stays renderer-neutral, and
+  `markupToHtml` re-emits that tag as a real element for `HTMLText`. `markupAccessibilityText` is the proper
+  accessibility projection (an image becomes a caller-described string, not its raw path, which
+  `stripMarkup` keeps for round-tripping instead). `layoutMarkupLines` wraps already-parsed spans
+  word by word against a caller-supplied `MarkupMeasure`, each word measured under its own
+  span's style - wrapping computed *after* styling, so a bold or larger run wraps where its own
+  wider glyphs actually land - and `positionMarkupLines` places those already-laid-out lines into
+  `PositionedMarkupSpan` runs (one `x`/`y` per span) under a `MarkupLayout`'s `direction`/`align`,
+  so an `rtl` line flows right to left and alignment defaults to the direction's own edge. Both
+  are backend-neutral: the same spans, `measure` and `maxWidth` decide the same line breaks and
+  the same runs whether a caller then draws them through `HTMLText` or a canvas `Text2D` pass.
+- `MarkupText`/`MarkupTextOptions` - the canvas backend for that contract, the counterpart to
+  `RichLabel`'s HTML text: one `Text2D` per styled run and one `Sprite2D` per `<img>` span,
+  resolved through the asset resolver, so an image is drawn rather than a caller positioning it
+  itself at a `layoutMarkupLines` offset. It reads `direction` from the theme and takes
+  `maxWidth`/`lineHeight`/`align`/`resolveImage`/`variables`/`resolution` options, plus
+  `tagStyles` (item 313): a Pixi `TextStyleOptions` record keyed by custom tag, applied to each
+  run and used when measuring it, so `<quest>...</quest>` is styled and wraps under its own font.
+- `RichLabel`/`parseMarkdown`/`stripMarkdown`/`sliceSpans` - basic inline markdown (`**bold**`,
+  `*italic*`, combined `***both***`, backslash escapes) through Pixi `HTMLText`, which is
+  what makes mixed styles inside one string possible at all. `parseMarkdown` is pure
+  span-splitting (unmatched markers stay literal); `stripMarkdown` recovers plain text;
+  `sliceSpans` takes the first N visible characters with styles kept, for progressive
+  reveal without leaking half-shown markers. Costs more than a `Label`, so this is for
+  descriptions and help bodies, not per-frame numbers. `tagStyles` (item 313) takes Pixi
+  `HTMLTextStyleOptions` keyed by custom tag; a registered tag survives escaping as a real element
+  for `HTMLText` to style, while an unregistered one is still escaped as literal text.
+- `startReveal`/`advanceReveal`/`completeReveal`/`revealComplete` - the shared
+  progressive-display primitive: one character count behind `MessageBox` pages (which
+  already revealed this way), `Label` lines, and `RichLabel` markdown. `Label` and
+  `RichLabel` expose it as `showProgressive`/`updateReveal`/`completeReveal`, driven by
+  the game's own frame loop; `MessageBox` keeps its confirm-completes-then-advances rule
+  on top unchanged.
+- `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
+  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
+  full-viewport layer that swallows clicks and dismisses the window for a click outside it
+  (`handleOutsideClick` is that decision).
+- `WindowStack` - keyboard focus goes to the top window only; dims what's underneath; `blocker` on
+  a window is what stops clicks reaching the map behind it. `handleAction(action)` is public so a
+  scene with its own key handling can ask the windows first: `Input.onAction` offers an action to
+  the most recently registered listener first, so a scene that registers after building its stack
+  is asked before the windows are and can swallow a key they need.
+- `MessageBox.blocker` - whether a click under the box reaches the map behind it; on by default,
+  and since the box is not closable that can only ever swallow clicks rather than dismiss it.
+  `blocker: false` is for a box the player is meant to click past.
+- `ListView` - a scrollable, keyboard- and pointer-navigable row list (click, wheel-scroll);
+  `multiple` checks rows instead of picking one, read back through `checkedIndexes`.
+- `IconGrid` - a multi-column icon-grid inventory view; tap-then-tap "drag and drop",
+  frame-driven long-press for a quickslot.
+- `TabbedList`/`ListTab`/`TabbedListOptions` - a renderer-free model for an inventory, journal,
+  shop or codex: caller-supplied tabs and rows (no assumed taxonomy), an optional label,
+  filter and disabled predicate, selection that skips disabled rows, a page derived from the
+  selection rather than tracked beside it, and an `openDetail`/`closeDetail` state.
+- `Slider`/`SliderOptions` + `sliderFraction`/`sliderValueAt` - a draggable knob on a themed track;
+  the two pure functions are the value/track arithmetic (clamping, the step grid, the degenerate
+  range), so a game routing its own input snaps the same way.
+- `Checkbox`/`CheckboxOptions` - a ticked-or-not box; a caption is a `Label` the game places beside
+  it, and `onChange` fires only when the state moves.
+- `RadioGroup`/`RadioOption`/`RadioGroupOptions` - exactly one choice among several: arrows
+  move the selection and select at once, a tap selects directly, disabled options are skipped.
+- `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`.
+- `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
+  `onText`: caret, anchor, selection-replacing edits, a length cap and a mask. Renderer-free.
+  `multiline` keeps real newlines with row navigation (`lineCount`, `caretLine`, `lineRange`,
+  `moveCaretLine` holding a sticky goal column); single-line fields strip them on every edit.
+- `TextPrompt`/`TextPromptOptions` - a modal single-line text field over a `TextModel` (a name
+  entry, a save-slot label): typing through `onText`, caret and edits through `left`/`right`/
+  `backspace`/`delete` actions, `confirm` gated by `validate` (the error shows and announces
+  assertively, the prompt stays open), `cancel` giving up. IME compositions preview until
+  they commit, and the message plus validation errors announce through `screenReader`.
+  The interface example's Name button is the reviewed hosting pattern: push it on a
+  `WindowStack` and it owns focus, closing and the stack's un-popping by itself.
+  The touch half (roadmap 402): `keyboard: UPPERCASE_KEYBOARD` (or any `KeyboardLayout`)
+  hosts one beneath the field and resizes the window to fit it - `OnScreenKeyboard`,
+  next.
+- `OnScreenKeyboard`/`KeyboardLayout`/`KeyboardKey` + `UPPERCASE_KEYBOARD`/`pressKey`/
+  `layoutKeys` - pointer-only typing: a layout is rows of keys as plain data (ragged rows
+  fine), each key a caption, the `text` it types (defaulting to its label), or the named
+  `action` it fires instead, plus a `span` in row units for a space bar. The class renders
+  it through the theme's own `Button` and reports `contentHeight` so a host can size
+  itself; `pressKey` is the pure dispatch rule (`dispatchText` for a typing key,
+  `dispatchAction` for an action key, the two paths a physical key travels, so no
+  listener can tell a tap from a keystroke) and `layoutKeys` the rows-to-buttons
+  arithmetic behind it. `UPPERCASE_KEYBOARD` is the one shipped default: the alphabet
+  over a digit row, then `Bksp`, caret moves, space, `OK`, `Esc`.
+- `DataTable`/`TableColumn`/`DataTableOptions` - a renderer-free columned table: sort by a column
+  (toggling direction), a highlight that skips disabled rows, and a page derived from the
+  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.
+- `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`/
+  `LayoutRect` - data-driven shell layout (item 263): named anchors placed inside bounds (margin,
+  offset, fill), and columns/rows that are `size` or `grow`, so one sidebar plus one content column
+  needs neither side to know the window's width. Pure geometry, renderer-free.
+- `Skins` with `Skin`/`SkinStates`/`SkinData`/`WidgetState` - per-widget, per-state looks looked up
+  by name, the counterpart the one global `Theme` has no room for. A lookup falls back widget state
+  -> widget idle -> wildcard state -> wildcard idle -> `{}`, and `Skins.from` reads the plain data a
+  config file would parse into.
+- `MessageBox` - dialogue text box: paged reveal, choices, ADV/NVL display modes,
+  `autoAdvance`, and timed `{sound:path}` markers delivered through `onSound`.
+- `messageBoxPresenter` - wires `rpg.EventRunner`'s dialogue to a `MessageBox` on a
+  `WindowStack`, in one argument: `present: messageBoxPresenter(this.windows)`.
+- `VerticalLabel`/`layoutVertical` - vertical writing layout, with CJK glyph rotation.
+- `RebindScreen` - a keybind-rebinding flow over `Input`, with an optional conflict hook.
+- `SettingsScreen`/`SettingsCustomRow`/`SettingsScreenOptions` (item 364) - a ready-made
+  settings screen over `core.Settings`: music/sfx sliders, mute checkbox, zoom slider,
+  one row per `custom` descriptor (boolean/number/choice), an embedded controls page
+  that writes rebinds back into `Settings` on exit, and a reset row. `cancel` on the
+  main page returns false for the caller to close.
+- `Button`/`ButtonSkin`/`ButtonState` - idle/hover/pressed/disabled clickable region, icon
+  and/or text, optional per-button nine-patch skin with per-state tints.
+- `Bar` - a filled-proportion track (health/mana/XP); flat colour or texture, optional
+  `roundUpToPixel` so a nonzero value never rounds down to invisible.
+- `Meter`/`MeterOptions` (item 368) - a discrete meter: N icons with a value filled, the
+  heart row or star rating to `Bar`'s continuous fill. Fractions clip mid-icon through a
+  mask, so halves need no extra art; flat theme pips by default, a game-supplied
+  filled/empty texture pair (which must come together) otherwise.
+- `FloatingText`/`floatingTextAlpha`/`floatingTextRise`/`floatingTextAgeAtLeast` - a rising, fading
+  damage/pickup number and its pure motion, opacity and age curves; `FloatingTextStack` with
+  `floatingTextStackLift`/`floatingTextStackMoves`/`floatingTextStackLifePenalty` and
+  `FLOATING_TEXT_STACK_GAP` stacks simultaneous pop-ups at one world point without overlap, lifting
+  the lines already there the way Java's `FloatingText.push()` does.
+- `MessageLog`/`linesToDrop`/`takeLastEntries`/`MessageLogEntry`/`MessageLevel`/`MessageLogOptions` - a player-facing message pane:
+  one coloured block per message (info, positive, negative, warning, highlight) that drops the
+  oldest blocks once the wrapped lines pass a cap; `linesToDrop` is that budget as a pure function,
+  and `lastEntries(n)` reads the newest retained entries back as `{ text, level }` records
+  (oldest first) without scraping rendered children.
+- `fitWindowZoom`/`sharpenText` - step a window stack's integer zoom down until its content fits
+  the viewport, and re-rasterise every `Text` under a zoomed container at device ratio times its
+  on-screen scale so it is not magnified 1x text.
+- `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.
+- `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`.
+- `ScreenReader`/`screenReader` - the screen-reader bridge: `Window` announces its title,
+  `MessageBox` each page and its choices, and `TextPrompt` its message and validation errors
+  through a visually hidden `aria-live` region, and a game's own widgets use the same
+  `screenReader.announce(text, { assertive })`. No-ops where there is no DOM, so ordinary
+  scene code needs no guard around it.
+- `contrastRatio`/`meetsContrast`/`relativeLuminance`/`ContrastLevel` - WCAG contrast for a
+  `theme` palette: the standard luminance and ratio formulas with AA/AAA thresholds, so a
+  game checks its own colours rather than guessing.
+
+### `two-d/stage`
+
+Dialogue scenes: backdrop, characters, a script runner - the visual-novel half.
+
+- `DialogueStage`/`CharacterDefinition`/`ShowOptions` - backdrop plus character
+  conversation scenes; the speaking character lit, others dimmed.
+- `StageScript`/`StageCommand`/`StageChoice`/`StoryScript` - a command interpreter;
+  `runStory` follows a named-passage graph (`{goto}`, choice jumps); `history`/`showLast`
+  for read-only dialogue rollback; `skipSeen` for auto-advancing already-read lines;
+  `ScriptOptions.mode: 'nvl'` for the accumulating-block presentation.
+- `importTwee`/`TwineStory` - imports Twee-notation Twine stories into `StageScript`'s
+  command format, a thin wrapper around `core.parseTwee` naming the `StoryScript` return
+  type. `rpg.importTwee` is the same wrapper around the same engine, targeting
+  `EventStoryScript` instead, so a text-only RPG needs no Pixi dependency to import a
+  branching Twee story, and a visual novel that never touches map events needs no `rpg`
+  dependency either.
+- `parseDialogueText`/`extractDialogueCatalog` - a terse line-based dialogue format for
+  straight (non-branching) scenes: `@id text` names the speaker, an unprefixed line
+  narrates, and `- text` alternates between the first two speakers established by `@id`
+  lines (capped at two - a third distinct speaker is refused). A thin wrapper around
+  `core.parseDialogueLines`, mapping its `speaker` field onto `StageCommand`'s `as`.
+  `extractDialogueCatalog` builds an identity `i18n` catalog from the resulting commands
+  (or a `StoryScript`), the same shape MWL's own `extractCatalog` builds from
+  `_("...")`-marked strings. `rpg.parseDialogueText` is the same wrapper around the same
+  engine, targeting `EventCommand` instead, so a text-only RPG needs no Pixi dependency to
+  use it, and a visual novel that never touches map events needs no `rpg` dependency either.
+- `StoryScreen`/`StoryScreenOptions` with `StorySequence`/`StoryBeat` - the between-scenario
+  interlude `DialogueStage` is not: a full-screen backdrop, title and text advanced by a click. The
+  sequencing (advance/back/`goTo`/`skip`/`restart`, and the current beat's `music` reported as a
+  signal so the game plays it) lives in the renderer-free `StorySequence`, and a `StoryBeat` has
+  the same `{ text, title, image, music }` shape as `MwlWorld.story`.
+
+## `assets`
+
+The `file://` story: a compiled build resolves paths through a `data:` URI map; dev mode
+serves them normally. Load once per scene; everything after is synchronous. The compiler side
+of this (`tools/compile-resources.mjs`, `tools/emit-page.mjs`, `tools/single-file.mjs`) offers
+independent build options on top of that one story - multi-file vs. single-file output,
+compression (gzip or brotli, single-file only), and WebP image conversion - documented in
+`DEVELOPMENT.md`'s "Build options" section and `tools.md`'s tool reference; none of them
+change what a game calls to load an asset.
+
+Split by renderer specificity: `assets/paths.ts` resolves paths and needs no renderer,
+`assets/binary.ts` caches raw bytes just as renderer-free, `assets/loader.ts` fetches and
+decodes *textures* through Pixi. The `assets` barrel exposes all three; a game rendering
+through something else imports `@datamoc/mw_games/assets/paths` or
+`@datamoc/mw_games/assets/binary` and pays nothing for Pixi, which is how `3d` and `audio`
+reach the compiled asset map without it.
+
+- `setBase`/`setAssetMap`/`isCompiled`/`paths`/`has`/`resolve` - dev-vs-compiled path
+  resolution, renderer-free (also its own entry point, `@datamoc/mw_games/assets/paths`).
+  `setAssetMap` hands these a game's own path-to-URI map directly (item 300), for a game
+  bundled by its own tool rather than `tools/compile-resources`, and takes priority over
+  `window.__MWG_ASSETS__` while set; `undefined` reverts to it.
+- `load`/`texture`/`get`/`isLoaded`/`release` - load assets by path, read them back
+  synchronously, and free GPU memory once a zone is no longer needed. `load(paths,
+  { resolution })` rasterizes a vector source (SVG) at a multiple of its intrinsic size, so a
+  game that zooms into an icon asks for a `2` or `3` instead of shipping a soft bitmap;
+  `onProgress` is the same `LoadQueue` seam whether passed alone or in the options. `optional`
+  loads those paths separately so one missing file never aborts the required batch, calling
+  `onMissing` for each; `texture`/`get` take a `fallback` returned instead of a throw for a
+  path that never loaded, so a caller stops needing its own try/catch around a missing asset.
+- `sanitizeSvg`/`svgScaleVariants`/`svgDataUri`/`splitSvgGroups` (item 398) - SVG as
+  inbound data: `sanitizeSvg` refuses what it cannot prove inert by name (script,
+  `foreignObject`, event handlers, `javascript:` and active `data:` URLs - a gate, never
+  a silent rewrite), `svgScaleVariants` rasterizes one proven-inert source once per named
+  scale with its resolution hint, and `splitSvgGroups` loads a group-authored SVG as one
+  standalone part per top-level `<g id=...` group, the authoring form for an SVG puppet.  `load` also supplies Pixi's `Assets.add` a `format` hint - the original path's own extension
+  - whenever the resolved `src` is a compiled build's `data:` URI (item 308): a `data:` URI
+  carries no extension of its own for Pixi's resolver to pick a parser from, which otherwise
+  left a game no way to load a compiled asset without building its own `{src, parser}`
+  descriptor by hand.
+- `loadBinary`/`getBinary`/`isBinaryLoaded`/`releaseBinary` - the renderer-free counterpart
+  to `load`/`texture`/.../`release`, caching raw `ArrayBuffer`s instead of Pixi textures
+  (also its own entry point, `@datamoc/mw_games/assets/binary`); `3d/models`' `Vox.parseVox`
+  is the direct consumer, taking bytes this now fetches and caches instead of a game doing
+  it by hand.
+- `AssetStream`/`AssetBundle` - preloads likely-next bundles with LRU eviction under a
+  byte budget, for progressive loading between scenes.
+- `fetchWithByteProgress`/`ByteProgress`/`OnByteProgress` - real cumulative byte-progress
+  reporting, for a server or desktop host (not `file://`, which blocks `fetch` entirely).
+
+## `audio`
+
+- `Sound` - a pooled, round-robin one-shot sound effect player. `play(gain, pitch)` takes an
+  optional pitch as `HTMLAudioElement.playbackRate` (1 unchanged); there is no matching `pan` -
+  a plain `<audio>` element has no pan of its own, the same reason `Positional.audioPan` only
+  reports a number rather than owning a panner node. `suspend` cuts in-flight sounds and
+  silences `play` until `resume`.
+- `onCaption`/`CaptionEvent` - accessibility captions fired alongside a sound cue.
+- `Music` - crossfading background music. `suspend` pauses the current and fading tracks
+  and freezes `update` until `resume` restarts the current one where it paused. `duck`
+  glides to an attenuated level until `unduck`, for dialogue and menus.
+- `createAudio`/`Playable` - an injectable audio backend (tests supply a fake in place of `new Audio()`).
+- `Orchestrator`/`OrchestratorState` - maps a named game state ("combat", "boss") to a
+  `Music` track and crossfade, and fires one-shot cues by event name; re-entering the same
+  state never restarts its track. `suspend`/`resume` silence and restore the music and
+  every cue.
+- `AudioListener`/`SoundSource`/`AudioFalloff` - positional audio: a listener the game moves,
+  a `Sound` placed at a point, and `audioGain`/`audioPan` turning distance and heading into a
+  volume and a stereo position. `SoundSource.playFor` applies the distance gain through
+  `Sound.play`; panning is reported for a backend that has a panner. `Music` stays global.
+- `XpbdWorld` (`@datamoc/mw_games/physics/xpbd`) - a deterministic structure solver
+  (extended position-based dynamics): `addNode`/`addLink` (stiffness, `tensionOnly` cables, `strength`/
+  `tensionStrength`), `applyForce`, `step()` on fixed substeps, the load of every link read back
+  (`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.
+- `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
+  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
+  built on `synthesizeTone` rather than a licensed instrument library: program, bank,
+  controller and pitch-bend events plus the controller-111 loop start, with each
+  scheduled note carrying its channel voice. `MidiPlayer.create(file, { humanize })`
+  humanizes first and then schedules, for the same player with a performance behind it.
+- `renderMidiToBuffer` - renders a parsed `.mid` file to stereo PCM frames, offline and
+  deterministic: browsers cannot decode MIDI, so the file is synthesized once and plays
+  back like any decoded track, with its controller-111 loop region. An optional game-supplied
+  `SoundFont` voices real samples; without one the built-in waveform synth plays.
+- `renderMidiToBufferAsync` - the same render as raw MIDI bytes, run on a worker thread so
+  the seconds a real track costs (2 to 11.8) do not freeze the loading screen. Parse,
+  schedule and voice lookup stay on the caller's thread; the stereo buffers come back
+  transferred rather than copied, and the result is bit-identical to the synchronous
+  render because both call the same function. `soundFontBytes` takes raw SoundFont 2 data.
+- `parseSoundFont` - reads SoundFont 2 bytes into layered preset voices (key and velocity
+  ranges, tuning, loops, envelopes, pan, attenuation); the font file itself stays the
+  game's to ship and to license. A SoundFont 3 (Ogg Vorbis samples) is refused by name
+  rather than read as noise: `loadSoundFont` reads either kind.
+- `loadSoundFont` - reads a SoundFont 2 or 3 into layered preset voices: a plain font goes
+  straight to `parseSoundFont`, a SoundFont 3 is decoded first, through
+  `webAudioSampleDecoder()` in a browser unless `{ decode }` names another decoder. It
+  is what a game calls on the bytes it ships, whichever kind they are.
+- `decodeSoundFont` - a SoundFont 3 as plain SoundFont 2 bytes: every sample a preset reaches
+  goes through the decoder once (an unreachable one never does), and the loop points a
+  SoundFont 3 states relative to its sample become the absolute ones SoundFont 2 uses. A
+  SoundFont 2 comes back unchanged. The result feeds anything that takes SoundFont 2 bytes,
+  `renderMidiToBufferAsync` included.
+- `webAudioSampleDecoder`/`SoundFontSampleDecoder` - the decoder contract (Ogg bytes and the
+  sample's own rate in, mono 16-bit frames out, synchronous or not) and the browser
+  implementation of it over `decodeAudioData`: each sample decodes in a context created at its
+  own rate, so the browser never resamples it. A Node tool passes a decoder of its own.
+- `collectSoundFontUsage` - lists the (bank, program) pairs scheduled notes actually
+  request across MIDI files, drums as bank 128, for the compile step to keep.
+- `mergeSoundFonts` - joins several SoundFont 2 files (or several SoundFont 3 files, the
+  Ogg bytes copied untouched) into one, presets in the order given and the first font winning
+  a shared (bank, program), which is how single-instrument files (the per-program collection
+  `mwg-soundfonts fetch` reads) become the one file a game ships.
+- `subsetSoundFont` - writes a smaller valid SoundFont 2 (or 3) file carrying only the used
+  programs, zones and samples copied verbatim and indexes remapped, so a game ships
+  megabytes instead of tens of megabytes with identical voices. The build does this
+  on its own: `compileResources` (and so `emitPage` and `mwgPage`) embeds `.mid`,
+  `.sf2` and `.sf3` assets, and subsets every embedded SoundFont to the programs the embedded
+  MIDI files use. `soundFont: false` embeds the font whole, `soundFontUsage` names
+  the programs explicitly, and with no shipped MIDI the font embeds whole because
+  the usage is unknowable. The reference bank in `data/microgm-opt.sf2` (2.6 MB,
+  WTFPL, shipped in the npm package for a game to copy into its assets) drops to
+  tens of kilobytes per game this way. It is the default bank. A game that wants another
+  picks it from `data/soundfont-catalog.json` and fetches just its instruments with
+  `mwg-soundfonts` (see [tools.md](tools.md)). A SoundFont 3 stays compressed all the way to
+  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.
+- `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.
+- `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.
+- `humanizeMidi`/`HumanizerFactory`/`HumanizeRequest`/`MidiHumanizerEngine` - the entry point
+  for a performance that sounds played rather than played back. `humanizeMidi(file, options)`
+  resolves the tier from the request (a `GrooveTemplate` in it means the groove tier, anything
+  else the lite one) and returns a new file; `HumanizerFactory.create(tier)` is for holding one
+  engine across several files. The pass never mutates its input: `intensity: 0` reproduces the
+  file exactly, a `seed` reproduces a run, note durations and every tempo, program, controller
+  and meta event survive, events come back sorted by tick with ties in file order, and nothing
+  lands before tick 0 (a shift that would cross it stops there instead). `create('magenta')`
+  throws naming what is missing rather than loading: `@magenta/music` and a PerformanceRNN
+  checkpoint cannot be fetched from a `file://` build.
+- `LiteHumanizer`/`GrooveHumanizer`/`HumanizationOptions`/`HumanizeStyle`/`HumanizerTier` - the
+  two shipped engines and their options. Tier 1 moves timing and velocity by gaussian noise
+  over a seeded gradient drift, scaled by `intensity` and by `style` (jazz wide, classical
+  tight), and holds the kick and the lowest notes to a few milliseconds of their slot; tier 2
+  applies a template's per-slot offsets and velocities instead, converted through the file's
+  own tempo map when the template was recorded at another tempo (which says so through
+  `onWarn` rather than staying quiet), plus contextual rules - an accent on a local melody
+  peak, restraint on the beat. `initialize()` is idempotent on both.
+- `subdivisionCount`/`assertGrooveTemplate`/`GrooveTemplate`/`GridSubdivision`/`GrooveOffset` -
+  the units everything else is measured in: how many slots a bar of a signature holds at a
+  grid (`subdivisionCount([4, 4], '16n')` is 16, `[6, 8]` at `8n` is 6, and a grid that does
+  not tile the bar throws), and the validator for a template's invariants - dense offsets in
+  subdivision order, whole ticks, a power-of-two denominator, a velocity factor between 0 and
+  1 - run when one is built and when one is imported.
+- `GrooveExtractor` - a reusable template out of three kinds of evidence, each reduced to the
+  same thing: the median of each slot's deviations, so one flubbed note cannot drag it and a
+  slot nobody played stays on the grid. Mode A matches a played pass against a straight one,
+  note-on to nearest note-on of the same channel and pitch within half a slot; mode B projects
+  a single file onto its own implied grid, which is exactly the residual a quantization would
+  discard; mode C takes an `AudioBuffer`, detecting attacks by spectral flux (hand-rolled FFT,
+  no analysis dependency) and taking the tempo as an argument because timing means nothing
+  without one, with velocity left at the neutral 1 since a recording carries none.
+- `GrooveConverter` - a template to and from the two formats that can carry one. JSON is
+  exact; the MIDI encoding is one note per slot behind an anchor a subdivision ahead, with
+  velocity at 1/64 per unit of `velocityFactor`, so the writer enforces `|offset|` below the
+  slot and a factor of 1/64 to 127/64 instead of rounding past them, and the file gets its own
+  reader because the round trip needs the tempo, time-signature and name metas that `parseMidi`
+  deliberately drops. `GrooveFormat` also names `ableton-agr` and `reaper-groove`, both of
+  which throw saying they are not shipped rather than returning a file that resembles one.
+
+## `battle`
+
+The Pokémon-shaped half of the capability spec: species/stats/party/type-matrix/turn-order.
+No move, formula, or number belongs here - only the shape.
+
+- `Creature`/`Species` - wraps `actors.StatBlock`/`Progression`, not a separate stat system.
+- `TypeMatrix` - attack-type effectiveness lookup.
+- `Party` - a roster of creatures.
+- `battleOrder`/`Move`/`BattleAction` - one round's priority-then-speed turn order.
+- `checkEvolution`/`EvolutionRule` - level/condition-based species evolution.
+- `StatStages` - a bounded, symmetric stage ladder over a stat (±`max`), replacing rather
+  than stacking the modifier for a stat's current stage.
+- `chooseMove`/`chooseSwitch` - battle AI built on `TypeMatrix`.
+- `BattleHooks`/`BattleHook` - `core.HookRegistry` with battle's argument shape: a handler
+  receives the creature plus a shared mutable `context`, for passive effects, abilities and
+  turn-skipping statuses.
+- `Field`/`FieldCondition` - field-wide conditions: weather, terrain, screens; named,
+  optionally timed, ticked down by `advance(rounds)`.
+- `AttackPreview`/`AttackPreviewOptions`/`AttackFrame`/`PreviewCombatant` - the damage totals and
+  one-frame-per-strike timeline an attack dialog prints and animates, from damage the game's own
+  formula produced (`totalDamage`, chance-weighted `expectedDamage`, `hits` for a rolled outcome,
+  `sampleAt` on the animation clock). It computes no damage itself.
+- `AttackDialog`/`AttackDialogOptions`/`StrikeNumbers` - the dialog's whole renderer-free state: a
+  `UnitSelector` to choose the pair, the `AttackPreview` built from a game-supplied `damageFor`, and
+  the `update(dt)`/`finished` clock that drives the animation.
+- `UnitSelector`/`UnitSelectorOptions`/`SelectableUnit`/`SelectorStage` - the two-step attack
+  selector: enabled units on the selecting side as candidates, then the enemies `canTarget` allows
+  as targets; `back` undoes the attacker choice.
+- `Whiteboard`/`WhiteboardEntry` - planned turn orders with one plan per unit, `undo`/`redo` (a new
+  plan clears the redo stack) and `commit` handing the plans back.
+- `BattleStats`/`BattleStatCategory` (item 273) - a per-run breakdown by category (`recruits`,
+  `recalls`, `advances`, `kills`, `deaths`, `damageDealt`, `damageTaken`) and unit type, the shape
+  `core.PlayerStats`'s opaque `T` cannot give a game for free; `record` adds to one unit type's
+  count, `total`/`breakdown` read a category back summed or per type, and `toJSON` folds into a
+  `core.RunHistory` entry or `core.PlayerStats` total like any other run summary.
+
+## `board`
+
+Board/card/dice games and generic tactics - traditional public-domain rules, no formula
+borrowed from any licensed game.
+
+- **chess** (`chess.ts`): `startingChess`/`parseFen`/`positionKey`/`cloneChess`/`legalMoves`/
+  `applyMove`/`inCheck`/`gameResult`/`sq`/`squareName` - full rules: legality, check/mate/
+  stalemate, castling, en passant, promotion, FEN in both directions (positions keyed
+  without clocks).
+- **engine** (`Engine.ts`): `chessGame`/`chooseMove`/`search` - the chess rules adapter and
+  convenience wrapper over the shared `ai.alphaBetaSearch`, with material evaluation and
+  depth/node limits. `searchAsync` scores each root move on a worker thread and combines
+  the scores first-wins, so a depth-3 search stops dropping frames; inside the node
+  budget it chooses exactly the move `search` would. The minigame path keeps this small search and never pays for the tournament module below. `searchAsync` combines root-move scores first-wins.
+
+- **bitboards** (`bitboard.ts`): the same rules on twelve 64-bit boards
+  (`startingBitboard`, `bitboardFromChess`, `bitboardMoves`, `makeMove`/`unmakeMove`,
+  `perft`), the mutable board the tournament engine searches. `bitboardFromChess`
+  bridges from a `chess.ts` position; the differential tests keep both rule sets in
+  agreement.
+- **openings** (`openings.ts`): `probeBook` looks a position up in a compiled opening
+  book (ECO, name where a known line ends, UCI continuations), `parseUciMove` reads a
+  UCI move back. The book is a game-side artifact built by `tools/compile-openings`
+  from vendored CC0 tables, so no table ships with the framework.
+- **tourney** (`tourney.ts`): `searchTourney`/`searchTourneyAsync` over one
+  self-contained `tourneyThink` task, so the worker side cannot diverge from the
+  main-thread side: negamax alpha-beta with principal variation search, null-move
+  pruning, late-move reductions, iterative deepening with aspiration windows, a bounded
+  Zobrist transposition table, quiescence over captures and promotions, hash/MVV-LVA/
+  killer/history ordering, and classical material plus in-house piece-square evaluation.
+  Positions are plain bitboard data and structured-clone straight into workers.
+  `TourneyResult.rootScores` is populated by an async search with legal root moves and
+  scores from the mover's view, in root order, for near-best selection without a
+  second search. The
+  chess example plays its reply through `searchTourneyAsync`, with a thinking indicator,
+  a per-move time cap, side and depth choice, a promotion picker and an in-check
+  highlight.
+- **tablebase** (`tablebase.ts`): `probeTablebase`/`loadTablebaseEnding`/`tablebaseId`
+  plus the `huffEncode`/`huffDecode` codec - WDL outcomes with distance-to-mate for
+  pawnless white-extras-against-lone-king endings, fifty-move-adjudicated against an
+  explicit halfmove clock, generated and verified by `tools/build-tablebases` and
+  shipped compiled under `data/tablebases` (3-piece; 4-piece stays a tool run away,
+  full 4-piece tables are tens of megabytes each).
+- **classics** (`Classics.ts`): `BoardGrid`; checkers
+  (`startingCheckers`/`checkersMoves`/`applyCheckersMove`, forced multi-jump captures); go
+  (`startingGo`/`playGo`/`passGo`/`goResult`/`goScore`, ko and area scoring); backgammon
+  (`startingBackgammon`/`rollBackgammonDice`/`backgammonMoves`/`applyBackgammonMove`, bar
+  and bearing off); cards (`createDeck`/`shuffleDeck`/`deal`/`trickWinner`); solitaire
+  (`dealSolitaire`/`drawSolitaire`/`moveSolitaireTableau`/`moveSolitaireToFoundation`/
+  `solitaireWon`, seeded Klondike); dice (`rollDice`/`rollExpression`/`DiceCup`/`scoreDice`,
+  Yahtzee-shaped keep-and-reroll scoring).
+- **tactics** (`Tactics.ts`): `startingTactics`/`addTacticalUnit`/`canPlaceTacticalUnit`/
+  `tacticalMoves`/`moveTacticalUnit`/`setTacticalOverwatch`/`triggerTacticalOverwatch`/
+  `tacticalAttack`/`endTacticalTurn` - squad tactics: action points, cover, overwatch, and
+  zone of control baked into `tacticalMoves`/move cost.
+- `FactionFog`/`VisionCell` - fog of war as a per-faction union of every controlled unit's
+  own vision, with explored memory retained. `share` puts factions on one map, sight and memory
+  alike, which is Wesnoth's `share_vision`; nothing shares until asked. `sees` hands a side's sight
+  out as a predicate for anything that asks what it can see.
+- **army** (`Army.ts`): `startingArmy`/`recruit`/`recall`/`bankUnit`/`armyIncome`/
+  `applyUpkeep` - recruiting/recalling units against a currency total, per-turn income and
+  upkeep, no specific rate baked in.
+- **hex skirmish** (`HexSkirmish.ts`): `startingSkirmish`/`setSkirmishTerrain`/
+  `canPlaceSkirmishUnit`/`addSkirmishUnit`/`skirmishMoves`/`moveSkirmishUnit`/
+  `skirmishAttack`/`skirmishIncome`/`endSkirmishTurn` - a Wesnoth-style hex army-game rules
+  layer distinct from `tactics` above: per-terrain movement cost and defence, adjacency-only
+  attacks where a surviving defender always strikes back, capturable villages that grant
+  income and heal whoever owns them, no zone of control.
+- `BoardPiece` (type, from `Classics.ts`) - a generic owned/countable/capturable/promotable
+  token distinct from `roguelike`'s `Creature`-shaped actors; every game above builds on it.
+
+## `actors`
+
+Stat blocks, equipment, inventory, and the numbers layer nearly every other module builds
+on. This is the *shape* - a game names its own attributes and formulas.
+
+- `StatBlock`/`Modifier`/`DerivedStat` - base attributes plus derived stats, combined
+  through ordered modifiers (add → multiply → set). `toJSON` saves base values only:
+  modifiers are reapplied on load by whatever owns them (equipment, status effects, auras),
+  so saving them too would double every bonus.
+- `composeModifiers` - the same canonical modifier composition as `StatBlock`, available to
+  adapters that resolve declarative effect lists without creating a stat block.
+- `Progression`/`powerCurve` - levelling from experience against a growth curve; `toJSON`
+  saves level and experience, the curve being a definition.
+- `skillCheck` - value-plus-modifiers against a difficulty, one dice roll.
+- `SkillPoints` - a spendable ledger that raises a stat's base rank, with per-stat caps and
+  a rising cost per rank. `toJSON` saves only unspent points; the ranks bought are already
+  in the `StatBlock`'s own base values.
+- `EquipmentSlots`/`EquippableItem`/`SavedEquipment` - equip/unequip applies or removes an
+  item's modifiers immediately; an optional `locked` predicate refuses unequip/swap for
+  cursed/quest gear. `toJSON(identify)` records slot-to-id, and `fromJSON` re-equips so every
+  modifier lands back on the `StatBlock`; a locked item is restored still worn.
+- `Inventory`/`InventoryItem`/`ItemDefinition`/`SavedInventory` - stacking (by id, and by
+  `instanceId` when either item sets one), weight, capacity, containers holding their own
+  `Inventory`. `toJSON` saves per-item instance state (level, wear, affix, identified,
+  `instanceId`) while `fromJSON(defs, data)` takes kind-level fields from the game's item
+  table, so a rebalanced weight reaches an old save.
+- `craft`/`Recipe`/`Ingredient` - resolves a recipe against an `Inventory`: all-or-nothing, with a
+  capacity-rollback path if the result doesn't fit. An ingredient may match an exact `id` (or a
+  list of them), a `category` on the item's definition ("any herb"), or a `matches` predicate; the
+  allocation is made against a working copy so two flexible ingredients cannot count one stack
+  twice. `InventoryItem.category`/`ItemDefinition` carry the kind-level grouping (supplied by the
+  game on load, like `stackable` and `weight`).
+- `applyStatusEffect`/`EffectClock`/`StatusEffectHandle` - a `StatBlock` modifier tied to a
+  `TurnClock`'s automatic expiry; `cancel()` for early removal.
+- `identify`/`enchant`/`damageItem`/`repairItem` - identification; enchant/upgrade level
+  (`enchant`'s `affixPolicy: 'keep' | 'remove'` decides whether an upgrade strips an
+  affix); durability wear and repair, opt-in per item.
+- `applyItemStatusEffect` - a status effect sourced from an item rather than a spell.
+- `Charges`/`ChargesOptions` - a resource regenerating in banked-turn chunks via
+  `advance(turns)`; `refund()` restores charges directly (a kill or crit), outside that path.
+  `toJSON` saves the count *and* the progress banked towards the next, so reloading cannot
+  shorten a recharge.
+- `rollLoot`/`LootEntry`/`LootTable` - rolls whether anything drops, then weight-picks
+  which, the same "roll whether, then which" shape `world.rollEncounter` shares.
+- `Advancement` - level-gated tiers granting ledger points, with mutually-exclusive
+  branch/capstone choices.
+- `rollAffix`/`affixOf`/`applyAffix`/`removeAffix`/`copyAffix`/`matchesContext` - named
+  item affixes: weight-picked, applied/removed on `InventoryItem.affix`, copied between
+  item instances, and matched against a fired trigger's attack `kind` via `AffixDef.kinds`.
+- `scaledModifiers`/`LevelScale` - level-scaled gear: `{stat, op, base, perLevel}` resolved
+  to a plain `Modifier`.
+- `assignAppearances`/`Appearances` - per-run appearance shuffling for unidentified items,
+  seeded and fixed for the run.
+- `buy`/`sell`/`Price`/`ShopOptions` - a currency-`StatBlock` transaction against an
+  `Inventory`, all-or-nothing with rollback.
+- `canAfford`/`spend`/`refund`/`convertToCharges`/`ResourceCost` - a spendable `StatBlock`
+  pool (mana, stamina): check, all-or-nothing spend, mirror-image refund (optionally
+  fractional), or convert a spent amount into `Charges` at a rate.
+- `Barrier`/`BarrierLayer` - a layered shield/absorption pool; the most recently added
+  layer drains first, with optional independent per-layer decay ticked by `advance(turns)`.
+- `assignTraits`/`TraitDef`/`AssignedTrait` - per-instance random traits drawn from a
+  shared pool at creation, applied as permanent modifiers.
+- `AuraField`/`AuraDef`/`AuraParticipant` - continuously reapplies a carrier's modifiers to
+  whoever is currently adjacent, diffing rather than reapplying every tick.
+- `SupportLedger` - a pair-order-independent, thresholded bond/support relationship between
+  two units, growing through proximity or shared battles; `toJSON`/`fromJSON` round-trip it.
+- `buildEntity`/`buildEntities`/`EntityTemplateRow`/`EntityTemplateCatalog`/`BuiltEntity` - one
+  row of a hero or monster file (typically a `core.parseCSV` result) into a fully wired
+  entity: a `StatBlock` of base stats (every non-reserved column), an optional `Progression`
+  against a named growth curve, a starting item carrying a named starting affix, and a
+  `ReactionTable` already holding a low-HP rule if the row names a threshold. What each named
+  growth curve/affix/item actually is stays the game's own `EntityTemplateCatalog`.
+- `toEntitySaveState`/`fromEntitySaveState`/`EntitySaveState` - a `BuiltEntity`'s mutable state
+  (base stat values, level/experience, the carried item) in the same "definitions supplied
+  fresh on load" shape `StatBlock`/`Progression` already draw. `fromEntitySaveState` rebuilds
+  via `buildEntity` from the same row and catalog, then overlays the saved state on top.
+
+## `roguelike`
+
+FOV, pathfinding, the energy scheduler, level generation, and combat-adjacent primitives -
+the dungeon-crawl half of the capability spec.
+
+- `Level`/`WALL`/`FLOOR`/`rectCenter`/`rectsOverlap` - the tile grid: terrain kinds,
+  passability/transparency, square or hex `shape`.
+- `generateDungeon`/`findFreeCell`/`furthestRoom`/`DUNGEON_KINDS` - procedural dungeon
+  generation.
+- `generateDungeonGraph` - the same pipeline as `generateDungeon`, also returning the room
+  graph (corridor edges, backbone then extra loops) and a rejected-placement retry count;
+  `DungeonOptions.hooks` fires `onRoomPlaced`/`onCorridorCarved` as the pipeline runs, the
+  seam a regional generator hangs hand-placed rooms, branches, wells, plants, statues,
+  chasms, doors and traps from.
+- `generateCave` (item 407) - the cave counterpart: chambers grown as random blobs
+  (`jagged` the chance a growth step wanders), passages as biased random walks
+  (`windiness`, `width`, `chance`), starts on chamber centres with cleared rings,
+  `villageDensity` returning picked clear cells as data, and a forced join so a cave is
+  always connected whatever the rolls did. Seeded through the `Random` stack like the
+  dungeon.
+- `generateOverworld` (item 410) - a whole realm as plain tile data: seeded elevation and
+  moisture fields classify water, plains, forest, hills, mountains, desert and swamp behind
+  a `seaLevel` knob; rivers run downhill to the sea, merging when they meet, drowning a
+  lake at a ridge instead of crossing it; settlements place themselves by suitability
+  (buildable ground, water within reach, spaced apart) and join into a road tree that
+  prefers flat ground, water a ford rather than a wall; points of interest carry a
+  `leadsTo` id for `Overworld` locations, and every cell carries a coarse region id for
+  encounter tables. The realm invents itself from the seed: no reference game's map data.
+- `shape: 'hex'` on `generateDungeon`, `generateDungeonGraph`, `generateCave` and
+  `generateOverworld` lays the same generator out on a hex grid (odd-q offsets, the `Level`
+  convention): the dungeon and cave `Level` carry the hex shape, a dungeon corridor leg runs
+  as a hex line, a cave grows its chambers by hex distance and walks passages toward their
+  target in true on-screen distance, and the overworld samples its noise where each hex is
+  drawn and steps rivers and roads across the six edges. The default stays square, byte for
+  byte. `generateCave` also takes `random` (a `RandomSource`, such as a `Generator`) in place
+  of `seed`: it draws from, and advances, that stream, leaving the ambient `Random` stack
+  untouched.
+- `RoomBuilder`/`hallBuilder`/`eligibleBuilders`/`pickBuilder` - composable room interiors:
+  the generator places and joins rooms, a builder carves each one, picked by weight among
+  those whose size constraints fit. `DungeonOptions.builders` wires them in; a room no
+  builder fits falls back to a plain hall rather than staying solid rock.
+- `FeatureLayer` - a floor feature/event layer: named kinds with `inspect`/`interact`/
+  `consequence`/`persistent` rules attached to generated cells; definitions supplied fresh
+  on load, only cell-to-kind pairs are save data.
+- `rollRoster` - a variant-spawn/content-roll API: weighted regular entries, rare additions,
+  per-entry alternative swaps, and a shuffle, in that order; every roll (including an
+  explicitly disabled rare entry's non-roll) is traced for parity tests.
+- `candidateCells`/`cellsNear`/`selectDistinctCells` - deterministic content placement over a
+  `Level`: `candidateCells` filters by terrain kind, occupancy and an optional region;
+  `cellsNear` walks outward by radius for a cluster anchor; `selectDistinctCells` shuffles and
+  slices a de-duplicated pool, bounded to however many candidates exist rather than throwing.
+  Composes for neighbouring-item clusters, scattered decorations, and single room/branch
+  rewards; nothing is placed until the caller commits, and the returned trace is plain
+  JSON-safe data for `DungeonArtifacts.content` or a save file.
+- `compareDungeonArtifacts`/`checkDeterminism` - a dungeon parity/test harness: diffs a
+  seeded run's room graph, retries, terrain, features and content rolls against a reference
+  or golden fixture, tagging every mismatch `'graph'` or `'paint'`; `checkDeterminism` repeats
+  a generation call and confirms every run matches the first.
+- `FieldOfView`/`HeightSight` - shadowcast (square) or straight-line (hex) visibility, with
+  `Elevation`-aware asymmetric cliff sight.
+- `Elevation` - whole-level height per cell, read by `FieldOfView`/`Pathfinder`.
+- `Pathfinder`/`neighbourOffsets` - A*(square)/Dijkstra(hex or elevation-aware) pathing,
+  `distanceMap`/`descend`/`autoExplore`, an optional climb limit.
+- `Scheduler`/`Actor`/`SchedulerSnapshot` - energy-cost turn order, the sole authority on
+  logical time; fractional costs, `postpone` (delaying an actor other than the current one),
+  and `toJSON`/`restore` for a deterministic snapshot keyed by a caller-supplied actor id.
+- `decideMonsterAI`/`AIState`/`AIDecision`/`Disposition` - wander/hunt/flee built on
+  `FieldOfView`/`Pathfinder`/`Scheduler`; peaceful/neutral/hostile disposition, provoked
+  override.
+- `Secrets` - disguised terrain (secret doors, hidden traps) that passes every
+  passable/transparent check as its disguise until revealed.
+- `Doors` - open/closed/locked door state; locking is independent of open/closed.
+- `chebyshevDistance`/`traceLine`/`ballistica`/`hasLineOfSight`/`canTarget`/`resolveArea` -
+  targeting and collision paths: range/line-of-sight checks, configurable stopping cells,
+  and single/line/burst/cone area resolution.
+- `TargetingController` - the input-facing half of targeting: a cursor moved by keyboard
+  (`move`) or by a caller-resolved pointer cell (`moveTo`), range and line-of-sight
+  validation with an optional game `validate` hook, a `preview` of the shape's cells, and a
+  `confirm`/`cancel` result. It returns cells only; the game keeps legality details, damage
+  and drawing.
+- `coneCells`/`chainTargets`/`knockbackPath` - a widening cone spray, a greedy nearest-hop
+  chain, and a shove's path until the first impassable cell.
+- `coneSector`/`ConeSectorOptions` - a circular sector aimed at an angle: rays cast every 0.5
+  degrees across an arc of `degrees`, each clamped to `range` and stopped by the first wall, so a
+  wall shadows what is behind it while the rest of the cone reaches. Unlike `coneCells`, the aim
+  is not snapped to one of the eight directions.
+- `resolveAreaOnLevel`/`hexConeCells` - topology-aware area resolution and widening hex cones,
+  complementing the square-grid targeting helpers.
+- `rangeMultiplier`/`areaFalloffMultiplier`/`RangeBand` - a range-band damage multiplier
+  lookup, and a per-target falloff multiplier for an area effect hitting several targets.
+- `BossPhases`/`AbilityCycle` - an HP-fraction phase ladder whose `check(hpFraction)` reports
+  newly entered phases, and a named-cooldown ability rotation (`ready`/`use`/`advance`).
+- `CombatHooks`/`CombatEvent`/`DamageContext` - `core.HookRegistry` with combat's argument
+  shape (one mutable `DamageContext`), plus `modifyDamage`'s pre-damage seam.
+- `Stealth`/`StealthOptions` - sticky, one-way detection: `checkDetection` returns true
+  only on the call that first brings an observer within radius.
+- `TriggerTracker` - a streak counter (combo, kill-streak) that extends within a turn
+  window and restarts once the window lapses.
+- `MultiStageAbility`/`AbilityStage` - an ability that unfolds through named, turn-timed
+  stages (windup/active/recovery) once started.
+- `Minimap`/`minimapCellCenter` - exploration minimap rendering and overlay coordinates for
+  square and odd-q hex maps.
+- `MultiTurnBeam` - a deterministic one-front-per-turn beam. The default shape is a straight line;
+  `fronts` opts into a per-turn front resolver (cone, burst, fork, moving front), `blocker` is the
+  explicit terrain/`none`/custom policy with `isBlocked` as an extra game rule, `onCell` sees every
+  reached cell, and a save carries the shape name so a reload resumes the same one. Live target
+  lookup, game-owned damage application, cancellation and save/restore as before.
+- `BeamBlocker`/`BeamStep`/`MultiTurnBeamSave` - the blocker policy, one turn's reached cells and
+  damage, and the serialisable front list with its shape identity.
+
+## `rpg`
+
+Tiled map/event data, the map-event interpreter, switches/variables, and grid movement -
+the classic top-down RPG half.
+
+- `automap`/`AutomapRule`/`AutomapTarget`/`AUTOMAP_EMPTY` - Tiled-style automapping:
+  `input`/`output` pattern rules applied in order, each rule's matches collected before any
+  write. Takes any grid exposing `getTile`/`setTile` (a `TileMap` satisfies it structurally),
+  so automapping needs no renderer.
+- `GameState` - switches and variables.
+- `activePage`/`conditionHolds`/`EventPage`/`MapEvent` - last-matching-page resolution for
+  a map event, re-checked rather than cached.
+- `EventRunner`/`EventCommand`/`DialoguePresenter`/`DialogueRequest`/`EventChoice` - a
+  `StageScript`-shaped command interpreter for map events. Dialogue goes through an injected
+  `present` function rather than a widget, so the interpreter is renderer-free and a game can
+  drive it from a 3D scene, a DOM overlay, or a test asserting on script order.
+  `two-d/ui.messageBoxPresenter` is the ready-made 2D implementation. `DialogueRequest.portrait`
+  is an opaque, renderer-specific value (`Texture2D` for `messageBoxPresenter`), kept untyped
+  here so `rpg` stays renderer-free. `EventRunner.runStory`/`EventStoryScript` follow a named-
+  passage graph the same way `StageScript.runStory`/`StoryScript` do - a `goto` command, or a
+  choice's own `goto`, jumps to a different passage; a plain `run()` refuses a stray `goto`
+  rather than silently ignoring it, the same guard `StageScript.run` applies.
+  `EventRunnerOptions.onUnknownCommand` hears every command the runner has no handler for (and a
+  `goto` in a straight `run()`, which then ends the list instead of throwing), so a game converting
+  foreign event data can make every dropped command loud.
+- `importTwee`/`EventTwineStory` - imports Twee-notation Twine stories into `EventStoryScript`,
+  a thin wrapper around `core.parseTwee` (the same engine `two-d/stage.importTwee` wraps for
+  `StageCommand`/`StoryScript` instead) naming the `EventStoryScript` return type, so a
+  text-only RPG can import a branching Twee story without depending on `two-d` for anything.
+- `GridMover`/`Direction4` - tweened tile-to-tile movement plus a walk-cycle hook.
+  `GridMover.jumpBy` repositions instantly, with no tween or walk animation, for a move-route
+  "jump" step.
+- `MoveRouteRunner`/`MoveRoute`/`MoveRouteStep`/`MoveRouteOptions` - drives any `GridMover`
+  (the player's or an NPC's) through a scripted route over successive `update(dt)` calls:
+  fixed/random/toward/away directional steps, a turn-in-place step, a jump step, and a wait
+  step, with `repeat` and `skippable` policies. Whether a step is passable is asked through the
+  same `canMove` contract `GridMover` itself expects of its own caller.
+- `FreeMover` - continuous (non-grid) position and facing, for action-game movement.
+- `MovableSprite` - what both movers actually require: `x`/`y`, and optionally `update`/`has`/
+  `play`. A static sprite, a 3D mesh wrapper or a plain test record all satisfy it.
+- `aabbOverlap`/`circleOverlap`/`circleAabbOverlap`/`resolveAabbAgainstTiles` - 2D
+  collision: shape overlap tests, and an axis-separated sweep against solid tiles.
+- `QuestLog`/`QuestStage`/`QuestDefinition`/`QuestMarker` - quest stages advanced one at a
+  time by `advanceStage`, prerequisites, `markerFor` deriving `'offer'`/`'turnIn'`/`'none'`,
+  and a tracked-quest pointer/location.
+- `questsFromRows`/`QuestStageRow` - groups a flat table of stage rows (typically a
+  `core.parseCSV` result, one row per stage sharing a `questId`) into `QuestDefinition`s a
+  `QuestLog` can `define`.
+- `decodeMarshal`/`encodeMarshal`/`RubySymbol` - Ruby `Marshal` 4.8 binary serialization
+  (the container format RPG Maker's own `.rxdata` saves use).
+- `hashDefaultOf`/`withHashDefault` - reads and attaches a Ruby hash's default value, which
+  `Marshal` carries alongside the entries rather than as one of them.
+- `parseDialogueText`/`extractDialogueCatalog` - the terse `@id text`/`-`-alternation dialogue
+  format targeting `EventCommand`, a thin wrapper around `core.parseDialogueLines` (the same
+  engine `two-d/stage.parseDialogueText` wraps for `StageCommand` instead), so a text-only
+  RPG (`core` plus `rpg`, no renderer at all) can author dialogue without depending on
+  `two-d` for anything. `extractDialogueCatalog` builds an identity `i18n` catalog from the
+  result, the same shape MWL's own `extractCatalog` builds from `_("...")`-marked strings.
+
+## `simulation`
+
+`TrainingEnvironment` adapts game-owned `TrainingRules` around the existing
+`SimulationRule`, with no renderer, DOM, audio or animation loop. `reset(seed)`
+returns a `TrainingFrame` with per-agent observations, rewards, `terminated` and
+`truncated`. `step(actions)` takes one action index per agent (or `null` only for
+an all-masked idle agent), invokes the same rule used during play and returns the
+next frame. Rewards inspect a cloned pre-transition state, so mutable rules work.
+The agent roster stays fixed within an episode. `maxSteps` is required and capped
+at one million; reaching it truncates an unfinished episode, while rule completion
+terminates it. Real-time games advance fixed simulation ticks inside their rules;
+turn-based games advance turns. Neither waits for wall-clock time. A throwing
+rule can mutate its state, as with `runScenario`; reset or restore before continuing.
+
+`snapshot()`/`restore()` use `TrainingSnapshot`: versioned environment state, schema,
+step limit, completion flags, seed and RNG state. `TrainingCheckpoint<State, TrainerState>`
+combines that snapshot with the `NeuralModel` and game-owned optimizer/exploration
+state. Persist every random stream the trainer uses in `trainerState`. Train with
+the same observation schema and action ordering used by the playable game.
+
+`runRollouts(environment, model, RolloutOptions)` chooses actions from each new
+observation until completion. Options provide episode seeds, optional seeded
+softmax sampling and `trajectoryLimit` (first transitions per episode, zero by
+default). `RolloutEpisode` reports steps, cumulative per-agent rewards, completion
+flags and a bounded array of `TrainingTransition`s. No command journal or presentation
+events are retained. Batches accept at most 10000 episodes and 10000 stored transitions.
+
+`runRolloutsAsync(TrainingFactory, config, model, options)` shards episodes across
+workers (default four, configurable `jobs` in 1..64). Each worker keeps its model,
+environment and inference buffers for the whole shard. Results stay in seed order;
+`signal` and per-worker `timeout` terminate work, and any failure terminates sibling
+workers. The factory must be self-contained, like `threads.spawn`, accepting the
+supplied `TrainingEnvironment` constructor and structured-cloneable configuration;
+it cannot close over module imports. Both paths run the same classes and inference
+code, including in a compiled `file://` page. Training algorithms and rewards are
+game-owned; `tools/train-neural.ts` shows a seeded evolution optimizer, resumable
+checkpoint and model export, and `examples/neural` loads its trained weights.
+
+`imitationFromReplay(environment, { actions, events, seed })` turns a persisted run
+(roadmap 397) into imitation targets: it walks the recorded actions against the
+same seeded environment they were played on and returns the `(observation, action)`
+samples a game's own trainer fits, sourced from how its players played rather than a
+generated expert. One recorded event is one environment step; the environment must
+expose exactly one agent (the recorded player - anything else that moves is part of
+the rule, like the maze chase's ghosts); a recorded action outside the list is a
+named error, never a silently skipped event.
+
+`runSeededEpisode(environment, choose, { seed })` plays one whole run with the AI
+choosing, from a named seed: the same seed and the same deterministic `choose` make
+the same decisions, so runs compare across builds, policies and machines. Unlike
+`runRollouts` the chooser is not a `NeuralModel` - a heuristic, a `NeuralPolicy`'s
+argmax, or any named function works - and the result records every chosen action and
+the cumulative rewards, with the environment's `maxSteps` as the truncation bound.
+
+Headless, deterministic turn/scenario running - for testing and benchmarking without a
+live game loop.
+
+- `advanceToInput`/`ScheduledTurns`/`TurnRules`/`TurnResult` - drives turns forward under a
+  rule set until the next input is due.
+- `runScenario`/`Scenario`/`ScenarioResult` - a bounded, scripted simulation run against a
+  set of expectations.
+- `Campaign`/`CampaignLevel`/`CampaignLevelResult`/`CampaignSnapshot` - generic level order,
+  result, carry-over, reminder and transition state, with JSON-safe save/restore.
+- `runHeadlessScenario`/`HeadlessScenario`/`HeadlessScenarioResult` - seeded, renderer-free
+  scenario execution returning the final state, ordered events and resumable random state.
+- `SimulationRuntime`/`SimulationContext`/`SimulationOutcome`/`SimulationRuntimeRule`/
+  `SimulationSnapshot` - a facade over one state + one `roguelike.Scheduler` + one `core.
+  Generator`, for the interactive half of a turn-based simulation: `dispatch` runs a single
+  command through the game's rule, threading `random`/`scheduler` as context and charging any
+  returned cost; `snapshot`/`restore` capture and rebuild the whole triple. Commands, events and
+  (with `history`) state are journalled through `structuredClone`, so they must be plain data:
+  name an actor by id, never pass the live object. A `dispatch` that cannot copy them throws
+  with the offending path and commits nothing. Composes with
+  `advanceToInput` against the same scheduler for the automatic-actor loop, rather than
+  replacing it.
+- `EventPresentation`/`EventPresentationOptions` - the documented pattern tying a
+  `SimulationRuntime` to a `core.PresentationQueue`: `submit` commits a command and starts its
+  events, `locked` is the animation lock `submit` refuses under, `followUp` schedules a
+  secondary actor's commands for after the current batch, `cancel` drops the rest of the show
+  without rolling the committed turn back, and `snapshot`/`restore` deliberately leave the
+  queue out of a save so a load resumes idle.
+- `Scheduler`/`Actor`/`SchedulerSnapshot` - re-exported here from `roguelike` (its real home),
+  since every `SimulationRuntime` needs one; a simulation-first game need not import a second
+  module just to construct the class its own runtime is built around.
+- `CampaignSave`/`CampaignSaveState`/`CampaignSaveParts` - one `core.SaveSystem` slot for a whole
+  campaign: `save` captures the `Campaign` snapshot, the game's own world payload and the
+  `SimulationRuntime` snapshot together, `load` reads them back migrated, and `list`/`delete` are
+  `SaveSystem`'s. The world is opaque, so an `MwlWorld`, a `Level` or a game's own scenario object
+  all fit.
+
+## `skeleton`
+
+Skeletal pose math, renderer-free: a bone tree, keyframed clips and layered blending, as
+pure data and arithmetic so it loads headless and tests without a renderer. Clips are plain
+JSON-shaped data a game authors itself. `import * as Skeleton from '@datamoc/mw_games/skeleton'`.
+
+- `create(bones)` - builds a `SkeletonBones` from `Bone`s (`name`, `parent`, `length`,
+  `origin`, `rest` `rotation` in degrees, optional `limits`), throwing by name on a duplicate
+  bone, a cycle, a missing parent or inverted joint limits. `boneOrder` lists names parents
+  first.
+- `resolve(skeleton, pose?)` - walks the tree and returns one `BoneTransform` per bone (world
+  `x`/`y`, `angle`, composed scale, a 2D `matrix`, and the `tipX`/`tipY` the children start
+  from). A `Pose` is one rotation per bone name; a `TransformPose` adds per-bone translations
+  and scales.
+- `samplePose`/`sampleTransformPose(clip, time, skeleton?)` - a `Clip` (`duration`, `loop`,
+  ascending `Keyframe`s) interpolated at a time: a looping clip wraps, a one-shot holds its
+  last frame. Passing the skeleton validates the result.
+- `advancePlayback`/`createMixer`/`crossfadeTo`/`advance`/`advancePose` - a `Mixer` holds a base
+  `Playback` plus weighted, prioritised additive `Layer`s. `advance(mixer, dt)` ticks every
+  playhead, folds in a running crossfade and the layers, and returns rotations;
+  `advancePose` returns the full `TransformPose`. `mixPoses` blends rotation poses by layer
+  priority and weight.
+- `validatePose` - refuses non-finite rotations and angles outside a bone's `limits`.
+- `solveTwoBoneIK(skeleton, first, second, target, bend?, pose?)` - solves a connected
+  two-bone chain toward a world target without stretching; throws for an unreachable target
+  or a second bone with a non-zero origin.
+
+## `physics`
+
+Small deterministic simulations, renderer-free, with no third-party engine. Three entry
+points: `@datamoc/mw_games/physics` (rigid bodies, cloth, spring) and
+`@datamoc/mw_games/physics/xpbd` (a structure solver). Everything is plain arithmetic, so a
+game's headless tests run the same world.
+
+- `PhysicsWorld` - rigid circles and axis-aligned boxes (never rotating: `angle` is a display
+  offset), stepped on a `FixedStepper` so results do not depend on the display refresh rate.
+  Semi-implicit Euler, impulse contacts with restitution and friction, and distance joints.
+  `addBox`/`addCircle` return a plain `PhysicsBody` (`position`, `velocity`, `angle`, `label`,
+  `isStatic`); `connect` joins two bodies or a body and a world point
+  (`ConstraintOptions`: `stiffness`, `damping`, `length`, attachment points, and `maxStretch`
+  to make the joint breakable); `remove` takes a body or constraint; `stretchOf` reads a
+  joint's strain; `update(dt)` runs the fixed steps it covers and returns their count.
+  `onContact` and `onBreak` are `Signal`s.
+- `XpbdWorld` (`physics/xpbd`) - point masses (`addNode`, `fixed` anchors) joined by springs
+  (`addLink`: `stiffness`, `rest`, `tensionOnly` cables, `strength`/`tensionStrength`),
+  solved with extended position-based dynamics and the force in each link read back, so a link
+  breaks at a real load. Fixed steps and no randomness make a replay identical on every
+  machine. `step()` advances one frame; `applyForce` pushes a node for one step; `ground` is a
+  height or a function of x; `breaking` gates breaking so a structure can settle first;
+  `onBreak` fires per broken link and `peakRatio` is a strain gauge. It has no rigid bodies or
+  collisions, which is what `PhysicsWorld` is for.
+- `Cloth` - a pinned-point Verlet grid (top row pinned) with structural links only, no
+  allocation per step. `indexOf`/`pointPosition`/`pointLinks`/`writePositions` read it back;
+  `pinPoint`/`unpinPoint`, `setWind`/`setGravity`, `reset` and `update(dt)` drive it.
+  `two-d`'s `ClothSprite` draws one as a mesh on the GPU path.
+- `Spring` - a damped chase spring for secondary motion (hair, hems, panels): `setAnchor`
+  moves the target, `displace` shoves the bob, `offset`/`length`/`settled(tolerance)` read the
+  lag, `place(target)` positions a display object, `update(dt)` steps it. Under reduced motion
+  it follows `SpringOptions.intent` (`decorative` snaps to the anchor).
+
+## `testing`
+
+Test doubles for the seams mwg takes by injection (item 388), so a game's tests and this
+repository's own share one copy of each. Renderer-free, dependency-free, and off the root barrel:
+nothing here reaches a shipped game unless a test imports it.
+- `createSceneControls` (item 408) - named steps a game opts into (`enterScenario`,
+  `finishTurn`, `advanceDialogue` in the Wesnoth port), driven by name from a test or a
+  headless Chrome: the game decides what a step does, the controls only promise that a
+  registered name runs and an unknown one is refused by name.
+- `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.
+- `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.
+- `FakeSocket` - a `WebSocketLike` for `LockstepClient`'s `create`: `sent`, `receive(message)`,
+  `receiveRaw(text)`, `close()`.
+- `fakeFetch`/`FakeFetchCall` - a `fetch` for every `HttpTransport` client, answering with a
+  `Response` or a value sent as JSON, recording each call.
+- `fakeGamepad` - a `Gamepad` from button values (pressed above 0.5) and axes, for `Input` and
+  `PlayerInput`.
+
+## `threads`
+
+Runs a self-contained function on a worker thread, so a blocking computation costs a
+background thread instead of a dropped frame. mwg's own runtime rather than a dependency:
+a classic blob worker in the browser, because that is the one shape a double-clicked
+`file://` page accepts (the shipped CSP allows `worker-src blob:` and `new Function`, and
+a module worker loaded from `file://` fails CORS whatever the policy says), and
+`node:worker_threads` in Node. Off the root barrel like `testing`: a game that never
+spawns a worker pays nothing for it, and imports `@datamoc/mw_games/threads` when it
+wants one.
+
+- `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
+  needs arrives as `args`, structured-cloned in. `options.transfer` moves listed buffers
+  instead, detaching them from the caller's thread. The result returns structured-cloned
+  with every `ArrayBuffer` inside it transferred rather than copied, since the worker is
+  finished with them. A task that throws, closes over something the worker cannot see, or
+  kills its worker without answering rejects the promise instead of hanging it;
+  `options.timeout` abandons a task that never returns, and `options.signal` (an
+  `AbortSignal`) cancels one on demand. One worker per task, terminated the moment it
+  settles. In Node an unsettled task keeps the process alive, so settle or cancel every
+  task before exit.
+
+## `headless`
+
+The blessed renderer-free entry: every module that loads in bare Node, in one import,
+with no DOM or WebGL globals. A rule imported through here is headless by construction;
+anything outside it belongs in presentation, not in the rule.
+
+- `core`/`simulation`/`mwl` - scenes, saves, RNG, headless scenarios and content tables.
+- `i18n`/`actors`/`world`/`battle` - messages, stats, maps, encounters and type matchups.
+- `roguelike`/`board`/`audio`/`rpg` - dungeon generation, board rules, sound/music
+  primitives (inject `create`, as under plain `audio`) and map events.
+- `ai`/`testing` - decision runners and the shared test doubles.
+- `assetPaths`/`assetBinary` - the two renderer-free asset halves (path resolution and
+  byte caching) beside the Pixi-backed `assets` loader.
+
+Excluded with reasons in `src/headless/index.ts`: `three-d` (needs Babylon at import),
+the Lua runtimes (`mwl/pyroeis`, `ai/lua`), and every `two-d/*` module.
+
+## `three-d` (optional)
+
+Babylon.js-backed 3D, kept fully separate from the 2D default - nothing in `core` imports
+this module.
+
+- `Engine3D` - owns Babylon's engine, scene, orbit camera, light, resize, and render loop.
+- `gridPoint3D`/`GridCell3D`/`GridShape3D` - square/hex 3D grid cell projection.
+- `createTileGrid3D` - a thin-instanced 3D tile floor (square or hex) with elevation
+  columns for nonzero cell heights.
+- `Character3D` - moves an imported mesh or a camera-facing billboard sprite through
+  continuous world coordinates; `playAnimation` plays a clip an imported model carries.
+- `parseVox`/`createVoxModel3D` - MagicaVoxel `.vox` import, batched by colour.
+- `loadModel3D`/`loadModelContainer3D`/`isModelContainerLoaded`/`releaseModelContainer`
+  (`@datamoc/mw_games/3d/models`, kept out of the main `3d` barrel so a scene that never
+  imports a model pays nothing for the loader) - glTF/GLB import. `loadModel3D` imports
+  straight into the scene, for one copy; `loadModelContainer3D` fetches and parses a source
+  once, caches the `AssetContainer`, and a game calls `instantiateModelsToScene()` on it for
+  each independent, unaliased copy it wants placed - Babylon's own answer to "load once,
+  place many" without a second network fetch.
+- `createHeightmapTerrain3D` - a continuous displaced-mesh terrain from a greyscale
+  heightmap image, alongside `createTileGrid3D`'s stepped floors.
+- `buildHeightIndex`/`cellAt`/`heightAt`/`resolveCapsuleAgainstGrid` - horizontal collision
+  for a moving capsule against `createTileGrid3D`'s stepped grid.
+
+## `world`
+
+Many maps, transitions, persistence, the turn clock, encounter tables - the connective
+tissue between scenes.
+
+- `World` - many maps, each created once and kept alive (or rebuilt fresh per entry when
+  defined `persistent: false`); `unload` frees a map's own state.
+- `Overworld`/`Location` - named-location lookup.
+- `TurnClock`/`TimedEffect` - hunger/poison-style timed effects, ticked on `advance`.
+- `rollEncounter`/`EncounterTable` - rolls whether an encounter fires, then weight-picks
+  which.
+- `EnvironmentClock`/`DayPhase`/`EnvironmentSnapshot` - a continuous day/night-phase and
+  weather clock above any one encounter, driven by `update(dt)` in real seconds, with change
+  notifications and `toJSON`/`fromJSON`.
+- `SideTurns`/`SideTurn`/`TimeOfDay`/`TimeArea`/`Alignment`/`alignmentBonus` - the reference
+  strategy game's outer turn model: sides take turns in order, a round is all of them, and the
+  time-of-day schedule steps on per round. `lawfulBonusAt` applies a unit's alignment to the
+  current time's `lawfulBonus`, and a `TimeArea` overrides the schedule for part of the map,
+  which is what makes the bonus per-hex. `toJSON`/`fromJSON` resume the exact position.
+
+## `i18n`
+
+Message tables, plurals, interpolation, and direction - pure logic, no Pixi dependency.
+
+- `Direction`/`Catalog`/`MessageValue` - the message-table shape: locale, direction,
+  messages, an optional Fluent-parsed or plain-string/plural-form value.
+- `setBase`/`setActive`/`locale`/`direction` - the active and fallback language, and the
+  direction `ui`'s `Theme.direction` reads from; `reset` clears both back to unset.
+- `t`/`tRaw`/`formatSpec`/`tokenizeMessage`/`diffPlaceholders`/`MessageParams` - resolves a key, selecting a plural form via `Intl.PluralRules` and
+  interpolating `{token}`s, including dotted paths that walk into nested params
+  (`{side.stored.hitpoints}` against `{ side: { stored: { hitpoints: 12 } } }`); falls back to the
+  base language, then to the raw key. Placeholders
+  also take Python f-string-style specs (`{dmg:03d}`, `{hp:.1%}`, `{name:>12}`), `!s`/`!r`/`!a`
+  conversions and `=` debugging, resolved through `formatSpec` (verified case by case against
+  CPython; an ill-fitting spec stays untouched rather than throwing). `tokenizeMessage` is
+  the single definition of that placeholder grammar, shared by interpolation and by
+  `diffPlaceholders`, which compares a reference string against its translation (dropped,
+  added, or reshaped tokens) for `tools/i18n-edit` to surface. `tRaw`
+  skips the display-text decoration (typographic spacing, RTL wrapping) for catalog values
+  that are not shown to the player, such as a sound path.
+- `parseSoundMarkers`/`stripSoundMarkers`/`InlineSoundCue`/`ParsedSoundText` - extracts
+  `{sound:path}` markers from translated text, returning marker-free display text and each
+  cue's visible-character offset. `MessageBox` consumes these markers during its reveal;
+  `t()` and `tRaw()` preserve them for the presentation layer.
+- `typographic` - locale-aware curly-apostrophe substitution (French/Italian/Dutch elisions);
+  for French, also a narrow no-break space before `; ! ? :` and around `« »`, and a plain
+  no-break space between a numbering word and its number ("Chapitre 3"); for German, a
+  no-break space between a number and its unit ("5 kg") and after a small set of
+  abbreviations ("Nr. 3", "Dr. Müller").
+- `nonBreakingUnit` - joins a value and a game-defined unit ("pièces d'or", "points de vie")
+  with whichever no-break space French/German typography calls for; the unit's own text is
+  always the game's vocabulary, never MWG's.
+- `has` - whether a key resolves to something real, in either language.
+- `parseFTL`/`FluentOptions` - parses Project Fluent `.ftl` message resources into the same
+  `Catalog`/`t()` surface, with variables, exact and plural variants.
+- `parsePo`/`PoOptions` - parses a gettext `.po` file into the same `Catalog`/`t()` surface:
+  `msgid`/`msgstr`, `msgctxt`, `msgid_plural` with `msgstr[N]` mapped onto the locale's CLDR
+  categories, the header entry dropped, untranslated entries left out for base fallback - which
+  includes a `#, fuzzy` one, the way gettext's own tools treat it - and a non-default gettext
+  `domain` prefixing keys.
+- `SemanticMessage`/`MessageChannel`/`MessageFormatter`/`createCatalogFormatter` - a typed
+  `{ type, params }` communication intent rendered differently per channel (log/compact/
+  accessibility/debug/audio) from the same underlying catalog: `createCatalogFormatter` looks up
+  `${type}.${channel}`, falling back to `${type}` alone, then formats through `t()`. A
+  simulation emits the message once; the channel is a presentation choice, not a rule. The
+  `audio` channel holds a sound path (played game-side through `audio`'s `Sound`), resolves
+  through `tRaw` rather than `t()`, returns `''` when no `<type>.audio` entry exists, and
+  never falls back to a bare type holding a sentence.
+- `EntityTextResolver`/`GrammaticalEntity` - type contracts a game uses while building a
+  `SemanticMessage`'s params (resolving an id to display text, or carrying gender/number/
+  proper-noun metadata for its own catalog's grammar); MWG never calls or interprets either.
+- `formatNumber`/`formatDate`/`formatList` - locale-aware `Intl.NumberFormat`/
+  `DateTimeFormat`/`ListFormat` wrappers reading the active locale from `locale()`, for a
+  message that needs more than `{token}` substitution - a game calls these while building a
+  `t()`/`SemanticMessage` param, the same way it resolves an entity id to display text.
+- `diffCatalogKeys`/`validateCatalog`/`CatalogKeyDiff`/`CatalogIssue` - catalog consistency
+  checks: `diffCatalogKeys` compares two catalogs' key sets (a base language against a
+  translation); `validateCatalog` flags empty messages and plural forms missing their
+  `other` branch within one catalog. Deliberately not a parameter schema validator - a
+  `SemanticMessage<TType, TParams>`'s own generics already give a game compile-time
+  parameter safety, which is the primary mechanism the source document calls for.
+- `validateMessageAudio`/`AudioIssue` - structural checks over `<type>.audio` sound-cue
+  entries: empty paths and non-string (plural/select) values, which would reduce silently
+  at lookup time rather than selecting per play.
+- `EditSession`/`EditRow`/`RowFilter`/`AUDIO_SUFFIX`/`createEditSession`/`sessionKeys`/
+  `sessionRow`/`sessionRows`/`setTargetText`/`copyFromBase`/`deleteTargetKey`/
+  `setTargetSound`/`cueKeyFor`/`sessionCompleteness`/`swapSession`/`isAudioKey` - the pure
+  session core behind `tools/i18n-edit`: translatable rows with reference/target text and
+  an effective cue (a channel key shares its semantic family's `<type>.audio`, one cue per
+  family), completeness ignoring cue keys, and swapping which catalog is the reference.
+  `tools/i18n-edit.mjs` is the terminal split-screen editor over it, with a `--check`
+  mode for CI.
+- `messageText`/`levenshteinDistance`/`findSimilarMessages` - content-management over a
+  catalog's actual message text rather than only its key shape: `messageText` reduces any
+  `MessageValue` to plain comparable text, `levenshteinDistance` is the classic edit-distance
+  primitive, and `findSimilarMessages` surfaces near-duplicate messages worth merging by
+  similarity threshold, most-similar first.
+- `catalogUsage`/`catalogCompleteness`/`pluralFormCoverage` - catalog statistics:
+  `catalogUsage` compares a catalog's keys against a caller-supplied referenced-keys list
+  (mwg has no view into a game's own source) for used/unused counts; `catalogCompleteness`
+  is a 0-1 translated fraction built on `diffCatalogKeys`; `pluralFormCoverage` tallies which
+  CLDR plural categories a catalog's plural-form messages actually define.
+- `mergeCatalogKeys` - drops a merged key from one catalog, keeping the surviving key's text
+  untouched; rewriting call sites that used the merged key stays the caller's own job, the
+  same boundary `catalogUsage`'s `referencedKeys` already draws.
+
+## `mwl`
+
+MWL is the build-time, game-neutral content layer. It uses a WML-inspired syntax for data
+such as units, items, maps, events, AI hooks, translations, and asset references. The runtime
+consumes generated data and does not parse `.mwl` source files in the browser.
+
+- `mwl build` - reads one file or a directory of `.mwl` files in stable path order and emits
+  `game-data.ts`, `i18n.json`, and `assets.json` in one step.
+- `mwl build --asset-root public/assets` - optionally verifies every extracted asset before
+  emitting the generated files. Missing paths include their MWL source location; without this
+  flag the build stays portable for games that resolve assets elsewhere.
+- `contentReport` / `loadContent` / `mwl report` - counts tags, lists opaque names, reports
+  resources, dependencies and unresolved references, and returns structured load diagnostics
+  for parity checks and CI.
+- `validateCatalog`/`validateCatalogNodes`/`MwlValidationOptions` - semantic checks shared by
+  every game: `MWL_DUPLICATE_ID`, `MWL_UNKNOWN_SLOT`, `MWL_INCOMPLETE_EFFECT`,
+  `MWL_INVALID_HOOK`/`MWL_UNKNOWN_HOOK`. `MWL_DUPLICATE_ID`'s `tag:id` key is scoped by
+  `rowIdScope` (item 304): `'global'` (the default) checks the whole compiled catalog, every
+  source file combined; `'file'` folds each node's own source file into the key too, for a game
+  whose id convention is meaningful only within one file and reuses ids across files on purpose
+  - a real duplicate within one file still reports.
+- `[campaign]` - declares game-owned campaign metadata (`id`, optional `name`, `title`,
+  `description`, and `start_scene`). Its children are intentionally open so a game can define
+  scenario and progression tags without changing the core MWL schema; metadata is exposed by
+  `contentCatalog(game).campaigns`.
+- `campaignChain` - points a `[campaign]` at `simulation.Campaign`: `first_scenario` opens the chain,
+  each `[scenario]`'s `next_scenario` is where it goes when it is won, and a scenario that ends the
+  chain ends the campaign. The order is content, the playing stays the game's (`run` is a callback),
+  and a scenario that decides for itself - a runtime `[endlevel]` - keeps its decision. The
+  `[campaign]` schema reads `first_scenario`, and the catalog exposes each campaign's `scenarios`.
+- `endLevelCarryover`/`carryoverIntoScenario`/`MWL_DEFAULT_CARRYOVER_PERCENTAGE` with `[endlevel]` -
+  a scenario's end as the reference models it: a share of the side's gold (80% by default), a bonus
+  on top, that side's surviving units as the recall list, and the next scenario. `result=victory`
+  ends it won, `result=defeat` lost, and the arithmetic is the same for both.
+- One side identity (item 277): the `id` a `[side]` declares (now a `string`, so a named side like
+  `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.
+- `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
+  value start for each attribute, and schema diagnostics use those locations when available.
+- `MwlValidationOptions.mapBounds` - an adapter can supply map dimensions so `validateCatalog`
+  rejects out-of-bounds integer, list, and range coordinates without embedding a map system in MWG.
+- `readTableMap` / `readTableIndex` / `tableKey` - project typed table rows into a `Map`, use
+  collision-free native composite keys, and build inverse indexes that retain every matching row.
+- A `key="""..."""` value (item 317) is the one attribute form that may span lines, and its text
+  is exactly what sits between the delimiters, so wrapped message, objective and option-label
+  text survives a conversion without the whitespace-collapsing workaround it otherwise needs. It
+  carries the `_` gettext marker like any other value; `text="""done"""` is the same form on one
+  line. (A line starting with `#` is still a comment wherever it appears, so a block cannot
+  carry one at the start of a line.)
+- MWL tables use `[table] columns=name:type|...` with typed `[row]` attributes. The compiler
+  validates column shape and values, and `contentCatalog(game).tables` exposes typed rows.
+  Supported column types match `core.parseCSV`: `string`, `number`, `boolean`, `list`, and
+  `map`, with configurable list and map delimiters. `typedRows`/`MwlTypedRow`/
+  `MwlColumnValueType` read rows through the declared columns (every field optional, an
+  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.
+- `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
+  once for all tables, reporting `MWL_TABLE_REFERENCE` with the table, the row, and the
+  offending value. The declarations' contents stay game data; absent or empty cells are
+  skipped and a `list` cell checks each entry under the table's own delimiter.
+- `composeEffects` - resolves MWL effects through `actors.composeModifiers`, so declarative
+  item effects and actor stats use one composition rule.
+- `evaluateCondition` - evaluates bounded content conditions with comparisons, `and`/`or`/`not`,
+  arithmetic, literals, `where` bindings, and explicitly supplied pure helpers. There are no loops, assignments,
+  dynamic code loading, or implicit game rules.
+- `mwl validate` - checks syntax and content structure without generating runtime files.
+- `mwl diagnostics` / `mwl ci` - emit stable JSON diagnostics, with `ci` additionally exposing
+  a boolean `valid` result and returning a failing process status when errors exist.
+- `mwl format` / `mwl migrate --to 1.0` - expand and emit a deterministic canonical MWL document;
+  migration requires an explicit target and currently normalizes the MWL 1.0 syntax surface.
+- `mwl compile`/`mwl extract-i18n`/`mwl hooks` - lower-level commands for a generated module,
+  translation extraction, or hook manifest when a build pipeline needs separate outputs.
+- `parse`/`compile`/`validate`/`extractI18n` - the programmatic compiler surface exported from
+  `@datamoc/mw_games/mwl`; games provide their own hook implementations and interpret
+  game-specific effects.
+- The `[side]` surface Wesnoth's own data writes, and the one key of it with behaviour here (item
+  252): `team_name`, `user_team_name`, `share_vision`, `village_gold`, `heal`, `fog`, `shroud`,
+  `hidden` and `flag` are read onto `MwlWorld.sides` as written, `yes`/`no` becoming booleans.
+  `sideVisionGroups` turns `team_name` and `share_vision` into the groups `FactionFog.share` takes,
+  so a scenario's teams see together without every game re-deriving who shares with whom.
+  `leader=` names either a `[unit]` id already declared (that unit is the side's leader; nothing
+  is spawned) or a unit type (one leader per free start cell, with that type's stats); a value
+  that is neither is refused by name (item 405).
+- A `[side]`'s own `[victory]`/`[defeat]` children (item 283): a side condition that names no
+  `side`/`side_filter` reads as that side's own, its result lands in `MwlWorld.sideStatus` keyed by
+  the side id, and the aggregate `MwlWorld.status` ends the scenario as a scenario-wide condition
+  would (a side victory outranking another side's defeat when both fire at once). `[win]`/`[lose]`
+  record the side they name too.
+- Public MWL exports - `MwlRuntime`, `MwlSyntaxError`, `collectHookReferences`, `compileNodes`,
+  `compileSources`, `compileAndEmitSources`, `emitArtifacts`, `coerceTableValue`, `decodeSaveEnvelope`,
+  `parseTableColumns`, `contentCatalog`, `createWorld`, `decodeSave`, `effectToModifier`,
+  `emitHooksDeclaration`, `emitModule`, `emitTableTypes`, `encodeSave`, `evaluateExpression`,
+  `execute`,
+  `extractCatalog`, `hookTypes`, `inventoryItem`, `isGettext`, `isMwlId`, `itemDefinition`,
+  `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
+  is split off and kept, and the comma-separated rows go through the same `parseTerrain` an inline
+  `[map] terrain=` uses, overlays (`Gg^Vh`) and `<side> <code>` starts included. Header keys are
+  not interpreted here, the same way `[terrain_graphics]` rules stay content's business.
+- `MwlHookDeclaration`/`validateHookAttributes` (item 321) - a hook may declare the attributes its
+  own `[hook]` calls carry (`attributes`, typed the way a tag schema types its own, or
+  `openAttributes`), and `validateCatalog`'s `hooks` option takes it in place of a bare
+  `type:name` id, so a typo in one of a command hook's eighteen modes is a compile-time
+  `MWL_VALUE` rather than a throw mid-scenario. The declaration is the hook's, not the tag's:
+  only `[hook]` calls are checked, where every attribute but `name` belongs to the hook. The
+  rule itself is `validAttributeValue`/`attributeTypeDescription`, exported because the tag
+  schema and a hook declaration check values the same way rather than two ways that drift.
+- `MwlDomainHook`/`MwlDomainHookRegistry` - game-declared hook namespaces such as
+  `item-effect:potion-strength` use a typed context/input/output boundary. MWG validates and
+  emits the reference shape, while the game owns the domain types, rules, and implementation.
+- `HookWorld`/`Emit` (item 319) - the hook boundary's two halves. `world.variableAt(path)`
+  resolves a nested variable through the same walker `[variable] name=` reads through, and
+  `emit.setVariable(path, value)` is its write, so a hook asks for `stored_naga.hitpoints` and
+  means the same variable content does; writing `world.variables` directly gets a flat dotted
+  key no reader finds.
+- `HookWorld.random`/`MwlRuntimeOptions.random` - a hook draws from the runtime's own seeded
+  `core.Generator` instead of `Math.random()`, so a `generator`/`ai`/domain hook stays reproducible;
+  the draw position is carried on `MwlWorld.random` and resumes exactly across save/restore.
+- `MwlTraceEvent`/`MwlRuntimeOptions.onTrace` - opt-in lifecycle tracing for event claims,
+  completions, variable writes and runtime errors. `MwlHookRegistry.predicate` lets an adapter
+  register named, typed filter predicates without putting game-specific semantics in MWG.
+- `MwlSaveableHookState` / `MwlHookRegistry.saveable` - a game may explicitly expose JSON-safe
+  hook state; `MwlRuntime.save()` includes it and `restore()` hands it back to the same adapter.
+- `MwlRuntime.journal` / `MwlRuntimeAction` - public runtime triggers and their trace batches are
+  recorded in order and persisted with the save, providing a replay and diagnostics input without
+  making MWG interpret game-specific commands.
+- `validateCatalog` also reports `MWL_ALIAS_CYCLE` for cycles among resolved `aliasof` references;
+  aliases outside the catalog remain available for game-defined sentinel values.
+- `validateSimulationReplay` - replays a `SimulationRuntime` journal from a checkpoint, compares
+  each deterministic event batch, and optionally verifies the final state with a stable checksum.
+- `SimulationRuntime` accepts an optional `history: { actorOf, limit? }`; `canUndo`, `canRedo`,
+  `undo()` and `redo()` restore complete state, scheduler, RNG and journal checkpoints.
+- `CanonicalState` / `CanonicalStateSnapshot` - a defensive, JSON-safe root state combined with
+  `StateRegistry` extensions; snapshots, version migrations, transactions and restores cover all
+  pieces atomically.
+- `LockstepClient` supports optional command validation, receives a session seed and initial
+  state, and can submit per-tick state checksums; `onDesync` reports differing peer checksums.
+  `createLockstepServer` accepts matching `seed`, `initialState` and `validateInput` options.
+- `MWL_SCHEMA_01` / `MWL_SCHEMA_10` and `schema01` / `schema10` identify the supported MWL
+  vocabularies; `mwl migrate --to 1.0` updates the document version without changing its data.
+  Schema 1.0 additionally enforces declared required attributes and child cardinalities.
+- `ScriptHost` and `createExpressionScriptHost` - the game-owned boundary for executable content.
+  The expression host is the statement-free default. The main `mwl` entry point
+  exports its types without loading a scripting VM. Projects that opt in to the optional
+  `@datamoc/pyroeis` dependency can import `createPyroeisScriptHost` from `@datamoc/mw_games/mwl/pyroeis`.
+  It provides Lua 5.4 evaluation, chunks, named function calls, JSON-shaped context values, and
+  `mwg_emit(name, payload)` events. The adapter opens only the sandbox-safe standard libraries
+  (base, coroutine, math, string, table, utf8): `io`, `os`, `debug` and `package` with its
+  `require` are never constructed, identically in Node and the browser, the base library's `load`,
+  `loadfile` and `dofile` are removed, and chunks compile in text mode only, so a binary
+  `\x1bLua` dump is rejected. It replaces `math.random` with seeded deterministic random, and
+  enforces an
+  instruction budget and a `memoryLimit` (bytes of string and buffer data one call may
+  allocate, 32 MB by default, parsing included), since one `..` or `string.rep` instruction
+  can allocate without bound. Scripts get `local x <const>`, `local x <close>` (with `__close`,
+  run on a normal exit, `break`, `return` and error, and unwound by a limit error too) and
+  `coroutine.close`, from fork 0.3.0; a `__close` cannot yield. The byte budget is the VM's
+  per-call allocation limit (`limits.totalAllocation` on `PyroeisVm`), so a script's own `pcall`
+  sees the standard `not enough memory`
+  while the host still rejects the call. `getmetatable("")` returns `false`. Globals persist between calls on one host, so
+  mutually untrusted scripts need a host each. Lua VM state is not save data: reload scripts
+  from the game's entry point.
+
+- `createPyroeisRuntime` (the same optional `mwl/pyroeis` subpath) returns a
+  `PyroeisRuntime` for games that need synchronous API responses, live state and
+  resumable handlers. It keeps the smaller `ScriptHost` contract intact.
+  `defineFunction(path, callback)` exposes a host function with arguments and a
+  result, and `get`/`set` use dotted global paths made of identifiers. `run` executes
+  text and returns its first result; `call` accepts a path or a `PyroeisReference`.
+  `reference(path)` retains a Lua table or function's identity, including callbacks
+  registered by Lua; dispose references when finished, or dispose the entire runtime.
+  `PyroeisValue` includes plain values, arrays, objects, Maps, BigInts, binary strings
+  as Uint8Arrays and owned references. Ordinary tables are copied on read; contiguous
+  sequences become arrays. Bound tables retain their references even inside lists.
+  Nil maps to null; assigning it removes a Lua table entry. Lua VM state and references
+  are not JSON save data.
+  `createTable(PyroeisTableBinding)` creates a live proxy: `get` and optional `set`
+  run on ordinary indexed reads/writes, with optional `keys` for `pairs` and `length`
+  for `#`. Nested bindings can return other proxy references, allowing a game to expose
+  a side list, each side's resources, a variable namespace or an entity lookup.
+  Its metatable is hidden; Lua `rawget`/`rawset` still bypass bindings, so callbacks
+  must enforce game rules themselves.
+  `PyroeisRuntimeOptions.modules` snapshots exact module IDs and embedded source
+  strings. Lua `require` caches the first result with Lua identity; `dofile` reruns
+  a source and returns all results. A game can alias `game.require = require` without
+  copying a loader. Unknown IDs, cyclic loads and binary chunks are rejected.
+  No filesystem, fetch or XHR is involved; `io`, `os`, `debug`, `package`, `load` and
+  `loadfile` stay absent. Closing a suspended module load clears its loading marker.
+  `defineYieldingFunction` returns request values to the host; a
+  `PyroeisCoroutine` created by `coroutine(pathOrReference)` exposes `status`,
+  `resume(args)` and `close()`. It can also adopt a thread created by Lua, including
+  one already suspended by the script; each thread has one host controller.
+  Each resume returns `{ done, values }`, with scene
+  answers supplied as the next resume's arguments. Close handlers run on explicit
+  closure or runtime disposal; failed handlers retain their error until closure.
+  Instruction and string/buffer allocation budgets cover compilation, modules,
+  host-side indexing and coroutine resumes. Nested host calls share the current
+  budget; a later top-level call/resume gets a fresh budget. Optional `timeLimit`
+  bounds wall-clock time, including callbacks, but cannot preempt host JavaScript.
+  Randomness is seeded; bounded `math.random` intervals require safe integers.
+  Total JavaScript heap and some native operations remain outside these bounds.
+- `luaToJs(source, { format?, header? })` (same subpath) translates Lua to readable
+  JavaScript without running it and returns `{ code, warnings, exports, freeGlobals }`.
+  Metatables, coroutines, general `goto` and some patterns stay as `TODO(lua2js)`
+  comments with a matching warning; invalid Lua throws `LuaSyntaxError`. Pyroeis's
+  runtime numeric `compile` is not used: it is skipped whenever execution limits are on.
+
+`MwlRuntime` exposes `fireEvent(id)` for named event execution. Event conditions compare
+numeric variables numerically, `set_variable` accepts the bounded MWL expression syntax,
+filters can match a unit id, `unit_at` can constrain a side, and both moveto events and unit
+filters take coordinates as comma-separated lists or inclusive ranges (`x=1,2,4-5`). A
+`set_variable` (either spelling, `[set_variable]` or `[command] name="set_variable"`) may
+declare what its own `value=` means with `mode=literal|number|expression`: `literal` keeps the
+text exactly as written, `number` parses it and refuses anything else, `expression` evaluates
+it and treats a missing variable as an error. Without a mode the value is inferred from its
+shape (`$name` copies a variable, a finite number is a number, operator characters or a
+numeric variable's name evaluate), which is what hand-authored content relies on and what a
+compiler target cannot, since a literal such as `Raise Walking Corpse (8 Gold)` would be read
+as an expression. `path=` is that same write with a target built from variables
+(`zombies[$index].allow_recruit`, or `$target` for a variable holding a path), expanded before
+the path is walked; a reference that names nothing throws rather than leaving an empty segment.
+`name=`/`target=` stay literal (a `$` there is not a reference today, so it is not read as one
+now), which keeps every existing write meaning exactly what it did. Top-level
+`say` commands execute normally. Dialogue choices are
+delivered in `MwlMessage.choices` and answered with `answerDialogue`; pending choices are
+included in save data. Commands after a dialogue in the same event run immediately, before
+the answer, so deferred follow-up commands belong in the selected choice event.
+
+The WML action vocabulary (item 250) is on the same event surface. `fire_event` runs another event
+by id. `store_unit` writes matching units into a world variable, `unstore_unit` and `recall` write
+them back (recall can move one to a chosen hex and side), `modify_unit` changes what its `[set]`
+names and `heal_unit` adds `amount` (or sets `hp`). A unit carries its own `name`, `role`/function
+and `can_recruit` leader flag: `[unit]` sets them, a side's own leader is `can_recruit`, and
+`unitMatchesFilter` reads all three, so `[filter] role=courier`, `name=Kalenz` and
+`can_recruit=yes` select on them (`[store_unit]` and the save keep them too). `set_terrain` changes
+one map cell, `capture_village` records ownership in `MwlWorld.villages`, and `clear_shroud`
+records the hexes a side has uncovered in `MwlWorld.clearedShroud`; the fog itself stays a game
+layer. At scenario level, `[role]` fills `MwlWorld.roles` and stamps the role onto the units it
+matches, `[object]` lands in `MwlWorld.objects`, and `[story]` in `MwlWorld.story` as data
+(rendering a story screen is its own item), all kept in the save. `[item]` is deliberately not
+among them: the tag already means an inventory item definition here, so WML's map-placement shape
+would have collided with it.
+
+Typical build-time usage:
+
+```sh
+npm run mwl -- build content/ -o generated/
+```
+
+The executable [`mwl-content` example](../examples/view.html?ex=mwl-content) shows the full
+path: authored content, generated catalog and manifests, then a small game reading the result
+at runtime. A Wesnoth adapter can convert native `.cfg` files to the same MWL input model
+before invoking this build step.
+
+## `mwl/pyroeis`
+
+The optional Lua 5.4 entry point, `@datamoc/mw_games/mwl/pyroeis`, kept off the `mwl` barrel
+so the Pyroeis VM (the optional `@datamoc/pyroeis` dependency) loads only when a game imports
+it. The `mwl` section above describes its behaviour in full; the exports are:
+
+- `createPyroeisScriptHost(options?)` - a sandboxed `ScriptHost` (`PyroeisScriptHostOptions`:
+  `instructionLimit`, `memoryLimit`, `seed`). Only the base, coroutine, math, string, table and
+  utf8 libraries are opened, `load` is removed, `math.random` is seeded, and every call is
+  bounded; globals persist per host.
+- `createPyroeisRuntime(options?)` - a `PyroeisRuntime` for synchronous host calls and live
+  state: `run`, `call`, `get`/`set` on dotted paths, `reference`, `defineFunction`,
+  `defineYieldingFunction`, `createTable` (live proxy tables), `coroutine` and `dispose`.
+  Types: `PyroeisValue`, `PyroeisReference`, `PyroeisCoroutine`, `PyroeisTableBinding`,
+  `PyroeisRuntimeOptions`.
+- `luaToJs(source, options?)` - translates Lua to readable JavaScript without running it
+  (`LuaToJsOptions`/`LuaToJsResult` are re-exported).
+
+## `ai`
+
+Renderer-free decision runners. The game owns perception, navigation, combat rules and
+goals; these modules provide the execution boundary, deterministic choice support, explicit
+actions, serialisable state, diagnostics and budgets.
+
+- `NeuralPolicy` over `NeuralModel`/`DenseLayer`: dependency-free dense inference,
+  ReLU hidden layers and linear output scores, with flat row-major weights and an
+  explicit `observationVersion`. Construction validates dimensions and finite values
+  before copying the weights; limits are 32 layers, 4096 neurons per layer and one
+  million parameters. `predict(input, output?)` reuses activation buffers and can
+  write into a caller-owned `Float64Array`. `exportModel()` returns a plain-data copy
+  suitable for bundling in a local-file game.
+  `selectAction(NeuralObservation, random?)` masks illegal actions, chooses the first
+  best score on ties and returns `null` when all actions are masked. A seeded random
+  callback enables stable-softmax sampling. `behavior(id, actions, observe, sample?)`
+  maps the same policy into `JavaScriptAI`, using its seeded random callback when
+  sampling. `predictBatchAsync(inputs, { signal?, timeout? })` runs a whole inference
+  batch on one worker. The caller owns stale-result rejection if a scene or position
+  changes while awaiting it. Tiny predictions are usually cheaper synchronously;
+  measure batches before offloading them.
+
+- `JavaScriptAI` - registers named behaviours, checks them in declaration order, and returns
+  a JSON-shaped action or an idle decision. A behaviour receives perception, mutable plain
+  state, seeded `random()`, `emit()` and a cooperative `checkpoint()` for cancellation and
+  step or wall-clock budgets. JavaScript cannot interrupt a synchronous function that never
+  checks its checkpoint, so long-running behaviours must cooperate.
+- `Suggester` - the suggestion mode (roadmap 397): the same decision call a game makes
+  for the AI, pointed at a hint UI instead of the world, throttled by a frame-count
+  budget (`every`, never wall clock) so a hint does not tax the frame budget. The
+  first `update` decides immediately, throttled updates return null while `latest`
+  keeps the previous suggestion, an `idle` decision is a suggestion the UI reads
+  (`decision.action === null`), and `clear` drops it. The decider must not mutate
+  game state to compute a suggestion; what the player does with one is the game's.
+- `alphaBetaSearch`/`AlphaBetaGame` - deterministic minimax with alpha-beta pruning over a
+  game-owned immutable-state adapter. The adapter supplies legal moves, transitions, terminal
+  detection, current player and evaluation from the root player's perspective. `depth`,
+  `maxNodes`, cancellation and node diagnostics bound the search; the same primitive works
+  for a local actor and for a top-level controller such as a chess master.
+  `rootSplits`/`firstWins` are the root-split halves of an off-thread search: the split
+  pairs each root move with its child in game order, and first-wins reduces scored moves
+  so ties keep the earlier move.
+- `personalScoreView`/`sideScoreView`/`scoreWith` over `ScoreSubject`/`ScoreView`/
+  `ScorePersonality` - the numbers a mind that weighs outcomes needs, for the case where a search
+  is the wrong tool. The game owns what anything is worth (`scoreOf`), the framework owns how a
+  view is assembled (own, allies and enemies kept apart, plus a `seen` count), and the mind owns
+  what it cares about: a personality is weights, so a selfish scout and a loyal one are content
+  rather than two AI implementations. Both scopes read through the same code and differ only in
+  the visibility set they are handed, a unit's own sight or `FactionFog.sees(side)`. `ScoreSubject`
+  also carries an optional `type`, `role`/function, `can_recruit` leader flag and `name`, and
+  `subjectsWhere`/`ScoreSubjectFilter` select a world on any of them, so a mind finds "the enemy
+  leader" (`{ side: 'red', can_recruit: true }`) without re-deriving it from ids.
+
+- The heuristic AI (item 269): `Aspects`/`AspectValues`/`AspectValue` - the named tuning knobs
+  (`aggression`, `caution`, `keep_away`, `recruitment_pattern`, ...) with typed readers and no
+  built-in values, since the numbers are content; `Difficulty`/`DifficultyLevel` - named levels as
+  aspect overrides on a base set; `Goals`/`Goal`/`GoalKind` - per-unit orders a stage's `weigh`
+  reads; `RecruitmentPattern` - a side's recruit order, cycled, with a fallback. `HeuristicAI`
+  runs candidate actions through `HeuristicStage`s in order, the first whose `when` passes scoring
+  every `HeuristicCandidate` and taking the best (earlier candidate on a tie); a candidate may carry
+  the acting unit's own `type`/`role`/`can_recruit`/`name` for a custom `weigh` to read.
+  `defaultWeigh` is each factor times the aspect of the same name with `keepAwayScore` for a
+  candidate's `distance`; `goalScore` is what a custom `weigh` adds for a goal.
+- `AIDecision`/`AIDecisionInput`/`AIAction` - the shared contract for perception, explicit
+  action objects, status (`action`, `idle`, `cancelled`, or `budget-exceeded`), emitted
+  diagnostics and state snapshots.
+- `AICancelledError`/`AIBudgetExceededError` - the cooperative control-flow errors used by
+  a JavaScript behaviour when it observes cancellation or exceeds its configured budget.
+- `exportState`/`importState` - versioned, JSON-shaped agent state. Function closures, VM
+  state and arbitrary object graphs never become save data.
+- `LuaAI`/`createLuaAI` from `@datamoc/mw_games/ai/lua` - optional Lua 5.4 provider with the same
+  action and state envelope. A Lua function receives `(perception, state)` and returns an action
+  table or `{ action, state, events }`. It uses the existing optional Pyroeis host, which
+  removes filesystem, process, module-loading, clock and debug access, supplies seeded random,
+  and enforces an instruction budget.
+- `AIAgentDefinition`/`AIBehavior` - JavaScript registrations; Lua registrations instead
+  provide a source chunk and an entry function name. Both remain game-owned content and
+  do not include any reference game's code or data.
+
+MWL `[ai]` profiles describe the boundary without embedding executable game rules: `scope`
+is `actor` or `controller`, `provider` is `javascript` or `lua`, `algorithm` can be
+`rules` or `alpha_beta`, and `depth`, `max_nodes`, `player`, `moves`, `apply`, `terminal`
+and `evaluate` identify search limits and game-owned operations. A game resolves those names
+to JavaScript behaviours or Lua functions and supplies the actual state, legal moves and
+evaluation.
+
+### Skeleton extensions (417-421)
+
+- `skeleton.solveTwoBoneIK(skeleton, first, second, target, bend, pose)` solves a connected
+  two-bone chain in world coordinates. `bend` is +1 or -1; positive bends clockwise on screen.
+  Positive finite lengths and a zero origin on the second bone are required. Unreachable
+  targets throw with the chain names. Rest rotations and rotated ancestors are supported.
+- `Bone.limits: { min, max }` bounds the absolute local rotation in degrees, including rest
+  rotation. `skeleton.validatePose` checks an authored pose; `samplePose` and
+  `sampleTransformPose` accept an optional skeleton for validation. Mixers and `resolve`
+  validate automatically. Use a nonnegative or nonpositive interval to constrain bend direction.
+- `Keyframe.translations` and `Keyframe.scales` map bone names to `{ x, y }` channels.
+  `skeleton.sampleTransformPose` and `skeleton.advancePose` return a `TransformPose`, with
+  `rotations`, `translations` and `scales`. Missing channels interpolate toward zero translation
+  or unit scale. Looping, reverse playback, holding, priority layers and crossfades share the
+  rotation timeline. Legacy `samplePose` and `advance` return rotations only.
+- `SkeletalSprite.apply` accepts either rotation poses or `TransformPose`; its mixer uses
+  `advancePose` automatically. `setDiagnostics(true)` explicitly enables bone lines, pivot
+  crosses, joint circles and tips. Omit it in release builds; disabled rigs allocate no overlay.
+- `assets.loadSvgParts(sourceOrPath, { resolution, groups })` returns borrowed textures keyed
+  by top-level SVG group name. It preserves the full SVG canvas, group attributes, shared defs
+  and styles. Repeated loads reuse textures; resolutions have separate cache entries. Compiled
+  asset paths decode directly from data URIs under `file://`. Unknown groups and invalid
+  resolutions throw by name. `releaseSvgParts(parts)` unloads them once no sprite uses them.
+- `node tools/check-skeleton-extensions-browser.mjs [local-vehicle.svg]` builds a classic
+  local-file page, verifies WebGL rendering, texture reuse, resolution isolation and diagnostic
+  cleanup, and writes screenshots under `benchmark-results/skeleton-extensions/`. The default
+  vehicle is generated; passing a local consumer SVG embeds it only into ignored scratch output.
+
+### Deformation, articulated SVG loading and asset filtering (414-416)
+
+- `PinnedDeform` / `DeformableSprite` expose pinned control points. `dragVertex`, `nudgeVertex`
+  and `resetVertices` change GPU vertex positions without changing UVs or rotating the sprite.
+  `dragVertices([{ index, x, y }, ...])` validates a batch before applying it and uploads once;
+  the pure `PinnedDeform.dragMany` performs the same batch operation without a renderer.
+- `loadSvgSkeleton(sourceOrPath, { skeleton, bindings?, pivots?, resolution?, mixer? })` returns
+  `{ sprite, textures }`. `sprite` is a `SkeletalSprite` with named SVG groups already bound.
+  By default matching groups bind in SVG document order. Explicit `bindings` provide draw order,
+  group-to-bone mapping and optional pivot/rest-angle overrides. Pivots come from `data-pivot-x`
+  and `data-pivot-y` (root SVG user coordinates), or a `pivots` map keyed by group id. Missing
+  pivots, groups, bones and duplicate bindings fail by name. Separately bound descendants are
+  removed from parent textures; ancestor transforms, shared styles and defs survive. Artwork is
+  normalized against each bone's rest angle so poses rotate the correct limbs about their pivots.
+  Browser DOMParser/XMLSerializer are required. Compiled paths work under `file://`. Destroy the
+  sprite with `{ children: true }`, then call `releaseSvgParts(textures)` when all users are done.
+- `mwgPage({ assetFiles: ['hero.svg', 'music/theme.ogg'] })` embeds only those asset-folder paths.
+  Omit `assetFiles` to keep all supported assets; `[]` embeds none. Unknown or unsupported named
+  entries fail before replacing compiled asset scripts. Both `emitPage` and `compileResources`
+  accept the same option. `credits.json` generates `CREDITS.txt` when selected, or with no filter.
+- Browser checks: `node tools/check-sprite-deform-browser.mjs [local-bird.svg]` and
+  `node tools/check-svg-skeleton-browser.mjs [local-character.svg] [local-manifest.json]` build
+  local-file WebGL pages and save rest/posed screenshots under `benchmark-results/`. Defaults
+  use generated art; consumer inputs remain in ignored scratch output only.