mons-rules 0.2.3 → 0.3.0

package/MIGRATION.md

@@ -0,0 +1,219 @@
+# Migrating from 0.2 to 0.3
+
+Version 0.3 intentionally removes the Rust/Wasm compatibility layer. The new
+API uses ordinary TypeScript classes, plain readonly objects, string
+discriminants, camelCase names, and structured results. There is no CommonJS
+entrypoint or compatibility shim.
+
+## Import and construct a game
+
+0.2:
+
+```ts
+import { GameVariant, Location, MonsGameModel } from "mons-rules";
+const game = MonsGameModel.new(GameVariant.Classic);
+```
+
+0.3:
+
+```ts
+import {
+  AutomovePreference,
+  Game,
+  GameVariant,
+  Modifier,
+  resolveMatch,
+} from "mons-rules";
+const game = new Game({ variant: GameVariant.Classic });
+```
+
+`GameVariant`, `Color`, `MonKind`, `Consumable`, and `Modifier` are now frozen
+string-valued const objects with matching union types. Persist their string
+values, not the old numeric ordinals.
+
+CommonJS consumers must migrate to ESM:
+
+Removed:
+
+```js
+const rules = require("mons-rules");
+```
+
+0.3:
+
+```js
+import * as rules from "mons-rules";
+```
+
+## Game method mapping
+
+| 0.2                                       | 0.3                                                          |
+| ----------------------------------------- | ------------------------------------------------------------ |
+| `MonsGameModel.new(variant)`              | `new Game({ variant })`                                      |
+| `MonsGameModel.from_fen(fen)`             | `Game.fromFen(fen)`                                          |
+| `game.fen()`                              | `game.toFen()`                                               |
+| `game.active_color()`                     | `game.activeColor`                                           |
+| `game.turn_number()`                      | `game.turnNumber`                                            |
+| `game.white_score()`                      | `game.scores[Color.White]`                                   |
+| `game.black_score()`                      | `game.scores[Color.Black]`                                   |
+| `game.winner_color()`                     | `game.winner`                                                |
+| `game.is_moves_verified()`                | `game.historyVerified`                                       |
+| `game.takeback_fens()`                    | `game.takebackFens`                                          |
+| `game.verbose_tracking_entities()`        | `game.trackingEntries`                                       |
+| `game.process_input_fen(fen)`             | `game.previewFen(fen)` or `game.playFen(fen)`                |
+| `game.process_input(locations, modifier)` | `game.preview(inputs)` or `game.play(inputs)`                |
+| `game.item(location)`                     | `game.itemAt(position)`                                      |
+| `game.square(location)`                   | `game.squareAt(position)`                                    |
+| `game.locations_with_content()`           | `game.contentPositions()`                                    |
+| `game.can_takeback(color)`                | `game.canTakeback(color)`                                    |
+| `game.takeback()`                         | `game.takeback()`                                            |
+| `game.without_last_turn(fens)`            | `game.previousTurn(fens)`                                    |
+| `game.verify_moves(white, black)`         | `game.verifyHistory({ white, black })`                       |
+| `game.is_later_than(otherFen)`            | `game.isLaterThan(otherGame)`                                |
+| `game.available_move_kinds()`             | `game.availableMoveCounts()`                                 |
+| `game.smartAutomove(mode)`                | `game.suggestMove(AutomovePreference.Fast \| Normal \| Pro)` |
+| `game.automove()`                         | `game.suggestMove(AutomovePreference.Random)`                |
+| `game.clearTracking()`                    | `game.clearTracking()`                                       |
+
+Every `suggestMove` call is source-pure. In 0.2, `game.automove()` applied its
+random move to the game; in 0.3, apply a returned suggestion explicitly:
+
+```ts
+const suggestion = game.suggestMove(AutomovePreference.Random);
+if (suggestion !== undefined) {
+  game.play(suggestion.inputs);
+}
+```
+
+`verifyHistory` takes arrays of per-turn input FEN strings. Convert the old
+dash-separated arguments before calling it:
+
+```ts
+game.verifyHistory({
+  white: oldWhiteMoves === "" ? [] : oldWhiteMoves.split("-"),
+  black: oldBlackMoves === "" ? [] : oldBlackMoves.split("-"),
+});
+```
+
+`isLaterThan` now requires a validated `Game` instead of silently accepting an
+invalid FEN:
+
+```ts
+const other = Game.fromFen(otherFen);
+const later = other === undefined ? undefined : game.isLaterThan(other);
+```
+
+## Inputs and positions
+
+`Location` and `Modifier` arguments are replaced by plain `Input` values:
+
+```ts
+// 0.2
+game.process_input([new Location(10, 5), new Location(9, 4)]);
+
+// 0.3
+game.play([
+  { kind: "position", position: { row: 10, column: 5 } },
+  { kind: "position", position: { row: 9, column: 4 } },
+]);
+```
+
+Coordinate fields changed from `i`/`j` to `row`/`column`. Potion and bomb
+selection are explicit input values:
+
+```ts
+{ kind: "modifier", modifier: Modifier.SelectPotion }
+{ kind: "modifier", modifier: Modifier.SelectBomb }
+```
+
+`Modifier.Cancel` has no replacement. Discard the partial input sequence in
+the caller instead of sending a cancellation token.
+
+`preview` and `previewFen` never mutate the game. `play` and `playFen` mutate
+only when the complete sequence is legal; incomplete or invalid sequences
+return `{ kind: "invalid", inputFen }`.
+
+## Outputs, events, and board values
+
+`OutputModel` and `OutputModelKind` are replaced by the `InputResolution`
+discriminated union:
+
+| 0.2 kind               | 0.3 result                                        |
+| ---------------------- | ------------------------------------------------- |
+| `InvalidInput`         | `{ kind: "invalid", inputFen }`                   |
+| `LocationsToStartFrom` | `{ kind: "awaiting-start", inputFen, positions }` |
+| `NextInputOptions`     | `{ kind: "awaiting-input", inputFen, options }`   |
+| `Events`               | `{ kind: "complete", inputFen, events }`          |
+
+Narrow on `kind` instead of calling wrapper accessors:
+
+```ts
+const resolution = game.previewFen("l10,5");
+if (resolution.kind === "awaiting-input") {
+  for (const option of resolution.options) {
+    console.log(option.input, option.action);
+  }
+}
+```
+
+`EventModel`, `ItemModel`, `ManaModel`, `Mon`, `SquareModel`,
+`NextInputModel`, and `VerboseTrackingEntityModel` are now plain readonly
+objects. Their numeric `*Kind` enums were replaced by string `kind`
+discriminants such as `"mon-move"`, `"regular"`, `"mon"`, and
+`"next-turn"`. Event coordinates use descriptive fields including `from`,
+`to`, `at`, and `by`.
+
+Wasm lifecycle methods such as `free()` and mutable wrapper setters no longer
+exist. Construct application values as object literals and treat values
+returned by the engine as readonly.
+
+## Removed engine-only operations
+
+The following compatibility methods exposed mutable engine internals and have
+no public replacement:
+
+- `remove_item`
+- `setVerboseTracking`
+- `newForSimulation`
+- `fromFenForSimulation`
+
+Use `preview` for non-mutating simulation. `inactive_player_items_counters()`
+is replaced by the color-keyed `game.potions` property; select the inactive
+color explicitly.
+
+## Match resolution
+
+The positional `winner` function and its `""`, `"w"`, `"b"`, and `"x"`
+return codes are replaced by `resolveMatch`:
+
+```ts
+const resolution = resolveMatch({
+  white: { fen: whiteFen, moves: whiteMoves },
+  black: { fen: blackFen, moves: blackMoves },
+});
+
+switch (resolution.kind) {
+  case "ongoing":
+    break;
+  case "winner":
+    console.log(resolution.winner);
+    break;
+  case "invalid":
+    break;
+}
+```
+
+Move histories are arrays rather than dash-separated strings.
+
+## Validation differences
+
+The 0.2 compatibility layer emulated Wasm coercions, including numeric enum
+coercion, integer wrapping, permissive string normalization, and no-op
+`free()` methods. Version 0.3 validates the TypeScript domain directly:
+
+- invalid FEN and input FEN return `undefined` or an `"invalid"` result;
+- unsupported variants, colors, and automove preferences throw `TypeError`;
+- positions must use in-bounds integer `row` and `column` values;
+- non-ASCII or non-canonical wire values are rejected rather than normalized.
+
+Update callers to validate external data before constructing typed values.

