@datamoc/mw_games 0.8.2 → 0.9.0

package/dist/simulation/Runtime.d.ts

@@ -1,4 +1,6 @@
 import { Generator } from '../core/Random.ts';
+import { ActionJournal, type ActionJournalEntry } from '../core/ActionJournal.ts';
+import { type UndoHistoryOptions } from '../core/UndoHistory.ts';
 import { Scheduler, type Actor, type SchedulerSnapshot } from '../roguelike/Scheduler.ts';
 import type { SimulationStatus } from './Scenario.ts';
 /** What a rule receives besides state and command: the two sources of non-determinism a
@@ -23,7 +25,56 @@ export interface SimulationSnapshot<State> {
     state: State;
     scheduler: SchedulerSnapshot;
     random: readonly [number, number, number, number];
+    /** Commands already committed, retained for replay, undo checkpoints, and diagnostics. */
+    readonly journal?: readonly ActionJournalEntry<unknown, unknown>[];
 }
+export interface SimulationReplayMismatch<Command, Event> {
+    readonly index: number;
+    readonly action: Command;
+    readonly expectedEvents: readonly Event[];
+    readonly actualEvents: readonly Event[];
+    readonly reason: 'sequence' | 'events' | 'execution' | 'final-state';
+    readonly error?: string;
+}
+export interface SimulationReplayResult<State, Command, Event> {
+    readonly valid: boolean;
+    readonly checked: number;
+    readonly state: State;
+    readonly journal: readonly ActionJournalEntry<Command, Event>[];
+    readonly mismatch?: SimulationReplayMismatch<Command, Event>;
+}
+export interface SimulationRuntimeHistoryOptions<A extends Actor = Actor> extends UndoHistoryOptions {
+    /** Resolves scheduler actor ids when an undo or redo restores a checkpoint. */
+    readonly actorOf: (id: string) => A;
+}
+/**
+ * Replays a journal from an initial snapshot and compares deterministic event batches. The
+ * initial snapshot is treated as a checkpoint, so any journal it carries is ignored. An optional
+ * final-state check catches rules that changed state without emitting an event.
+ *
+ * @example
+ * ```ts
+ * import { validateSimulationReplay, type SimulationRuntimeRule, type SimulationSnapshot } from '@datamoc/mw_games/simulation';
+ * import type { ActionJournalEntry } from '@datamoc/mw_games/core';
+ * import type { Actor } from '@datamoc/mw_games/roguelike';
+ *
+ * declare const initialSnapshot: SimulationSnapshot<unknown>;
+ * declare const recordedJournal: readonly ActionJournalEntry<unknown, unknown>[];
+ * declare const rule: SimulationRuntimeRule<unknown, unknown, unknown, Actor>;
+ * declare const actorOf: (id: string) => Actor;
+ * declare const actorId: (actor: Actor) => string;
+ * const result = validateSimulationReplay(initialSnapshot, recordedJournal, {
+ *   rule, actorOf, actorId,
+ * });
+ * if (!result.valid) console.error('replay diverged at', result.mismatch?.index);
+ * ```
+ */
+export declare function validateSimulationReplay<State, Command, Event, A extends Actor>(initial: SimulationSnapshot<State>, entries: readonly ActionJournalEntry<Command, Event>[], options: {
+    rule: SimulationRuntimeRule<State, Command, Event, A>;
+    actorOf: (id: string) => A;
+    actorId: (actor: A) => string;
+    expectedFinalState?: State;
+}): SimulationReplayResult<State, Command, Event>;
 /**
  * A small facade over one state + one scheduler + one RNG, for the interactive half of a
  * turn-based simulation: the command a player just issued, dispatched through the game's own
@@ -68,21 +119,33 @@ export interface SimulationSnapshot<State> {
  */
 export declare class SimulationRuntime<State, Command, Event, A extends Actor> {
     private _state;
-    readonly scheduler: Scheduler<A>;
+    private _scheduler;
     readonly random: Generator;
+    readonly journal: ActionJournal<Command, Event>;
     private readonly rule;
     private readonly actorId;
+    private readonly history;
+    private readonly actorOf;
     constructor(options: {
         state: State;
         scheduler: Scheduler<A>;
         random: Generator;
         rule: SimulationRuntimeRule<State, Command, Event, A>;
         actorId: (actor: A) => string;
+        journal?: ActionJournal<Command, Event>;
+        history?: SimulationRuntimeHistoryOptions<A>;
     });
+    get scheduler(): Scheduler<A>;
     get state(): State;
     /** Runs one command through the rule, commits the resulting state, and charges its cost
      * to the scheduler's current actor when one is given. */
     dispatch(command: Command): SimulationOutcome<State, Event>;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    /** Restores the previous committed simulation checkpoint, or null when undo is disabled. */
+    undo(): SimulationSnapshot<State> | null;
+    /** Restores the next checkpoint after an undo, or null when no redo is available. */
+    redo(): SimulationSnapshot<State> | null;
     snapshot(version?: number): SimulationSnapshot<State>;
     /**
      * Rebuilds a runtime from a snapshot taken by `snapshot()`. The caller supplies
@@ -94,5 +157,7 @@ export declare class SimulationRuntime<State, Command, Event, A extends Actor> {
         actorOf: (id: string) => A;
         actorId: (actor: A) => string;
     }): SimulationRuntime<State, Command, Event, A>;
+    private historySnapshot;
+    private restoreCheckpoint;
 }
 //# sourceMappingURL=Runtime.d.ts.map

package/dist/simulation/Runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Runtime.d.ts","sourceRoot":"","sources":["../../src/simulation/Runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Runtime.d.ts","sourceRoot":"","sources":["../../src/simulation/Runtime.ts"],"names":[],"mappings":"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"}

package/dist/simulation/Runtime.js

@@ -1,5 +1,83 @@
 import { Generator } from '../core/Random.js';
+import { ActionJournal } from '../core/ActionJournal.js';
+import { stateChecksum } from '../core/SyncGuard.js';
+import { UndoHistory } from '../core/UndoHistory.js';
 import { Scheduler } from '../roguelike/Scheduler.js';
+/**
+ * Replays a journal from an initial snapshot and compares deterministic event batches. The
+ * initial snapshot is treated as a checkpoint, so any journal it carries is ignored. An optional
+ * final-state check catches rules that changed state without emitting an event.
+ *
+ * @example
+ * ```ts
+ * import { validateSimulationReplay, type SimulationRuntimeRule, type SimulationSnapshot } from '@datamoc/mw_games/simulation';
+ * import type { ActionJournalEntry } from '@datamoc/mw_games/core';
+ * import type { Actor } from '@datamoc/mw_games/roguelike';
+ *
+ * declare const initialSnapshot: SimulationSnapshot<unknown>;
+ * declare const recordedJournal: readonly ActionJournalEntry<unknown, unknown>[];
+ * declare const rule: SimulationRuntimeRule<unknown, unknown, unknown, Actor>;
+ * declare const actorOf: (id: string) => Actor;
+ * declare const actorId: (actor: Actor) => string;
+ * const result = validateSimulationReplay(initialSnapshot, recordedJournal, {
+ *   rule, actorOf, actorId,
+ * });
+ * if (!result.valid) console.error('replay diverged at', result.mismatch?.index);
+ * ```
+ */
+export function validateSimulationReplay(initial, entries, options) {
+    const runtime = SimulationRuntime.restore({ ...initial, journal: [] }, options);
+    const failed = (value) => ({
+        valid: false,
+        checked: value.index,
+        state: runtime.state,
+        journal: runtime.journal.toJSON(),
+        mismatch: value,
+    });
+    for (let index = 0; index < entries.length; index++) {
+        const entry = entries[index];
+        if (entry.sequence !== index)
+            return failed({
+                index,
+                action: entry.action,
+                expectedEvents: entry.events,
+                actualEvents: [],
+                reason: 'sequence',
+            });
+        let outcome;
+        try {
+            outcome = runtime.dispatch(entry.action);
+        }
+        catch (error) {
+            return failed({
+                index,
+                action: entry.action,
+                expectedEvents: entry.events,
+                actualEvents: [],
+                reason: 'execution',
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        if (stateChecksum(outcome.events) !== stateChecksum(entry.events))
+            return failed({
+                index,
+                action: entry.action,
+                expectedEvents: entry.events,
+                actualEvents: outcome.events,
+                reason: 'events',
+            });
+    }
+    if (options.expectedFinalState !== undefined &&
+        stateChecksum(runtime.state) !== stateChecksum(options.expectedFinalState))
+        return failed({
+            index: entries.length,
+            action: entries.at(-1)?.action,
+            expectedEvents: [],
+            actualEvents: [],
+            reason: 'final-state',
+        });
+    return { valid: true, checked: entries.length, state: runtime.state, journal: runtime.journal.toJSON() };
+}
 /**
  * A small facade over one state + one scheduler + one RNG, for the interactive half of a
  * turn-based simulation: the command a player just issued, dispatched through the game's own
@@ -45,10 +123,18 @@ import { Scheduler } from '../roguelike/Scheduler.js';
 export class SimulationRuntime {
     constructor(options) {
         this._state = options.state;
-        this.scheduler = options.scheduler;
+        this._scheduler = options.scheduler;
         this.random = options.random;
         this.rule = options.rule;
         this.actorId = options.actorId;
+        this.journal = options.journal ?? new ActionJournal();
+        this.actorOf = options.history?.actorOf ?? null;
+        this.history = options.history ? new UndoHistory(options.history) : null;
+        if (this.history)
+            this.history.push(this.historySnapshot());
+    }
+    get scheduler() {
+        return this._scheduler;
     }
     get state() {
         return this._state;
@@ -56,18 +142,48 @@ export class SimulationRuntime {
     /** Runs one command through the rule, commits the resulting state, and charges its cost
      * to the scheduler's current actor when one is given. */
     dispatch(command) {
-        const outcome = this.rule(this._state, command, { random: this.random, scheduler: this.scheduler });
+        const outcome = this.rule(this._state, command, { random: this.random, scheduler: this._scheduler });
         this._state = outcome.state;
         if (outcome.cost != null)
-            this.scheduler.spend(outcome.cost);
+            this._scheduler.spend(outcome.cost);
+        this.journal.append(command, outcome.events);
+        if (this.history)
+            this.history.push(this.historySnapshot());
         return outcome;
     }
+    get canUndo() {
+        return this.history?.canUndo ?? false;
+    }
+    get canRedo() {
+        return this.history?.canRedo ?? false;
+    }
+    /** Restores the previous committed simulation checkpoint, or null when undo is disabled. */
+    undo() {
+        if (!this.history || !this.actorOf)
+            return null;
+        const snapshot = this.history.undo();
+        if (!snapshot)
+            return null;
+        this.restoreCheckpoint(snapshot);
+        return this.snapshot();
+    }
+    /** Restores the next checkpoint after an undo, or null when no redo is available. */
+    redo() {
+        if (!this.history || !this.actorOf)
+            return null;
+        const snapshot = this.history.redo();
+        if (!snapshot)
+            return null;
+        this.restoreCheckpoint(snapshot);
+        return this.snapshot();
+    }
     snapshot(version = 1) {
         return {
             version,
             state: this._state,
             scheduler: this.scheduler.toJSON(this.actorId),
             random: this.random.getState(),
+            journal: this.journal.toJSON(),
         };
     }
     /**
@@ -83,9 +199,21 @@ export class SimulationRuntime {
             state: snapshot.state,
             scheduler,
             random,
+            journal: ActionJournal.fromJSON((snapshot.journal ?? [])),
             rule: options.rule,
             actorId: options.actorId,
         });
     }
+    historySnapshot() {
+        return structuredClone(this.snapshot());
+    }
+    restoreCheckpoint(snapshot) {
+        if (!this.actorOf)
+            throw new Error('simulation history needs actorOf to restore a checkpoint');
+        this._state = structuredClone(snapshot.state);
+        this._scheduler = Scheduler.restore(snapshot.scheduler, this.actorOf);
+        this.random.setState(snapshot.random);
+        this.journal.replace((snapshot.journal ?? []));
+    }
 }
 //# sourceMappingURL=Runtime.js.map

package/dist/simulation/Runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"Runtime.js","sourceRoot":"","sources":["../../src/simulation/Runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAsC,MAAM,2BAA2B,CAAC;AAkC1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,OAAO,iBAAiB;IAO7B,YAAY,OAMX;QACA,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAC5B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAChC,CAAC;IAED,IAAI,KAAK;QACR,OAAO,IAAI,CAAC,MAAM,CAAC;IACpB,CAAC;IAED;6DACyD;IACzD,QAAQ,CAAC,OAAgB;QACxB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QACpG,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAC5B,IAAI,OAAO,CAAC,IAAI,IAAI,IAAI;YAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7D,OAAO,OAAO,CAAC;IAChB,CAAC;IAED,QAAQ,CAAC,OAAO,GAAG,CAAC;QACnB,OAAO;YACN,OAAO;YACP,KAAK,EAAE,IAAI,CAAC,MAAM;YAClB,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;YAC9C,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE;SAC9B,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,OAAO,CACb,QAAmC,EACnC,OAIC;QAED,MAAM,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC/B,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACjC,MAAM,SAAS,GAAG,SAAS,CAAC,OAAO,CAAI,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QAC5E,OAAO,IAAI,iBAAiB,CAA2B;YACtD,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,SAAS;YACT,MAAM;YACN,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,OAAO,EAAE,OAAO,CAAC,OAAO;SACxB,CAAC,CAAC;IACJ,CAAC;CACD"}
+{"version":3,"file":"Runtime.js","sourceRoot":"","sources":["../../src/simulation/Runtime.ts"],"names":[],"mappings":"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"}

package/dist/simulation/index.d.ts

@@ -6,8 +6,8 @@ export { Campaign } from './Campaign.ts';
 export type { CampaignOutcome, CampaignLevel, CampaignLevelResult, CampaignSnapshot } from './Campaign.ts';
 export { runHeadlessScenario } from './Harness.ts';
 export type { HeadlessScenario, HeadlessScenarioResult } from './Harness.ts';
-export { SimulationRuntime } from './Runtime.ts';
-export type { SimulationContext, SimulationOutcome, SimulationRuntimeRule, SimulationSnapshot } from './Runtime.ts';
+export { SimulationRuntime, validateSimulationReplay } from './Runtime.ts';
+export type { SimulationContext, SimulationOutcome, SimulationReplayMismatch, SimulationReplayResult, SimulationRuntimeHistoryOptions, SimulationRuntimeRule, SimulationSnapshot, } from './Runtime.ts';
 export { EventPresentation } from './EventPresentation.ts';
 export type { EventPresentationOptions } from './EventPresentation.ts';
 export { CampaignSave } from './CampaignSave.ts';

package/dist/simulation/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/simulation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,cAAc,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAChH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC3G,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACpH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE9E;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,YAAY,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/simulation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,cAAc,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAChH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC3G,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAC3E,YAAY,EACX,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,EACxB,sBAAsB,EACtB,+BAA+B,EAC/B,qBAAqB,EACrB,kBAAkB,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE9E;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,YAAY,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/simulation/index.js

@@ -2,7 +2,7 @@ export { advanceToInput } from './Turns.js';
 export { runScenario } from './Scenario.js';
 export { Campaign } from './Campaign.js';
 export { runHeadlessScenario } from './Harness.js';
-export { SimulationRuntime } from './Runtime.js';
+export { SimulationRuntime, validateSimulationReplay } from './Runtime.js';
 export { EventPresentation } from './EventPresentation.js';
 export { CampaignSave } from './CampaignSave.js';
 /**

package/dist/simulation/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/simulation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/simulation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAU3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/version.d.ts

@@ -9,5 +9,5 @@
  * this from `package.json` automatically, chosen because this project's own build already
  * has no step before `tsc`/`vite` that this would need to run ahead of.
  */
-export declare const version = "0.8.2";
+export declare const version = "0.9.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -9,5 +9,5 @@
  * this from `package.json` automatically, chosen because this project's own build already
  * has no step before `tsc`/`vite` that this would need to run ahead of.
  */
-export const version = '0.8.2';
+export const version = '0.9.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@datamoc/mw_games",
-	"version": "0.8.2",
+	"version": "0.9.0",
 	"description": "A local-file game framework: renderer-free game logic, drawn through PixiJS in 2D or Babylon.js in 3D, with mobile and desktop packaging.",
 	"license": "MPL-2.0",
 	"repository": {
@@ -255,6 +255,7 @@
 		"roadmap:browser": "node tools/roadmap-progress.mjs --browser"
 	},
 	"dependencies": {
+		"json5": "^2.2.3",
 		"rot-js": "^2.2.1"
 	},
 	"peerDependencies": {

package/tools/mwl.mjs

@@ -19,7 +19,8 @@ import {
 } from '../dist/mwl/index.js';
 
 /**
- * Command line for MWL: validate, compile, extract-i18n, assets, hooks, build.
+ * Command line for MWL: validate, compile, format, migrate, extract-i18n, assets, report,
+ * diagnostics, ci, hooks, build.
  *
  * Reading files happens here, not in the published module, so the library
  * itself stays free of node builtins. `hooks` needs esbuild and says so
@@ -40,7 +41,19 @@ import {
  */
 
 const args = process.argv.slice(2);
-const commands = ['validate', 'compile', 'extract-i18n', 'assets', 'report', 'hooks', 'build'];
+const commands = [
+	'validate',
+	'compile',
+	'format',
+	'migrate',
+	'extract-i18n',
+	'assets',
+	'report',
+	'diagnostics',
+	'ci',
+	'hooks',
+	'build',
+];
 const [command, input] = args;
 const outputFlag = args.indexOf('-o');
 const output = outputFlag === -1 ? undefined : args[outputFlag + 1];
@@ -48,17 +61,44 @@ const manifestFlag = args.indexOf('--manifest');
 const manifestPath = manifestFlag === -1 ? undefined : args[manifestFlag + 1];
 const assetRootFlag = args.indexOf('--asset-root');
 const assetRoot = assetRootFlag === -1 ? undefined : args[assetRootFlag + 1];
+const targetFlag = args.indexOf('--to');
+const target = targetFlag === -1 ? undefined : args[targetFlag + 1];
 
 if (!command || !input || !commands.includes(command)) {
 	console.error(
-		'Usage: mwl <validate|compile|extract-i18n|assets|report|hooks|build> input.mwl [-o output] [--manifest hooks.json] [--asset-root directory]',
+		'Usage: mwl <validate|compile|format|migrate|extract-i18n|assets|report|diagnostics|ci|hooks|build> input.mwl [-o output] [--to 1.0] [--manifest hooks.json] [--asset-root directory]',
 	);
 	process.exitCode = 2;
 } else {
 	const files = fs.statSync(input).isDirectory()
 		? collectSources(input)
 		: [{ file: sourceLabel(input), source: fs.readFileSync(input, 'utf8') }];
-	if (command === 'validate') {
+	if (command === 'format' || command === 'migrate') {
+		if (command === 'migrate' && target !== '1.0') {
+			console.error('mwl migrate currently supports only --to 1.0');
+			process.exitCode = 2;
+		} else {
+			const nodes = files.flatMap((file) => parse(preprocess(file.source, { file: file.file }), file.file));
+			const text = `${JSON.stringify(
+				nodes.map((node) => formatNode(node, command === 'migrate' ? target : undefined)),
+				null,
+				'\t',
+			)}\n`;
+			if (output) {
+				fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
+				fs.writeFileSync(output, text);
+			} else process.stdout.write(text);
+		}
+	} else if (command === 'diagnostics' || command === 'ci') {
+		const diagnostics = diagnose(files);
+		const report = command === 'ci' ? { valid: diagnostics.length === 0, diagnostics } : diagnostics;
+		const text = `${JSON.stringify(report, null, '\t')}\n`;
+		if (output) {
+			fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
+			fs.writeFileSync(output, text);
+		} else process.stdout.write(text);
+		if (diagnostics.length) process.exitCode = 1;
+	} else if (command === 'validate') {
 		const diagnostics = files.flatMap((file) =>
 			validate(parse(preprocess(file.source, { file: file.file }), file.file)),
 		);
@@ -123,6 +163,47 @@ function sourceLabel(file) {
 	return (relative || path.basename(path.resolve(file))).split(path.sep).join('/');
 }
 
+/** Parse and validate every input without throwing, for machine-readable CI diagnostics. */
+function diagnose(files) {
+	const diagnostics = [];
+	for (const file of files) {
+		try {
+			diagnostics.push(...validate(parse(preprocess(file.source, { file: file.file }), file.file)));
+		} catch (error) {
+			if (error?.diagnostic) diagnostics.push(error.diagnostic);
+			else
+				diagnostics.push({
+					code: 'MWL_CLI',
+					message: error instanceof Error ? error.message : String(error),
+					location: { file: file.file, line: 1, column: 1 },
+				});
+		}
+	}
+	return diagnostics.sort(
+		(a, b) =>
+			a.location.file.localeCompare(b.location.file) ||
+			a.location.line - b.location.line ||
+			a.location.column - b.location.column ||
+			a.code.localeCompare(b.code),
+	);
+}
+
+/** Emit a stable, source-independent MWL document after preprocessing. */
+function formatNode(node, target) {
+	const attributes = Object.fromEntries(
+		Object.entries(node.attributes).map(([name, value]) => [
+			name,
+			node.gettext?.includes(name) ? { $gettext: value } : value,
+		]),
+	);
+	if (target === '1.0' && node.tag === 'game') attributes.schema = '1.0';
+	return {
+		tag: node.tag,
+		...attributes,
+		...(node.children.length ? { children: node.children.map((child) => formatNode(child, target)) } : {}),
+	};
+}
+
 /** One deterministic build step for the three files every MWL game consumes. */
 function build(files) {
 	const game = compileSources(files);