@datamoc/mw_games 0.7.3 → 0.7.6

package/CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to `mwg` are documented here. Format follows
 [Semantic Versioning](https://semver.org/) as of this first release - a 0.y.z version means
 the public API may still change between minor versions.
 
+## [0.7.6] - 2026-09-11
+
+### Added
+
+- `Blob.spread` returns the cells it just emptied, in reading order, so a game can turn the ground
+  under a fire to embers at the moment the flames leave it instead of diffing `cellsAbove` between
+  two steps to notice. Cells emptied before the step (a doused one) are not reported.
+
+### Changed
+
+- `pixi.js` moved from `dependencies` to an optional peer dependency, the treatment
+  `@babylonjs/core` already had (item 175's 1.0 decision). The install line now names it:
+  `npm install @datamoc/mw_games pixi.js vite`. A game that only uses the renderer-free modules
+  never downloads it. Verified from an empty directory on all three documented paths: the
+  registry install, the `npm pack` tarball installed by path, and the no-install
+  `mw_games.global.js` script tag.
+
+## [0.7.4] - 2026-09-11
+
+### Added
+
+- `FloatingTextStack` owns the pop-ups a game spawns over world points: one `push` per number, one
+  `update(dt)` to drive them all, and pop-ups sharing a key and an origin stack apart instead of
+  overprinting. `FloatingText` gained a `hold` option for the classic hold-then-fade curve, and its
+  rise now moves an inner layer rather than the container itself - it used to overwrite the
+  container's own `y`, so a pop-up positioned at a world point jumped to `y = 0` on its first
+  update. The fade curve and the stacking rule are exported as pure functions, so both are tested
+  without a DOM.
+- `ParticleEmitter` accepts a `frames` texture sequence, walked per particle across its own life -
+  the four frames of a flame, the puff of smoke - in place of the single `texture`. The current
+  frame is exposed as `Particle.frame` for the same reason the rest of the particle state is.
+- `Bar` recolours its fill at runtime with `setColor(color)` and takes a `background` colour for its
+  track; both are readable back through `color`/`background`, and a runtime colour counts as
+  explicit so a later theme change cannot throw it away. These were the two blockers for a consumer
+  whose bars change colour with state (a health bar going red as it empties) and whose track is
+  black rather than the theme's panel fill.
+
 ## [0.7.3] - 2026-09-11
 
 ### Added
@@ -35,8 +72,6 @@ the public API may still change between minor versions.
 - The standalone bundle baseline, API report, documentation, and roadmap were updated.
 - Release checks now isolate npm audit and package-smoke caches from user-level npm settings.
 
-## [Unreleased]
-
 ## [0.7.1] - 2026-09-10
 
 ### Added

package/README.md

@@ -15,7 +15,7 @@ playable in the browser with no download, plus the generated API reference.
 planning or porting a demanding game with mwg, with links to the [mwg reference](REFERENCE.md)
 and the [mwg Pixel Dungeon study](https://datamoc.github.io/mwg-pixel-dungeon/).
 
-> **Status: pre-alpha (v0.7.3).** Every module in the shared floor below, plus optional
+> **Status: pre-alpha (v0.7.4).** Every module in the shared floor below, plus optional
 > 3D, mobile (Capacitor) and desktop (WebView2) packaging, is built and tested - see
 > [ROADMAP.md](ROADMAP.md) for the full, numbered history.
 >
@@ -28,6 +28,14 @@ and the [mwg Pixel Dungeon study](https://datamoc.github.io/mwg-pixel-dungeon/).
 > Each future major version is meant to carry a name, one per letter of the alphabet: 1.0 takes
 > a name beginning with A, 2.0 one beginning with B, and so on. None of the names are chosen
 > yet, and nothing depends on them until they are.
+>
+> **API stability:** everything documented in [REFERENCE.md](REFERENCE.md) and
+> [API_REPORT.md](API_REPORT.md) is meant to be stable from 1.0 on. Anything that is not carries
+> an `@experimental` tag in its own doc comment, and is called out as experimental in the release
+> notes that introduce it, so it can still change or disappear without a major version. A rename
+> or a removal is deprecated first: the old name keeps working, its doc comment carries
+> `@deprecated` naming the replacement, and the release notes list it. 1.0 is the last release
+> where either can move silently.
 
 ## What it is for
 
@@ -86,19 +94,24 @@ for free: a finished game is still a folder you double-click.
 **With a toolchain**, if you already use a bundler:
 
 ```
-npm install @datamoc/mw_games
+npm install @datamoc/mw_games pixi.js
 ```
 ```ts
 import { Game, Scene } from '@datamoc/mw_games/core';
 import { Sprite } from '@datamoc/mw_games/two-d/render';
 ```
 
+`pixi.js` is the 2D renderer, and it is an optional peer dependency rather than an installed
+one: a game that only uses `mwg/core`, `mwg/roguelike`, `mwg/actors`, `mwg/i18n` or the other
+logic modules never downloads it. Name it on the install line when a game draws, exactly as
+`@babylonjs/core` is named for 3D.
+
 No npm registry access (an offline machine, a pinned artifact for reproducible builds)?
 `npm pack @datamoc/mw_games` downloads the exact published tarball; install it by path
 instead of by name:
 
 ```
-npm install ./datamoc-mw_games-0.1.1.tgz
+npm install ./datamoc-mw_games-<version>.tgz pixi.js
 ```
 
 **Without either.** Drop one file next to your page and open it: this path exists because

package/dist/board/FogOfWar.d.ts

@@ -33,6 +33,12 @@ export declare class FactionFog {
     private explored;
     constructor(width: number, height: number);
     sync(faction: string, sources: readonly VisionCell[], cells: (source: VisionCell) => Iterable<VisionCell>): void;
+    /**
+     * Mark cells explored without changing what is currently visible: the
+     * shroud-clearing half of `sync`, for effects (a revealed map, a scouted
+     * region) that lift the shroud where no unit stands watch.
+     */
+    reveal(faction: string, cells: Iterable<VisionCell>): void;
     isVisible(faction: string, x: number, y: number): boolean;
     isExplored(faction: string, x: number, y: number): boolean;
     visibleCells(faction: string): readonly number[];

package/dist/board/FogOfWar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FogOfWar.d.ts","sourceRoot":"","sources":["../../src/board/FogOfWar.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACV;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,UAAU;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,QAAQ,CAAkC;IAElD,YAAY,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAIxC;IAED,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,UAAU,EAAE,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,QAAQ,CAAC,UAAU,CAAC,GAAG,IAAI,CAW/G;IAED,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAExD;IAED,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAEzD;IAED,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAE/C;IACD,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAEhD;IAED,OAAO,CAAC,MAAM;IAGd,OAAO,CAAC,KAAK;CAGb"}
+{"version":3,"file":"FogOfWar.d.ts","sourceRoot":"","sources":["../../src/board/FogOfWar.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACV;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,UAAU;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,QAAQ,CAAkC;IAElD,YAAY,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAIxC;IAED,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,UAAU,EAAE,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,QAAQ,CAAC,UAAU,CAAC,GAAG,IAAI,CAW/G;IAED;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,IAAI,CAOzD;IAED,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAExD;IAED,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAEzD;IAED,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAE/C;IACD,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAEhD;IAED,OAAO,CAAC,MAAM;IAGd,OAAO,CAAC,KAAK;CAGb"}

package/dist/board/FogOfWar.js

@@ -46,6 +46,21 @@ export class FactionFog {
             memory.add(cell);
         this.explored.set(faction, memory);
     }
+    /**
+     * Mark cells explored without changing what is currently visible: the
+     * shroud-clearing half of `sync`, for effects (a revealed map, a scouted
+     * region) that lift the shroud where no unit stands watch.
+     */
+    reveal(faction, cells) {
+        if (!faction)
+            throw new Error('fog needs a faction id');
+        const memory = this.explored.get(faction) ?? new Set();
+        for (const cell of cells) {
+            if (this.inside(cell.x, cell.y))
+                memory.add(this.index(cell.x, cell.y));
+        }
+        this.explored.set(faction, memory);
+    }
     isVisible(faction, x, y) {
         return this.visible.get(faction)?.has(this.index(x, y)) ?? false;
     }

package/dist/board/FogOfWar.js.map

@@ -1 +1 @@
-{"version":3,"file":"FogOfWar.js","sourceRoot":"","sources":["../../src/board/FogOfWar.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,UAAU;IAMtB,YAAY,KAAa,EAAE,MAAc;QAHjC,YAAO,GAAG,IAAI,GAAG,EAAuB,CAAC;QACzC,aAAQ,GAAG,IAAI,GAAG,EAAuB,CAAC;QAGjD,IAAI,KAAK,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QAC9E,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,OAA8B,EAAE,KAAmD;QACxG,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QACxD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,MAAM,IAAI,OAAO;YAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;gBAClC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;oBAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YACvE,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,GAAG,EAAU,CAAC;QAC/D,KAAK,MAAM,IAAI,IAAI,IAAI;YAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAED,SAAS,CAAC,OAAe,EAAE,CAAS,EAAE,CAAS;QAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC;IAClE,CAAC;IAED,UAAU,CAAC,OAAe,EAAE,CAAS,EAAE,CAAS;QAC/C,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC;IACnE,CAAC;IAED,YAAY,CAAC,OAAe;QAC3B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC/C,CAAC;IACD,aAAa,CAAC,OAAe;QAC5B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAChD,CAAC;IAEO,MAAM,CAAC,CAAS,EAAE,CAAS;QAClC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IAC9D,CAAC;IACO,KAAK,CAAC,CAAS,EAAE,CAAS;QACjC,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC;CACD"}
+{"version":3,"file":"FogOfWar.js","sourceRoot":"","sources":["../../src/board/FogOfWar.ts"],"names":[],"mappings":"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"}

package/dist/core/ActionJournal.d.ts

@@ -0,0 +1,36 @@
+/** One deterministic action and the framework/game events it produced. */
+export interface ActionJournalEntry<Action, Event> {
+    readonly sequence: number;
+    readonly action: Action;
+    readonly events: readonly Event[];
+}
+/**
+ * A serializable, append-only action log for replay, undo checkpoints, synchronization and
+ * debugging. It does not interpret actions or events: the game decides how to reapply an
+ * action, while the journal preserves the exact order and resulting event batch.
+ *
+ * @example
+ * ```ts
+ * import { ActionJournal } from '@datamoc/mw_games/core';
+ *
+ * const journal = new ActionJournal<string, { type: string }>();
+ * journal.append('open-door', [{ type: 'door-opened' }]);
+ * const checkpoint = journal.mark();
+ * // An undo system can restore its state and replay journal.since(checkpoint).
+ * ```
+ */
+export declare class ActionJournal<Action, Event> {
+    private entries;
+    private nextSequence;
+    append(action: Action, events?: readonly Event[]): ActionJournalEntry<Action, Event>;
+    get size(): number;
+    get all(): readonly ActionJournalEntry<Action, Event>[];
+    /** Returns a sequence number that can be used as an undo or sync checkpoint. */
+    mark(): number;
+    since(sequence: number): ActionJournalEntry<Action, Event>[];
+    /** Drops entries at and after a checkpoint, as an undo operation would. */
+    truncate(sequence: number): void;
+    toJSON(): ActionJournalEntry<Action, Event>[];
+    static fromJSON<Action, Event>(entries: readonly ActionJournalEntry<Action, Event>[]): ActionJournal<Action, Event>;
+}
+//# sourceMappingURL=ActionJournal.d.ts.map

package/dist/core/ActionJournal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionJournal.d.ts","sourceRoot":"","sources":["../../src/core/ActionJournal.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB,CAAC,MAAM,EAAE,KAAK;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAa,CAAC,MAAM,EAAE,KAAK;IACvC,OAAO,CAAC,OAAO,CAA2C;IAC1D,OAAO,CAAC,YAAY,CAAK;IAEzB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,SAAS,KAAK,EAAO,GAAG,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,CAIvF;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,GAAG,IAAI,SAAS,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAEtD;IAED,gFAAgF;IAChF,IAAI,IAAI,MAAM,CAEb;IAED,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAE3D;IAED,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAG/B;IAED,MAAM,IAAI,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAE5C;IAED,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,EAC5B,OAAO,EAAE,SAAS,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,GACnD,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,CAa9B;CACD"}

package/dist/core/ActionJournal.js

@@ -0,0 +1,60 @@
+/**
+ * A serializable, append-only action log for replay, undo checkpoints, synchronization and
+ * debugging. It does not interpret actions or events: the game decides how to reapply an
+ * action, while the journal preserves the exact order and resulting event batch.
+ *
+ * @example
+ * ```ts
+ * import { ActionJournal } from '@datamoc/mw_games/core';
+ *
+ * const journal = new ActionJournal<string, { type: string }>();
+ * journal.append('open-door', [{ type: 'door-opened' }]);
+ * const checkpoint = journal.mark();
+ * // An undo system can restore its state and replay journal.since(checkpoint).
+ * ```
+ */
+export class ActionJournal {
+    constructor() {
+        this.entries = [];
+        this.nextSequence = 0;
+    }
+    append(action, events = []) {
+        const entry = { sequence: this.nextSequence++, action, events: structuredClone([...events]) };
+        this.entries.push(entry);
+        return structuredClone(entry);
+    }
+    get size() {
+        return this.entries.length;
+    }
+    get all() {
+        return structuredClone(this.entries);
+    }
+    /** Returns a sequence number that can be used as an undo or sync checkpoint. */
+    mark() {
+        return this.nextSequence;
+    }
+    since(sequence) {
+        return structuredClone(this.entries.filter((entry) => entry.sequence >= sequence));
+    }
+    /** Drops entries at and after a checkpoint, as an undo operation would. */
+    truncate(sequence) {
+        this.entries = this.entries.filter((entry) => entry.sequence < sequence);
+        this.nextSequence = sequence;
+    }
+    toJSON() {
+        return this.all;
+    }
+    static fromJSON(entries) {
+        const journal = new ActionJournal();
+        let expected = 0;
+        for (const entry of entries) {
+            if (!Number.isSafeInteger(entry.sequence) || entry.sequence !== expected)
+                throw new Error('action journal sequences must be contiguous from zero');
+            journal.entries.push(structuredClone({ sequence: entry.sequence, action: entry.action, events: [...entry.events] }));
+            expected++;
+        }
+        journal.nextSequence = expected;
+        return journal;
+    }
+}
+//# sourceMappingURL=ActionJournal.js.map

package/dist/core/ActionJournal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionJournal.js","sourceRoot":"","sources":["../../src/core/ActionJournal.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,aAAa;IAA1B;QACS,YAAO,GAAwC,EAAE,CAAC;QAClD,iBAAY,GAAG,CAAC,CAAC;IAmD1B,CAAC;IAjDA,MAAM,CAAC,MAAc,EAAE,MAAM,GAAqB,EAAE;QACnD,MAAM,KAAK,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC;QAC9F,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,IAAI;QACP,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED,IAAI,GAAG;QACN,OAAO,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;IAED,gFAAgF;IAChF,IAAI;QACH,OAAO,IAAI,CAAC,YAAY,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,QAAgB;QACrB,OAAO,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,IAAI,QAAQ,CAAC,CAAC,CAAC;IACpF,CAAC;IAED,2EAA2E;IAC3E,QAAQ,CAAC,QAAgB;QACxB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAAC;QACzE,IAAI,CAAC,YAAY,GAAG,QAAQ,CAAC;IAC9B,CAAC;IAED,MAAM;QACL,OAAO,IAAI,CAAC,GAA0C,CAAC;IACxD,CAAC;IAED,MAAM,CAAC,QAAQ,CACd,OAAqD;QAErD,MAAM,OAAO,GAAG,IAAI,aAAa,EAAiB,CAAC;QACnD,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ;gBACvE,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;YAC1E,OAAO,CAAC,OAAO,CAAC,IAAI,CACnB,eAAe,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAC9F,CAAC;YACF,QAAQ,EAAE,CAAC;QACZ,CAAC;QACD,OAAO,CAAC,YAAY,GAAG,QAAQ,CAAC;QAChC,OAAO,OAAO,CAAC;IAChB,CAAC;CACD"}

package/dist/core/Blob.d.ts

@@ -19,7 +19,11 @@
  * const fire = new Blob(20, 20);
  * fire.seed(5, 5, 10); // a fireball lands
  *
- * fire.spread((x, y) => x >= 0 && y >= 0 && x < 20 && y < 20, 0.25, 0.9); // one turn of spreading
+ * // one turn of spreading; it hands back whatever it just burned out, so the ground under
+ * // the fire can turn to embers at the moment the flames leave it
+ * const burntOut = fire.spread((x, y) => x >= 0 && y >= 0 && x < 20 && y < 20, 0.25, 0.9);
+ * for (const cell of burntOut) console.log('burned out at', cell.x, cell.y);
+ *
  * for (const cell of fire.cellsAbove(0.5)) console.log('burning at', cell.x, cell.y);
  *
  * fire.clear(5, 5); // someone douses that one tile
@@ -46,8 +50,15 @@ export declare class Blob {
      * `decay` of what it ends up with. `decay: 1` conserves volume and only moves it around;
      * anything lower thins the effect out over time. `open(x, y)` decides whether the effect
      * may cross into a cell, so the caller chooses what blocks it.
+     *
+     * Returns the cells this step emptied, in reading order: those holding a volume before the
+     * step and none after it. That is the moment a game turns the grass under a fire to embers,
+     * and reporting it here saves the game diffing `cellsAbove` between two steps to notice.
      */
-    spread(open: (x: number, y: number) => boolean, spread?: number, decay?: number): void;
+    spread(open: (x: number, y: number) => boolean, spread?: number, decay?: number): Array<{
+        x: number;
+        y: number;
+    }>;
     /** every cell holding at least `minimum` - the cells a game applies its effect on */
     cellsAbove(minimum: number): Array<{
         x: number;

package/dist/core/Blob.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Blob.d.ts","sourceRoot":"","sources":["../../src/core/Blob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAUH,qBAAa,IAAI;IAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,OAAO,CAAC,MAAM,CAAe;IAE7B,YAAY,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAIxC;IAED,mEAAmE;IACnE,OAAO,CAAC,KAAK;IAKb,4DAA4D;IAC5D,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGrC;IAED,iFAAiF;IACjF,KAAK,IAAI,MAAM,CAId;IAED,2EAA2E;IAC3E,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAG/C;IAED,yFAAyF;IACzF,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAGhC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,EAAE,MAAM,SAAO,EAAE,KAAK,SAAM,GAAG,IAAI,CAgChF;IAED,qFAAqF;IACrF,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAS3E;IAED,MAAM,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAE5D;IAED,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI,CAI/E;CACD"}
+{"version":3,"file":"Blob.d.ts","sourceRoot":"","sources":["../../src/core/Blob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAUH,qBAAa,IAAI;IAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,OAAO,CAAC,MAAM,CAAe;IAE7B,YAAY,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAIxC;IAED,mEAAmE;IACnE,OAAO,CAAC,KAAK;IAKb,4DAA4D;IAC5D,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGrC;IAED,iFAAiF;IACjF,KAAK,IAAI,MAAM,CAId;IAED,2EAA2E;IAC3E,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAG/C;IAED,yFAAyF;IACzF,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAGhC;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,EAAE,MAAM,SAAO,EAAE,KAAK,SAAM,GAAG,KAAK,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAsC3G;IAED,qFAAqF;IACrF,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAS3E;IAED,MAAM,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAE5D;IAED,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI,CAI/E;CACD"}

package/dist/core/Blob.js

@@ -19,7 +19,11 @@
  * const fire = new Blob(20, 20);
  * fire.seed(5, 5, 10); // a fireball lands
  *
- * fire.spread((x, y) => x >= 0 && y >= 0 && x < 20 && y < 20, 0.25, 0.9); // one turn of spreading
+ * // one turn of spreading; it hands back whatever it just burned out, so the ground under
+ * // the fire can turn to embers at the moment the flames leave it
+ * const burntOut = fire.spread((x, y) => x >= 0 && y >= 0 && x < 20 && y < 20, 0.25, 0.9);
+ * for (const cell of burntOut) console.log('burned out at', cell.x, cell.y);
+ *
  * for (const cell of fire.cellsAbove(0.5)) console.log('burning at', cell.x, cell.y);
  *
  * fire.clear(5, 5); // someone douses that one tile
@@ -74,6 +78,10 @@ export class Blob {
      * `decay` of what it ends up with. `decay: 1` conserves volume and only moves it around;
      * anything lower thins the effect out over time. `open(x, y)` decides whether the effect
      * may cross into a cell, so the caller chooses what blocks it.
+     *
+     * Returns the cells this step emptied, in reading order: those holding a volume before the
+     * step and none after it. That is the moment a game turns the grass under a fire to embers,
+     * and reporting it here saves the game diffing `cellsAbove` between two steps to notice.
      */
     spread(open, spread = 0.25, decay = 0.9) {
         const next = new Float32Array(this.volume.length);
@@ -102,11 +110,17 @@ export class Blob {
                 }
             }
         }
+        const emptied = [];
         for (let i = 0; i < next.length; i++) {
             const kept = next[i] * decay;
             //snap float dust to zero so a burned-out effect actually reads as gone
-            this.volume[i] = kept < 0.001 ? 0 : kept;
+            const volume = kept < 0.001 ? 0 : kept;
+            if (volume === 0 && this.volume[i] > 0) {
+                emptied.push({ x: i % this.width, y: Math.floor(i / this.width) });
+            }
+            this.volume[i] = volume;
         }
+        return emptied;
     }
     /** every cell holding at least `minimum` - the cells a game applies its effect on */
     cellsAbove(minimum) {

package/dist/core/Blob.js.map

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

package/dist/core/Pathfinding.d.ts

@@ -0,0 +1,41 @@
+/** A cell reached by a weighted flood. */
+export interface WeightedCell<T> {
+    readonly cell: T;
+    readonly cost: number;
+}
+export interface WeightedFloodOptions<T, K> {
+    /** Stable identity for a cell; it may be a string, number, or object key. */
+    key: (cell: T) => K;
+    /** Adjacent cells, in whatever topology the game uses. */
+    neighbors: (cell: T) => Iterable<T>;
+    /** Cost of entering `to` from `from`; non-finite or negative costs are ignored. */
+    cost: (from: T, to: T) => number;
+    /** Maximum accumulated cost, inclusive. */
+    maxCost: number;
+    /** Optional game rule that rejects a candidate before it is reached. */
+    canEnter?: (cell: T, from: T, cost: number) => boolean;
+    /** Optional game rule that keeps a reached cell from expanding further. */
+    stop?: (cell: T, cost: number) => boolean;
+}
+/**
+ * Dijkstra-style weighted flood fill, independent of a particular board or game rule.
+ *
+ * @example
+ * ```ts
+ * import { weightedFlood } from '@datamoc/mw_games/core';
+ *
+ * const cells = weightedFlood(0, {
+ *   key: (cell) => cell,
+ *   neighbors: (cell) => cell < 3 ? [cell + 1] : [],
+ *   cost: () => 1,
+ *   maxCost: 2,
+ * });
+ * console.log(cells.get(2)?.cost); // 2
+ * ```
+ *
+ * The returned map includes `start` at cost 0. A game can use `canEnter` for blockers and
+ * `stop` for rules such as a zone-of-control boundary; neither callback is interpreted here.
+ * Equal-cost revisits are discarded, and the input cells are never mutated.
+ */
+export declare function weightedFlood<T, K>(start: T, options: WeightedFloodOptions<T, K>): Map<K, WeightedCell<T>>;
+//# sourceMappingURL=Pathfinding.d.ts.map

package/dist/core/Pathfinding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Pathfinding.d.ts","sourceRoot":"","sources":["../../src/core/Pathfinding.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,MAAM,WAAW,YAAY,CAAC,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC,EAAE,CAAC;IACzC,6EAA6E;IAC7E,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC;IACpB,0DAA0D;IAC1D,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC;IACpC,mFAAmF;IACnF,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,MAAM,CAAC;IACjC,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACvD,2EAA2E;IAC3E,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CA6B1G"}

package/dist/core/Pathfinding.js

@@ -0,0 +1,86 @@
+/**
+ * Dijkstra-style weighted flood fill, independent of a particular board or game rule.
+ *
+ * @example
+ * ```ts
+ * import { weightedFlood } from '@datamoc/mw_games/core';
+ *
+ * const cells = weightedFlood(0, {
+ *   key: (cell) => cell,
+ *   neighbors: (cell) => cell < 3 ? [cell + 1] : [],
+ *   cost: () => 1,
+ *   maxCost: 2,
+ * });
+ * console.log(cells.get(2)?.cost); // 2
+ * ```
+ *
+ * The returned map includes `start` at cost 0. A game can use `canEnter` for blockers and
+ * `stop` for rules such as a zone-of-control boundary; neither callback is interpreted here.
+ * Equal-cost revisits are discarded, and the input cells are never mutated.
+ */
+export function weightedFlood(start, options) {
+    if (!Number.isFinite(options.maxCost) || options.maxCost < 0)
+        return new Map();
+    const startKey = options.key(start);
+    const reached = new Map([[startKey, { cell: start, cost: 0 }]]);
+    const queue = [{ cell: start, key: startKey, cost: 0 }];
+    while (queue.length > 0) {
+        const current = pop(queue);
+        const known = reached.get(current.key);
+        if (!known || current.cost !== known.cost)
+            continue;
+        if (options.stop?.(current.cell, current.cost))
+            continue;
+        for (const next of options.neighbors(current.cell)) {
+            const step = options.cost(current.cell, next);
+            if (!Number.isFinite(step) || step < 0)
+                continue;
+            const total = current.cost + step;
+            if (total > options.maxCost)
+                continue;
+            if (options.canEnter && !options.canEnter(next, current.cell, total))
+                continue;
+            const key = options.key(next);
+            if (total >= (reached.get(key)?.cost ?? Infinity))
+                continue;
+            const entry = { cell: next, key, cost: total };
+            reached.set(key, entry);
+            push(queue, entry);
+        }
+    }
+    return reached;
+}
+function push(queue, entry) {
+    queue.push(entry);
+    let index = queue.length - 1;
+    while (index > 0) {
+        const parent = Math.floor((index - 1) / 2);
+        if (queue[parent].cost <= queue[index].cost)
+            break;
+        [queue[parent], queue[index]] = [queue[index], queue[parent]];
+        index = parent;
+    }
+}
+function pop(queue) {
+    const first = queue[0];
+    const last = queue.pop();
+    if (!first || !last || queue.length === 0)
+        return first;
+    queue[0] = last;
+    let index = 0;
+    while (true) {
+        const left = index * 2 + 1;
+        const right = left + 1;
+        let smallest = index;
+        if (left < queue.length && queue[left].cost < queue[smallest].cost)
+            smallest = left;
+        if (right < queue.length && queue[right].cost < queue[smallest].cost)
+            smallest = right;
+        if (smallest === index)
+            break;
+        [queue[index], queue[smallest]] = [queue[smallest], queue[index]];
+        index = smallest;
+    }
+    return first;
+}
+//# sourceMappingURL=Pathfinding.js.map

package/dist/core/Pathfinding.js.map

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

package/dist/core/State.d.ts

@@ -0,0 +1,59 @@
+/** A JSON-compatible value owned by a game or one of its framework extensions. */
+export type StateValue = null | boolean | number | string | StateValue[] | {
+    readonly [key: string]: StateValue;
+};
+export interface StateExtension<T extends StateValue = StateValue> {
+    /** stable key written into a snapshot */
+    readonly id: string;
+    /** capture the extension's complete serializable state */
+    readonly capture: () => T;
+    /** restore a previously captured state atomically */
+    readonly restore: (state: T) => void;
+    /** Current schema version for this extension, independent of other save data. */
+    readonly version?: number;
+    /** Migrations are keyed by destination version and run in order. */
+    readonly migrations?: Readonly<Record<number, (state: StateValue) => T>>;
+    /** Optional reset used when a save predates this extension. */
+    readonly reset?: () => void;
+    /** Optional cleanup when the extension is deliberately absent from a restored save. */
+    readonly remove?: () => void;
+}
+export interface StateSnapshot {
+    readonly extensions: Readonly<Record<string, StateValue>>;
+    readonly versions?: Readonly<Record<string, number>>;
+}
+export interface StateRestoreDiagnostic {
+    readonly extension: string;
+    readonly from: number;
+    readonly to: number;
+    readonly status: 'migrated' | 'unchanged' | 'reset' | 'removed';
+}
+/**
+ * Coordinates game-owned save state without knowing its schema.
+ *
+ * Each extension owns its data and restore logic. `transaction` captures all registered
+ * extensions before running work and restores that snapshot if work throws, which prevents
+ * half-applied saves when one subsystem rejects an update.
+ *
+ * @example
+ * ```ts
+ * import { StateRegistry } from '@datamoc/mw_games/core';
+ *
+ * let inventory = { gold: 10 };
+ * const state = new StateRegistry();
+ * state.register({ id: 'inventory', capture: () => inventory, restore: (saved) => { inventory = saved; } });
+ * state.transaction(() => { inventory.gold -= 5; });
+ * const save = state.snapshot();
+ * ```
+ */
+export declare class StateRegistry {
+    private extensions;
+    register<T extends StateValue>(extension: StateExtension<T>): () => void;
+    snapshot(): StateSnapshot;
+    restore(snapshot: StateSnapshot, options?: {
+        readonly missing?: 'keep' | 'reset' | 'remove';
+        readonly onDiagnostic?: (diagnostic: StateRestoreDiagnostic) => void;
+    }): readonly StateRestoreDiagnostic[];
+    transaction<T>(work: () => T): T;
+}
+//# sourceMappingURL=State.d.ts.map

package/dist/core/State.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"State.d.ts","sourceRoot":"","sources":["../../src/core/State.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,EAAE,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAAA;CAAE,CAAC;AAElH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU;IAChE,yCAAyC;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IACrC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC;IACzE,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,uFAAuF;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,OAAO,GAAG,SAAS,CAAC;CAChE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,UAAU,CAAqC;IAEvD,QAAQ,CAAC,CAAC,SAAS,UAAU,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAcvE;IAED,QAAQ,IAAI,aAAa,CAMxB;IAED,OAAO,CACN,QAAQ,EAAE,aAAa,EACvB,OAAO,GAAE;QACR,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;QAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,sBAAsB,KAAK,IAAI,CAAC;KAChE,GACJ,SAAS,sBAAsB,EAAE,CAiCnC;IAED,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAQ/B;CACD"}