package/README.md

@@ -1,25 +1,55 @@
 # Mons rules engine
 
-`mons-rules` is the dependency-free TypeScript rules engine for Super Metal Mons.
-Its single ES module works in browsers, Web Workers, Node.js, and Firebase Cloud
-Functions.
+`mons-rules` is the dependency-free TypeScript rules engine for Super Metal
+Mons. The package is an ES module targeting ES2020 and runs in browsers, Web
+Workers, Node.js, and Firebase Cloud Functions.
+
+Version 0.3 introduces an intentionally smaller, idiomatic TypeScript API.
+Existing 0.2 users should follow [MIGRATION.md](./MIGRATION.md).
+
+## Install
+
+```sh
+npm install mons-rules
+```
+
+`mons-rules` is ESM-only:
 
 ```ts
-import { GameVariant, MonsGameModel } from "mons-rules";
+import { AutomovePreference, Game, GameVariant, type Input } from "mons-rules";
 
-const game = MonsGameModel.new(GameVariant.Classic);
-const output = game.process_input_fen("l10,5;l9,4");
+const game = new Game({ variant: GameVariant.Classic });
+
+const inputs: Input[] = [
+  { kind: "position", position: { row: 10, column: 5 } },
+  { kind: "position", position: { row: 9, column: 4 } },
+];
+const result = game.play(inputs);
+
+if (result.kind === "complete") {
+  console.log(result.events);
+}
+
+const suggestion = game.suggestMove(AutomovePreference.Normal);
+console.log(suggestion?.inputFen);
 ```
 
-```js
-const { GameVariant, MonsGameModel } = require("mons-rules");
+FEN helpers are available when a wire-format boundary is more convenient:
 
-const game = MonsGameModel.new(GameVariant.Classic);
+```ts
+const game = new Game();
+const result = game.playFen("l10,5;l9,4");
+const restored = Game.fromFen(game.toFen());
 ```
 
-Published JavaScript targets ES2020 and uses the Web-standard `performance` and
-`crypto` globals. Node.js 22.13 through 22.x, or Node.js 24 or newer, is required for
-Node consumers and repository tooling.
+Use `preview` or `previewFen` to inspect a partial input sequence without
+mutating the game. Use `play` or `playFen` to apply a complete legal move.
+Results, events, board items, positions, and squares are plain discriminated
+objects rather than mutable façade classes.
+
+Published JavaScript uses Web-standard `performance` and `crypto` globals.
+Node.js 22.13 through 22.x, or Node.js 24 or newer, is required for Node
+consumers and repository tooling.
 
 ## Validation
 
@@ -30,22 +60,24 @@ npm ci --engine-strict
 npm run check
 ```
 
-The check streams and replays 699,994 canonical rules transitions without unpacking
-the compressed corpus. It also validates 89 public API edge cases, 39 deterministic
-automove decisions, and 1,527 complete real-player games containing 25,185 turns and
-169,480 inputs across all 12 variants.
+The check streams and replays 699,994 canonical rules transitions without
+unpacking the compressed corpus. It also validates the public API,
+deterministic automove decisions, and 1,527 complete real-player games
+containing 25,185 turns and 169,480 inputs across all 12 variants.
 
-Run `node ./scripts/check-complete-games.cjs` to validate the immutable public corpus
-without replaying it. Run `npm run test:complete-games` for the full engine replay.
+Run `node ./scripts/check-complete-games.mjs` to validate the immutable public
+corpus without replaying it. Run `npm run test:complete-games` for the full
+engine replay.
 
 ## Release
 
 Run `npm run bump` to increment the patch version in `package.json` and
 `package-lock.json`, then commit the release change. Run
-`npm run publish -- --check-only` to validate the unpublished version and perform an
-npm dry run. Run `npm run publish` from a clean worktree to publish that version to
-`latest`.
+`npm run publish -- --check-only` to validate the unpublished version and
+perform an npm dry run. Run `npm run publish` from a clean worktree to publish
+that version to `latest`.
 
-A real publish uses the transient `mons-npm-publish-lock` tag on `origin`, or the
-shared remote named by `MONS_PUBLISH_LOCK_REMOTE`, to serialize releases across
-hosts. The script prints lease-protected recovery instructions if cleanup fails.
+A real publish uses the transient `mons-npm-publish-lock` tag on `origin`, or
+the shared remote named by `MONS_PUBLISH_LOCK_REMOTE`, to serialize releases
+across hosts. The script prints lease-protected recovery instructions if
+cleanup fails.

package/dist/api/game.d.ts

@@ -0,0 +1,39 @@
+import { type AvailableMoveCounts, type AutomovePreference as AutomovePreferenceValue, type BoardItem, type Color as ColorValue, type GameVariant as GameVariantValue, type Input, type InputResolution, type MoveSuggestion, type MoveUsage, type PlayResult, type Position, type Square, type TrackingEntry } from "./types.js";
+export type GameOptions = {
+    readonly variant?: GameVariantValue;
+};
+export type MoveHistory = {
+    readonly white: readonly string[];
+    readonly black: readonly string[];
+};
+export declare class Game {
+    #private;
+    constructor(options?: GameOptions);
+    static fromFen(fen: string): Game | undefined;
+    get variant(): GameVariantValue;
+    get activeColor(): ColorValue;
+    get turnNumber(): number;
+    get scores(): Readonly<Record<ColorValue, number>>;
+    get potions(): Readonly<Record<ColorValue, number>>;
+    get moveUsage(): MoveUsage;
+    get winner(): ColorValue | undefined;
+    get historyVerified(): boolean;
+    get takebackFens(): readonly string[];
+    get trackingEntries(): readonly TrackingEntry[];
+    toFen(): string;
+    preview(inputs: readonly Input[]): InputResolution;
+    previewFen(inputFen: string): InputResolution;
+    play(inputs: readonly Input[]): PlayResult;
+    playFen(inputFen: string): PlayResult;
+    itemAt(position: Position): BoardItem | undefined;
+    squareAt(position: Position): Square;
+    contentPositions(): readonly Position[];
+    canTakeback(color: ColorValue): boolean;
+    takeback(): PlayResult;
+    previousTurn(takebackFens: readonly string[]): Game | undefined;
+    verifyHistory(history: MoveHistory): boolean;
+    isLaterThan(other: Game): boolean;
+    availableMoveCounts(): AvailableMoveCounts;
+    suggestMove(preference: AutomovePreferenceValue): MoveSuggestion | undefined;
+    clearTracking(): void;
+}

package/dist/api/types.d.ts

@@ -0,0 +1,257 @@
+export declare const Color: Readonly<{
+    readonly White: "white";
+    readonly Black: "black";
+}>;
+export type Color = (typeof Color)[keyof typeof Color];
+export declare const GameVariant: Readonly<{
+    readonly Classic: "Classic";
+    readonly SwappedManaRows: "SwappedManaRows";
+    readonly OffsetArcManaRows: "OffsetArcManaRows";
+    readonly CenterSpokeManaRows: "CenterSpokeManaRows";
+    readonly AlternatingManaRows: "AlternatingManaRows";
+    readonly InnerWedgeManaRows: "InnerWedgeManaRows";
+    readonly OuterWedgeManaRows: "OuterWedgeManaRows";
+    readonly BentCenterManaRows: "BentCenterManaRows";
+    readonly OuterEdgeManaRows: "OuterEdgeManaRows";
+    readonly SplitFlankManaRows: "SplitFlankManaRows";
+    readonly ForwardBridgeManaRows: "ForwardBridgeManaRows";
+    readonly CornerChainManaRows: "CornerChainManaRows";
+}>;
+export type GameVariant = (typeof GameVariant)[keyof typeof GameVariant];
+export declare const MonKind: Readonly<{
+    readonly Demon: "demon";
+    readonly Drainer: "drainer";
+    readonly Angel: "angel";
+    readonly Spirit: "spirit";
+    readonly Mystic: "mystic";
+}>;
+export type MonKind = (typeof MonKind)[keyof typeof MonKind];
+export declare const Consumable: Readonly<{
+    readonly Potion: "potion";
+    readonly Bomb: "bomb";
+    readonly BombOrPotion: "bomb-or-potion";
+}>;
+export type Consumable = (typeof Consumable)[keyof typeof Consumable];
+export declare const Modifier: Readonly<{
+    readonly SelectPotion: "select-potion";
+    readonly SelectBomb: "select-bomb";
+}>;
+export type Modifier = (typeof Modifier)[keyof typeof Modifier];
+export declare const AutomovePreference: Readonly<{
+    readonly Random: "random";
+    readonly Fast: "fast";
+    readonly Normal: "normal";
+    readonly Pro: "pro";
+}>;
+export type AutomovePreference = (typeof AutomovePreference)[keyof typeof AutomovePreference];
+export type Position = {
+    readonly row: number;
+    readonly column: number;
+};
+export type Mon = {
+    readonly kind: MonKind;
+    readonly color: Color;
+    readonly cooldown: number;
+};
+export type Mana = {
+    readonly kind: "regular";
+    readonly color: Color;
+} | {
+    readonly kind: "supermana";
+};
+export type Carryable = {
+    readonly kind: "mana";
+    readonly mana: Mana;
+} | {
+    readonly kind: "consumable";
+    readonly consumable: Consumable;
+};
+export type BoardItem = {
+    readonly kind: "mon";
+    readonly mon: Mon;
+    readonly carrying?: Carryable;
+} | Carryable;
+export type Square = {
+    readonly kind: "regular";
+} | {
+    readonly kind: "consumable-base";
+} | {
+    readonly kind: "supermana-base";
+} | {
+    readonly kind: "mana-base";
+    readonly color: Color;
+} | {
+    readonly kind: "mana-pool";
+    readonly color: Color;
+} | {
+    readonly kind: "mon-base";
+    readonly monKind: MonKind;
+    readonly color: Color;
+};
+export type Input = {
+    readonly kind: "takeback";
+} | {
+    readonly kind: "position";
+    readonly position: Position;
+} | {
+    readonly kind: "modifier";
+    readonly modifier: Modifier;
+};
+export type InputAction = "mon-move" | "mana-move" | "mystic-action" | "demon-action" | "demon-additional-step" | "spirit-target-capture" | "spirit-target-move" | "select-consumable" | "bomb-attack";
+type PositionInput = Extract<Input, {
+    readonly kind: "position";
+}>;
+type ModifierInput = Extract<Input, {
+    readonly kind: "modifier";
+}>;
+type PositionInputOption<Action extends Exclude<InputAction, "select-consumable">> = {
+    readonly action: Action;
+    readonly input: PositionInput;
+    readonly actor?: BoardItem;
+};
+export type InputOption = PositionInputOption<"mon-move"> | PositionInputOption<"mana-move"> | PositionInputOption<"mystic-action"> | PositionInputOption<"demon-action"> | PositionInputOption<"demon-additional-step"> | PositionInputOption<"spirit-target-capture"> | PositionInputOption<"spirit-target-move"> | PositionInputOption<"bomb-attack"> | {
+    readonly action: "select-consumable";
+    readonly input: ModifierInput;
+    readonly actor?: BoardItem;
+};
+export type GameEvent = {
+    readonly kind: "mon-move";
+    readonly item: BoardItem;
+    readonly from: Position;
+    readonly to: Position;
+} | {
+    readonly kind: "mana-move";
+    readonly mana: Mana;
+    readonly from: Position;
+    readonly to: Position;
+} | {
+    readonly kind: "mana-scored";
+    readonly mana: Mana;
+    readonly at: Position;
+} | {
+    readonly kind: "mystic-action";
+    readonly mystic: Mon;
+    readonly from: Position;
+    readonly to: Position;
+} | {
+    readonly kind: "demon-action";
+    readonly demon: Mon;
+    readonly from: Position;
+    readonly to: Position;
+} | {
+    readonly kind: "demon-additional-step";
+    readonly demon: Mon;
+    readonly from: Position;
+    readonly to: Position;
+} | {
+    readonly kind: "spirit-target-move";
+    readonly item: BoardItem;
+    readonly from: Position;
+    readonly to: Position;
+    readonly by: Position;
+} | {
+    readonly kind: "pickup-bomb";
+    readonly by: Mon;
+    readonly at: Position;
+} | {
+    readonly kind: "pickup-potion";
+    readonly by: BoardItem;
+    readonly at: Position;
+} | {
+    readonly kind: "use-potion";
+    readonly from: Position;
+    readonly to: Position;
+} | {
+    readonly kind: "pickup-mana";
+    readonly mana: Mana;
+    readonly by: Mon;
+    readonly at: Position;
+} | {
+    readonly kind: "mon-fainted";
+    readonly mon: Mon;
+    readonly from: Position;
+    readonly to: Position;
+} | {
+    readonly kind: "mana-dropped";
+    readonly mana: Mana;
+    readonly at: Position;
+} | {
+    readonly kind: "supermana-back-to-base";
+    readonly from: Position;
+    readonly to: Position;
+} | {
+    readonly kind: "bomb-attack";
+    readonly by: Mon;
+    readonly from: Position;
+    readonly to: Position;
+} | {
+    readonly kind: "mon-awake";
+    readonly mon: Mon;
+    readonly at: Position;
+} | {
+    readonly kind: "bomb-explosion";
+    readonly at: Position;
+} | {
+    readonly kind: "next-turn";
+    readonly color: Color;
+} | {
+    readonly kind: "game-over";
+    readonly winner: Color;
+} | {
+    readonly kind: "takeback";
+};
+export type InvalidInputResolution = {
+    readonly kind: "invalid";
+    readonly inputFen: string;
+};
+export type CompleteInputResolution = {
+    readonly kind: "complete";
+    readonly inputFen: string;
+    readonly events: readonly GameEvent[];
+};
+export type InputResolution = InvalidInputResolution | {
+    readonly kind: "awaiting-start";
+    readonly inputFen: string;
+    readonly positions: readonly Position[];
+} | {
+    readonly kind: "awaiting-input";
+    readonly inputFen: string;
+    readonly options: readonly InputOption[];
+} | CompleteInputResolution;
+export type PlayResult = InvalidInputResolution | CompleteInputResolution;
+export type MoveUsage = {
+    readonly monMoves: number;
+    readonly manaMoves: number;
+    readonly actions: number;
+};
+export type AvailableMoveCounts = MoveUsage & {
+    readonly potions: number;
+};
+export type TrackingEntry = {
+    readonly fen: string;
+    readonly color: Color;
+    readonly events: readonly GameEvent[];
+    readonly eventsFen: string;
+};
+export type MoveSuggestion = {
+    readonly inputs: readonly Input[];
+    readonly inputFen: string;
+    readonly events: readonly GameEvent[];
+};
+export type PlayerSubmission = {
+    readonly fen: string;
+    readonly moves: readonly string[];
+};
+export type MatchSubmission = {
+    readonly white: PlayerSubmission;
+    readonly black: PlayerSubmission;
+};
+export type MatchResolution = {
+    readonly kind: "ongoing";
+} | {
+    readonly kind: "winner";
+    readonly winner: Color;
+} | {
+    readonly kind: "invalid";
+};
+export {};

package/dist/api/winner.d.ts

@@ -0,0 +1,3 @@
+import { type MatchResolution, type MatchSubmission } from "./types.js";
+/** Validate two independently submitted end states and move histories. */
+export declare function resolveMatch(submission: MatchSubmission): MatchResolution;

package/dist/entrypoints/mons-rules.d.ts

@@ -0,0 +1,5 @@
+export { Game } from "../api/game.js";
+export type { GameOptions, MoveHistory } from "../api/game.js";
+export { resolveMatch } from "../api/winner.js";
+export { AutomovePreference, Color, Consumable, GameVariant, Modifier, MonKind, } from "../api/types.js";
+export type { AvailableMoveCounts, BoardItem, Carryable, CompleteInputResolution, GameEvent, Input, InputAction, InputOption, InputResolution, InvalidInputResolution, Mana, MatchResolution, MatchSubmission, Mon, MoveSuggestion, MoveUsage, PlayerSubmission, PlayResult, Position, Square, TrackingEntry, } from "../api/types.js";