@futdevpro/fsm-dynamo 1.20.97 → 1.20.100

package/build/_modules/game/_collections/build-reservation.util.d.ts

@@ -0,0 +1,31 @@
+import { DyFM_BuildReservation, DyFM_PlacementPreview, DyFM_PlacementRule, DyFM_RefundLine, DyFM_RefundPolicy, DyFM_ReservedCostSource } from '../_models/build-reservation.interface';
+/**
+ * BFR-WARFACTORY-012 (①–②) — placement preview and escrow reservation, headless and pure (the caller owns the world
+ * state and applies the returned refund lines).
+ */
+export declare class DyFM_BuildReservation_Util {
+    /** ① Evaluates EVERY rule and returns the preview with all failure reasons (not just the first). */
+    static preview<TPosition>(candidate: {
+        position: TPosition;
+        footprint: {
+            width: number;
+            height: number;
+        };
+    }, rules: DyFM_PlacementRule<TPosition>[]): DyFM_PlacementPreview<TPosition>;
+    /**
+     * ② Holds the cost in escrow for a VALID preview. An invalid preview or a non-positive amount throws
+     * (`DYFM-RESERVATION-INVALID`) — reserving an invalid placement is how resources silently disappear.
+     */
+    static reserve<TPosition>(reservationId: string, preview: DyFM_PlacementPreview<TPosition>, sources: DyFM_ReservedCostSource[], policy?: DyFM_RefundPolicy): DyFM_BuildReservation<TPosition>;
+    /** ② The build started / finished: the escrow is consumed. Idempotent on `committed`; a released one cannot commit. */
+    static commit<TPosition>(reservation: DyFM_BuildReservation<TPosition>): DyFM_BuildReservation<TPosition>;
+    /**
+     * ② Cancel: returns the refund lines BACK TO THEIR ORIGINAL SOURCES — `cancelRefundRatio × (1 − progressRatio)`
+     * of each line (floored to whole units). A second release returns nothing (no double refund).
+     */
+    static release<TPosition>(reservation: DyFM_BuildReservation<TPosition>, progressRatio?: number): {
+        reservation: DyFM_BuildReservation<TPosition>;
+        refunds: DyFM_RefundLine[];
+    };
+}
+//# sourceMappingURL=build-reservation.util.d.ts.map

package/build/_modules/game/_collections/build-reservation.util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-reservation.util.d.ts","sourceRoot":"","sources":["../../../../src/_modules/game/_collections/build-reservation.util.ts"],"names":[],"mappings":"AACA,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EAErB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,uBAAuB,EACxB,MAAM,wCAAwC,CAAC;AAEhD;;;GAGG;AACH,qBAAa,0BAA0B;IAErC,oGAAoG;IACpG,MAAM,CAAC,OAAO,CAAC,SAAS,EACtB,SAAS,EAAE;QAAE,QAAQ,EAAE,SAAS,CAAC;QAAC,SAAS,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,EAChF,KAAK,EAAE,kBAAkB,CAAC,SAAS,CAAC,EAAE,GACrC,qBAAqB,CAAC,SAAS,CAAC;IAiBnC;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,SAAS,EACtB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,qBAAqB,CAAC,SAAS,CAAC,EACzC,OAAO,EAAE,uBAAuB,EAAE,EAClC,MAAM,GAAE,iBAAsB,GAC7B,qBAAqB,CAAC,SAAS,CAAC;IAwBnC,uHAAuH;IACvH,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,WAAW,EAAE,qBAAqB,CAAC,SAAS,CAAC,GAAG,qBAAqB,CAAC,SAAS,CAAC;IAYzG;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,SAAS,EACtB,WAAW,EAAE,qBAAqB,CAAC,SAAS,CAAC,EAC7C,aAAa,GAAE,MAAU,GACxB;QAAE,WAAW,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAC;QAAC,OAAO,EAAE,eAAe,EAAE,CAAA;KAAE;CAcjF"}

package/build/_modules/game/_collections/build-reservation.util.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DyFM_BuildReservation_Util = void 0;
+const error_control_model_1 = require("../../../_models/control-models/error.control-model");
+/**
+ * BFR-WARFACTORY-012 (①–②) — placement preview and escrow reservation, headless and pure (the caller owns the world
+ * state and applies the returned refund lines).
+ */
+class DyFM_BuildReservation_Util {
+    /** ① Evaluates EVERY rule and returns the preview with all failure reasons (not just the first). */
+    static preview(candidate, rules) {
+        const reasons = [];
+        if (!(candidate.footprint?.width > 0) || !(candidate.footprint?.height > 0)) {
+            reasons.push({ code: 'invalid-footprint', message: 'the footprint must be at least 1 × 1' });
+        }
+        for (const rule of rules) {
+            const reason = rule(candidate);
+            if (reason) {
+                reasons.push(reason);
+            }
+        }
+        return { position: candidate.position, footprint: { ...candidate.footprint }, valid: !reasons.length, reasons: reasons };
+    }
+    /**
+     * ② Holds the cost in escrow for a VALID preview. An invalid preview or a non-positive amount throws
+     * (`DYFM-RESERVATION-INVALID`) — reserving an invalid placement is how resources silently disappear.
+     */
+    static reserve(reservationId, preview, sources, policy = {}) {
+        const ratio = policy.cancelRefundRatio ?? 1;
+        if (!reservationId || !preview.valid
+            || sources.some((s) => !s.resource || !s.sourceId || !(s.amount > 0))
+            || !(ratio >= 0 && ratio <= 1)) {
+            throw new error_control_model_1.DyFM_Error({
+                message: 'DyFM_BuildReservation: reserve needs an id, a VALID preview, sources with resource + sourceId + '
+                    + `amount > 0 and a refund ratio in 0..1 (reasons: ${preview.reasons.map((r) => r.code).join(', ') || '-'})`,
+                errorCode: 'DYFM-RESERVATION-INVALID',
+                issuerService: 'DyFM_BuildReservation_Util',
+            });
+        }
+        return {
+            reservationId: reservationId,
+            position: preview.position,
+            footprint: { ...preview.footprint },
+            reservedCostSources: sources.map((s) => ({ ...s })),
+            refundPolicy: { cancelRefundRatio: ratio },
+            status: 'held',
+        };
+    }
+    /** ② The build started / finished: the escrow is consumed. Idempotent on `committed`; a released one cannot commit. */
+    static commit(reservation) {
+        if (reservation.status === 'released') {
+            throw new error_control_model_1.DyFM_Error({
+                message: `DyFM_BuildReservation: ${reservation.reservationId} was already released — it cannot be committed`,
+                errorCode: 'DYFM-RESERVATION-STATE',
+                issuerService: 'DyFM_BuildReservation_Util',
+            });
+        }
+        return { ...reservation, status: 'committed' };
+    }
+    /**
+     * ② Cancel: returns the refund lines BACK TO THEIR ORIGINAL SOURCES — `cancelRefundRatio × (1 − progressRatio)`
+     * of each line (floored to whole units). A second release returns nothing (no double refund).
+     */
+    static release(reservation, progressRatio = 0) {
+        if (reservation.status === 'released') {
+            return { reservation: reservation, refunds: [] };
+        }
+        const progress = Math.min(1, Math.max(0, Number.isFinite(progressRatio) ? progressRatio : 0));
+        const share = reservation.refundPolicy.cancelRefundRatio * (1 - progress);
+        const refunds = reservation.reservedCostSources
+            .map((s) => ({ resource: s.resource, sourceId: s.sourceId, amount: Math.floor(s.amount * share + 1e-9) }))
+            .filter((line) => line.amount > 0);
+        return { reservation: { ...reservation, status: 'released' }, refunds: refunds };
+    }
+}
+exports.DyFM_BuildReservation_Util = DyFM_BuildReservation_Util;
+//# sourceMappingURL=build-reservation.util.js.map

package/build/_modules/game/_collections/build-reservation.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-reservation.util.js","sourceRoot":"","sources":["../../../../src/_modules/game/_collections/build-reservation.util.ts"],"names":[],"mappings":";;;AAAA,6FAAiF;AAWjF;;;GAGG;AACH,MAAa,0BAA0B;IAErC,oGAAoG;IACpG,MAAM,CAAC,OAAO,CACZ,SAAgF,EAChF,KAAsC;QAEtC,MAAM,OAAO,GAA2B,EAAE,CAAC;QAE3C,IAAI,CAAC,CAAC,SAAS,CAAC,SAAS,EAAE,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;YAC5E,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,sCAAsC,EAAE,CAAC,CAAC;QAC/F,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,MAAM,GAAgC,IAAI,CAAC,SAAS,CAAC,CAAC;YAE5D,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QAED,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,EAAE,GAAG,SAAS,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAC3H,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,OAAO,CACZ,aAAqB,EACrB,OAAyC,EACzC,OAAkC,EAClC,SAA4B,EAAE;QAE9B,MAAM,KAAK,GAAW,MAAM,CAAC,iBAAiB,IAAI,CAAC,CAAC;QAEpD,IAAI,CAAC,aAAa,IAAI,CAAC,OAAO,CAAC,KAAK;eAC/B,OAAO,CAAC,IAAI,CAAC,CAAC,CAA0B,EAAW,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;eACpG,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,gCAAU,CAAC;gBACnB,OAAO,EAAE,kGAAkG;sBACvG,mDAAmD,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAuB,EAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,GAAG;gBAC5I,SAAS,EAAE,0BAA0B;gBACrC,aAAa,EAAE,4BAA4B;aAC5C,CAAC,CAAC;QACL,CAAC;QAED,OAAO;YACL,aAAa,EAAE,aAAa;YAC5B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,SAAS,EAAE,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE;YACnC,mBAAmB,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAA0B,EAA2B,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;YACrG,YAAY,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE;YAC1C,MAAM,EAAE,MAAM;SACf,CAAC;IACJ,CAAC;IAED,uHAAuH;IACvH,MAAM,CAAC,MAAM,CAAY,WAA6C;QACpE,IAAI,WAAW,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YACtC,MAAM,IAAI,gCAAU,CAAC;gBACnB,OAAO,EAAE,0BAA0B,WAAW,CAAC,aAAa,gDAAgD;gBAC5G,SAAS,EAAE,wBAAwB;gBACnC,aAAa,EAAE,4BAA4B;aAC5C,CAAC,CAAC;QACL,CAAC;QAED,OAAO,EAAE,GAAG,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IACjD,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,OAAO,CACZ,WAA6C,EAC7C,gBAAwB,CAAC;QAEzB,IAAI,WAAW,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YACtC,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QACnD,CAAC;QAED,MAAM,QAAQ,GAAW,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACtG,MAAM,KAAK,GAAW,WAAW,CAAC,YAAY,CAAC,iBAAiB,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC;QAClF,MAAM,OAAO,GAAsB,WAAW,CAAC,mBAAmB;aAC/D,GAAG,CAAC,CAAC,CAA0B,EAAmB,EAAE,CACnD,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;aAC/F,MAAM,CAAC,CAAC,IAAqB,EAAW,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAE/D,OAAO,EAAE,WAAW,EAAE,EAAE,GAAG,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IACnF,CAAC;CACF;AA1FD,gEA0FC"}

package/build/_modules/game/_collections/game-save.util.d.ts

@@ -0,0 +1,46 @@
+import { DyFM_GameSave_ConflictResult, DyFM_GameSave_Envelope, DyFM_GameSave_Metadata, DyFM_GameSave_MigrationStep, DyFM_GameSave_Result, DyFM_GameSave_SealInput } from '../_models/game-save.interface';
+/** The only envelope format this version reads and writes. */
+export declare const DYFM_GAME_SAVE_FORMAT: 'dyfm-game-save/1';
+/**
+ * BFR-WARFACTORY-011 — deterministic, headless game-save operations: seal (checksum), parse (corruption + format
+ * check), migrate (ordered replay with a typed failure) and conflict resolution (lineage first, then a time window).
+ * Nothing here reads a clock, a platform or a credential.
+ */
+export declare class DyFM_GameSave_Util {
+    /**
+     * FNV-1a (32-bit, hex) over the CANONICAL JSON of the payload (object keys sorted) — the same payload always gives
+     * the same checksum, whatever the key order. A corruption / identity check, NOT a security signature.
+     */
+    static checksum(payload: unknown): string;
+    /** Builds an envelope with the format and the computed checksum. Invalid input throws (`DYFM-GAME-SAVE-SEAL`). */
+    static seal<TPayload>(input: DyFM_GameSave_SealInput<TPayload>): DyFM_GameSave_Envelope<TPayload>;
+    /** The metadata of an envelope (what `list` returns — no payload). */
+    static metadataOf(envelope: DyFM_GameSave_Envelope): DyFM_GameSave_Metadata;
+    /**
+     * Validates a RAW read (anything an adapter returned): shape, format, field types and the checksum. A corrupt or
+     * foreign save is a typed failure — never a half-loaded game.
+     */
+    static parse<TPayload = unknown>(raw: unknown): DyFM_GameSave_Result<TPayload>;
+    /**
+     * Replays the migration steps from the envelope's `schemaVersion` up to `targetVersion`, step by step, on a COPY of
+     * the payload; the result is re-sealed (same slot, time and lineage). A save NEWER than the target, a gap in the
+     * chain or a throwing step is a typed failure and the input is untouched.
+     */
+    static migrate<TPayload = unknown>(envelope: DyFM_GameSave_Envelope, steps: DyFM_GameSave_MigrationStep[], targetVersion: number): DyFM_GameSave_Result<TPayload>;
+    /**
+     * Deterministic local ↔ remote decision for ONE slot:
+     * none / one side missing → the existing one · same checksum → `in-sync` · proven descent (one side's
+     * `parentChecksum` is the other's checksum) → the descendant · both carry lineage but neither descends from the
+     * other → `ask-user` (a true divergence: picking one silently LOSES progress) · no lineage (legacy saves) → within
+     * `ambiguityWindowMs` `ask-user`, otherwise the newer one.
+     */
+    static resolveConflict(local: DyFM_GameSave_Metadata | null | undefined, remote: DyFM_GameSave_Metadata | null | undefined, options?: {
+        ambiguityWindowMs?: number;
+    }): DyFM_GameSave_ConflictResult;
+    private static isVersion;
+    /** JSON with sorted object keys (arrays keep their order) — the checksum input. */
+    private static canonicalJson;
+    /** A deep copy for the migration replay (a step must not be able to change the caller's envelope). */
+    private static clone;
+}
+//# sourceMappingURL=game-save.util.d.ts.map

package/build/_modules/game/_collections/game-save.util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-save.util.d.ts","sourceRoot":"","sources":["../../../../src/_modules/game/_collections/game-save.util.ts"],"names":[],"mappings":"AACA,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,EACtB,sBAAsB,EACtB,2BAA2B,EAC3B,oBAAoB,EACpB,uBAAuB,EACxB,MAAM,gCAAgC,CAAC;AAExC,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,EAAE,kBAAuC,CAAC;AAE5E;;;;GAIG;AACH,qBAAa,kBAAkB;IAE7B;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM;IAYzC,kHAAkH;IAClH,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,uBAAuB,CAAC,QAAQ,CAAC,GAAG,sBAAsB,CAAC,QAAQ,CAAC;IA8BjG,sEAAsE;IACtE,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,sBAAsB,GAAG,sBAAsB;IAM3E;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,OAAO,EAAE,GAAG,EAAE,OAAO,GAAG,oBAAoB,CAAC,QAAQ,CAAC;IA0B9E;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,QAAQ,GAAG,OAAO,EAC/B,QAAQ,EAAE,sBAAsB,EAChC,KAAK,EAAE,2BAA2B,EAAE,EACpC,aAAa,EAAE,MAAM,GACpB,oBAAoB,CAAC,QAAQ,CAAC;IA4CjC;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CACpB,KAAK,EAAE,sBAAsB,GAAG,IAAI,GAAG,SAAS,EAChD,MAAM,EAAE,sBAAsB,GAAG,IAAI,GAAG,SAAS,EACjD,OAAO,GAAE;QAAE,iBAAiB,CAAC,EAAE,MAAM,CAAA;KAAO,GAC3C,4BAA4B;IA2C/B,OAAO,CAAC,MAAM,CAAC,SAAS;IAIxB,mFAAmF;IACnF,OAAO,CAAC,MAAM,CAAC,aAAa;IAe5B,sGAAsG;IACtG,OAAO,CAAC,MAAM,CAAC,KAAK;CAGrB"}

package/build/_modules/game/_collections/game-save.util.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DyFM_GameSave_Util = exports.DYFM_GAME_SAVE_FORMAT = void 0;
+const error_control_model_1 = require("../../../_models/control-models/error.control-model");
+/** The only envelope format this version reads and writes. */
+exports.DYFM_GAME_SAVE_FORMAT = 'dyfm-game-save/1';
+/**
+ * BFR-WARFACTORY-011 — deterministic, headless game-save operations: seal (checksum), parse (corruption + format
+ * check), migrate (ordered replay with a typed failure) and conflict resolution (lineage first, then a time window).
+ * Nothing here reads a clock, a platform or a credential.
+ */
+class DyFM_GameSave_Util {
+    /**
+     * FNV-1a (32-bit, hex) over the CANONICAL JSON of the payload (object keys sorted) — the same payload always gives
+     * the same checksum, whatever the key order. A corruption / identity check, NOT a security signature.
+     */
+    static checksum(payload) {
+        const text = DyFM_GameSave_Util.canonicalJson(payload);
+        let hash = 0x811c9dc5;
+        for (let i = 0; i < text.length; i++) {
+            hash ^= text.charCodeAt(i);
+            hash = Math.imul(hash, 0x01000193) >>> 0;
+        }
+        return hash.toString(16).padStart(8, '0');
+    }
+    /** Builds an envelope with the format and the computed checksum. Invalid input throws (`DYFM-GAME-SAVE-SEAL`). */
+    static seal(input) {
+        if (!input?.gameId?.trim() || !input.slotId?.trim() || !DyFM_GameSave_Util.isVersion(input.schemaVersion)
+            || !Number.isFinite(input.savedAtMs) || input.payload === undefined) {
+            throw new error_control_model_1.DyFM_Error({
+                message: 'DyFM_GameSave: seal needs gameId, slotId, an integer schemaVersion ≥ 1, a finite savedAtMs and a payload',
+                errorCode: 'DYFM-GAME-SAVE-SEAL',
+                issuerService: 'DyFM_GameSave_Util',
+            });
+        }
+        const envelope = {
+            format: exports.DYFM_GAME_SAVE_FORMAT,
+            gameId: input.gameId,
+            slotId: input.slotId,
+            schemaVersion: input.schemaVersion,
+            savedAtMs: input.savedAtMs,
+            checksum: DyFM_GameSave_Util.checksum(input.payload),
+            payload: input.payload,
+        };
+        if (input.parentChecksum) {
+            envelope.parentChecksum = input.parentChecksum;
+        }
+        if (input.label) {
+            envelope.label = input.label;
+        }
+        return envelope;
+    }
+    /** The metadata of an envelope (what `list` returns — no payload). */
+    static metadataOf(envelope) {
+        const { payload: _payload, ...metadata } = envelope;
+        return metadata;
+    }
+    /**
+     * Validates a RAW read (anything an adapter returned): shape, format, field types and the checksum. A corrupt or
+     * foreign save is a typed failure — never a half-loaded game.
+     */
+    static parse(raw) {
+        const fail = (code, message) => ({ ok: false, code: code, message: message, appliedSteps: [] });
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            return fail('not-an-object', 'the save is not an object');
+        }
+        const envelope = raw;
+        if (envelope.format !== exports.DYFM_GAME_SAVE_FORMAT) {
+            return fail('unknown-format', `unknown save format: ${String(envelope.format)}`);
+        }
+        if (typeof envelope.gameId !== 'string' || typeof envelope.slotId !== 'string'
+            || !DyFM_GameSave_Util.isVersion(envelope.schemaVersion) || !Number.isFinite(envelope.savedAtMs)
+            || typeof envelope.checksum !== 'string' || !('payload' in envelope)) {
+            return fail('invalid-field', 'the save is missing or has an invalid gameId / slotId / schemaVersion / savedAtMs / '
+                + 'checksum / payload');
+        }
+        if (DyFM_GameSave_Util.checksum(envelope.payload) !== envelope.checksum) {
+            return fail('checksum-mismatch', `the payload does not match its checksum (${envelope.checksum}) — corrupt save`);
+        }
+        return { ok: true, envelope: envelope, appliedSteps: [] };
+    }
+    /**
+     * Replays the migration steps from the envelope's `schemaVersion` up to `targetVersion`, step by step, on a COPY of
+     * the payload; the result is re-sealed (same slot, time and lineage). A save NEWER than the target, a gap in the
+     * chain or a throwing step is a typed failure and the input is untouched.
+     */
+    static migrate(envelope, steps, targetVersion) {
+        const applied = [];
+        const fail = (code, message) => ({ ok: false, code: code, message: message, appliedSteps: [...applied] });
+        if (steps.some((step) => !(step.to > step.from))) {
+            return fail('invalid-step', 'every migration step must go forward (to > from)');
+        }
+        if (envelope.schemaVersion > targetVersion) {
+            return fail('future-version', `save schema ${envelope.schemaVersion} is newer than this game (${targetVersion}) — `
+                + 'an older build must not load it');
+        }
+        let version = envelope.schemaVersion;
+        let payload = DyFM_GameSave_Util.clone(envelope.payload);
+        while (version < targetVersion) {
+            const step = steps.find((candidate) => candidate.from === version);
+            if (!step || step.to > targetVersion) {
+                return fail('missing-step', `no migration step from schema ${version} toward ${targetVersion}`);
+            }
+            try {
+                payload = step.migrate(payload);
+            }
+            catch (err) {
+                return fail('step-failed', `migration ${step.from}→${step.to} failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            applied.push(`${step.from}→${step.to}`);
+            version = step.to;
+        }
+        const migrated = {
+            ...envelope,
+            schemaVersion: version,
+            payload: payload,
+            checksum: DyFM_GameSave_Util.checksum(payload),
+        };
+        return { ok: true, envelope: migrated, appliedSteps: applied };
+    }
+    /**
+     * Deterministic local ↔ remote decision for ONE slot:
+     * none / one side missing → the existing one · same checksum → `in-sync` · proven descent (one side's
+     * `parentChecksum` is the other's checksum) → the descendant · both carry lineage but neither descends from the
+     * other → `ask-user` (a true divergence: picking one silently LOSES progress) · no lineage (legacy saves) → within
+     * `ambiguityWindowMs` `ask-user`, otherwise the newer one.
+     */
+    static resolveConflict(local, remote, options = {}) {
+        if (!local && !remote) {
+            return { decision: 'none', reason: 'no save on either side' };
+        }
+        if (!remote) {
+            return { decision: 'use-local', reason: 'only the local save exists' };
+        }
+        if (!local) {
+            return { decision: 'use-remote', reason: 'only the remote save exists' };
+        }
+        if (local.gameId !== remote.gameId || local.slotId !== remote.slotId) {
+            throw new error_control_model_1.DyFM_Error({
+                message: `DyFM_GameSave: resolveConflict compares ONE slot — got ${local.gameId}/${local.slotId} vs `
+                    + `${remote.gameId}/${remote.slotId}`,
+                errorCode: 'DYFM-GAME-SAVE-SLOT-MISMATCH',
+                issuerService: 'DyFM_GameSave_Util',
+            });
+        }
+        if (local.checksum === remote.checksum) {
+            return { decision: 'in-sync', reason: 'identical payloads' };
+        }
+        if (local.parentChecksum === remote.checksum) {
+            return { decision: 'use-local', reason: 'the local save was made from the remote one' };
+        }
+        if (remote.parentChecksum === local.checksum) {
+            return { decision: 'use-remote', reason: 'the remote save was made from the local one' };
+        }
+        if (local.parentChecksum && remote.parentChecksum) {
+            return { decision: 'ask-user', reason: 'both sides progressed separately (diverged) — either choice loses progress' };
+        }
+        const windowMs = options.ambiguityWindowMs ?? 30_000;
+        const gap = local.savedAtMs - remote.savedAtMs;
+        if (Math.abs(gap) <= windowMs) {
+            return { decision: 'ask-user', reason: `no lineage and saved within ${windowMs} ms of each other` };
+        }
+        return gap > 0
+            ? { decision: 'use-local', reason: 'no lineage; the local save is newer' }
+            : { decision: 'use-remote', reason: 'no lineage; the remote save is newer' };
+    }
+    static isVersion(value) {
+        return typeof value === 'number' && Number.isInteger(value) && value >= 1;
+    }
+    /** JSON with sorted object keys (arrays keep their order) — the checksum input. */
+    static canonicalJson(value) {
+        return JSON.stringify(value, (_key, item) => {
+            if (item && typeof item === 'object' && !Array.isArray(item)) {
+                return Object.keys(item).sort()
+                    .reduce((sorted, key) => {
+                    sorted[key] = item[key];
+                    return sorted;
+                }, {});
+            }
+            return item;
+        }) ?? 'undefined';
+    }
+    /** A deep copy for the migration replay (a step must not be able to change the caller's envelope). */
+    static clone(value) {
+        return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+    }
+}
+exports.DyFM_GameSave_Util = DyFM_GameSave_Util;
+//# sourceMappingURL=game-save.util.js.map

package/build/_modules/game/_collections/game-save.util.js.map

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

package/build/_modules/game/_models/build-reservation.interface.d.ts

@@ -0,0 +1,70 @@
+/**
+ * BFR-WARFACTORY-012 (scope extension ①–②) — placement preview + reservation with escrow. Game-specific resources
+ * (drones, a hammer, the player's position) stay OUT: they are the game's extension, not these models.
+ */
+/** ① Why a placement is invalid — a reason, never a bare `false`. */
+export interface DyFM_PlacementReason {
+    /** Stable code (e.g. `blocked`, `out-of-bounds`, `insufficient-resources`). */
+    code: string;
+    /** Human text for the UI. */
+    message: string;
+}
+/** ① A placement preview: where, how big, is it valid, and why not. */
+export interface DyFM_PlacementPreview<TPosition = {
+    x: number;
+    y: number;
+}> {
+    position: TPosition;
+    footprint: {
+        width: number;
+        height: number;
+    };
+    valid: boolean;
+    /** Empty when valid; every failed rule otherwise (all of them, not just the first). */
+    reasons: DyFM_PlacementReason[];
+}
+/** ① One placement rule: `null` = fine, a reason = why not. */
+export type DyFM_PlacementRule<TPosition = {
+    x: number;
+    y: number;
+}> = (candidate: {
+    position: TPosition;
+    footprint: {
+        width: number;
+        height: number;
+    };
+}) => DyFM_PlacementReason | null;
+/** ② One held cost line: how much of which resource, taken FROM WHERE (the key to restoring the original state). */
+export interface DyFM_ReservedCostSource {
+    resource: string;
+    amount: number;
+    /** Where it was taken from (a storage, a building, the player's inventory …). */
+    sourceId: string;
+}
+/** ② What happens to the held cost when the reservation is cancelled. */
+export interface DyFM_RefundPolicy {
+    /** Share returned on cancel before any progress (0..1). Default: `1`. */
+    cancelRefundRatio?: number;
+}
+/** ② A reservation: the reserved location + the cost in escrow, per source. */
+export interface DyFM_BuildReservation<TPosition = {
+    x: number;
+    y: number;
+}> {
+    reservationId: string;
+    position: TPosition;
+    footprint: {
+        width: number;
+        height: number;
+    };
+    reservedCostSources: DyFM_ReservedCostSource[];
+    refundPolicy: Required<DyFM_RefundPolicy>;
+    status: 'held' | 'committed' | 'released';
+}
+/** ② A refund line, back to its ORIGINAL source. */
+export interface DyFM_RefundLine {
+    resource: string;
+    amount: number;
+    sourceId: string;
+}
+//# sourceMappingURL=build-reservation.interface.d.ts.map

package/build/_modules/game/_models/build-reservation.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-reservation.interface.d.ts","sourceRoot":"","sources":["../../../../src/_modules/game/_models/build-reservation.interface.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qEAAqE;AACrE,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,uEAAuE;AACvE,MAAM,WAAW,qBAAqB,CAAC,SAAS,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE;IACzE,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,KAAK,EAAE,OAAO,CAAC;IACf,uFAAuF;IACvF,OAAO,EAAE,oBAAoB,EAAE,CAAC;CACjC;AAED,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,CAAC,SAAS,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,IACjE,CAAC,SAAS,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,KAAK,oBAAoB,GAAG,IAAI,CAAC;AAEpH,oHAAoH;AACpH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB,CAAC,SAAS,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE;IACzE,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,mBAAmB,EAAE,uBAAuB,EAAE,CAAC;IAC/C,YAAY,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IAC1C,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,CAAC;CAC3C;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB"}

package/build/_modules/game/_models/build-reservation.interface.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * BFR-WARFACTORY-012 (scope extension ①–②) — placement preview + reservation with escrow. Game-specific resources
+ * (drones, a hammer, the player's position) stay OUT: they are the game's extension, not these models.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=build-reservation.interface.js.map

package/build/_modules/game/_models/build-reservation.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-reservation.interface.js","sourceRoot":"","sources":["../../../../src/_modules/game/_models/build-reservation.interface.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

package/build/_modules/game/_models/game-save.interface.d.ts

@@ -0,0 +1,76 @@
+/**
+ * BFR-WARFACTORY-011 — headless game-save contracts. No provider credential, platform binding or game payload shape
+ * lives here: the payload is opaque (`TPayload`, typically the serialized game state), adapters are the game's.
+ */
+/** The envelope format marker — an unknown one is rejected, never guessed. */
+export type DyFM_GameSave_Format_Type = 'dyfm-game-save/1';
+/** The list / conflict view of a save: everything except the payload. */
+export interface DyFM_GameSave_Metadata {
+    format: DyFM_GameSave_Format_Type;
+    /** The game (one envelope format serves several games). */
+    gameId: string;
+    /** The save slot (the adapter-level key). */
+    slotId: string;
+    /** The GAME's payload schema version (integer ≥ 1) — what migrations step through. */
+    schemaVersion: number;
+    /** When it was saved (Unix ms, from the caller's clock). */
+    savedAtMs: number;
+    /** Deterministic checksum of the payload (corruption + identity). */
+    checksum: string;
+    /** The checksum of the save this one was made FROM (lineage) — lets conflict resolution prove descent. */
+    parentChecksum?: string;
+    /** Display label (optional). */
+    label?: string;
+}
+/** A full save: metadata + the opaque payload. */
+export interface DyFM_GameSave_Envelope<TPayload = unknown> extends DyFM_GameSave_Metadata {
+    payload: TPayload;
+}
+/** What a game passes to `seal` — the checksum and the format are computed, never hand-written. */
+export interface DyFM_GameSave_SealInput<TPayload = unknown> {
+    gameId: string;
+    slotId: string;
+    schemaVersion: number;
+    savedAtMs: number;
+    payload: TPayload;
+    parentChecksum?: string;
+    label?: string;
+}
+/** A storage adapter (localStorage, file system, Steam, cloud …) — implemented by the game, not here. */
+export interface DyFM_GameSave_Adapter_Interface<TPayload = unknown> {
+    /** Writes (overwrites) the slot. */
+    write(envelope: DyFM_GameSave_Envelope<TPayload>): Promise<void>;
+    /** Reads a slot; `null` when it does not exist. Callers should pass the raw result through `parse`. */
+    read(slotId: string): Promise<unknown>;
+    /** Lists the slots' metadata (no payloads — the list UI must not load every save into memory). */
+    list(): Promise<DyFM_GameSave_Metadata[]>;
+    /** Deletes a slot; idempotent. */
+    delete(slotId: string): Promise<void>;
+}
+/** One migration step: the payload of `from` → the payload of `to` (`to` > `from`). Pure; must not mutate its input. */
+export interface DyFM_GameSave_MigrationStep {
+    from: number;
+    to: number;
+    migrate: (payload: unknown) => unknown;
+}
+/** Why a parse / migration failed — a stable code for the game's UI and telemetry. */
+export type DyFM_GameSave_Failure_Type = 'not-an-object' | 'unknown-format' | 'invalid-field' | 'checksum-mismatch' | 'future-version' | 'missing-step' | 'invalid-step' | 'step-failed';
+/** The result of `parse` / `migrate`. */
+export type DyFM_GameSave_Result<TPayload = unknown> = {
+    ok: true;
+    envelope: DyFM_GameSave_Envelope<TPayload>;
+    appliedSteps: string[];
+} | {
+    ok: false;
+    code: DyFM_GameSave_Failure_Type;
+    message: string;
+    appliedSteps: string[];
+};
+/** The deterministic conflict decision (the game maps `ask-user` to its conflict dialog). */
+export type DyFM_GameSave_ConflictDecision_Type = 'in-sync' | 'use-local' | 'use-remote' | 'ask-user' | 'none';
+/** The decision + why (for logs and the dialog). */
+export interface DyFM_GameSave_ConflictResult {
+    decision: DyFM_GameSave_ConflictDecision_Type;
+    reason: string;
+}
+//# sourceMappingURL=game-save.interface.d.ts.map

package/build/_modules/game/_models/game-save.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-save.interface.d.ts","sourceRoot":"","sources":["../../../../src/_modules/game/_models/game-save.interface.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,8EAA8E;AAC9E,MAAM,MAAM,yBAAyB,GAAG,kBAAkB,CAAC;AAE3D,yEAAyE;AACzE,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,yBAAyB,CAAC;IAClC,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,0GAA0G;IAC1G,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,kDAAkD;AAClD,MAAM,WAAW,sBAAsB,CAAC,QAAQ,GAAG,OAAO,CAAE,SAAQ,sBAAsB;IACxF,OAAO,EAAE,QAAQ,CAAC;CACnB;AAED,mGAAmG;AACnG,MAAM,WAAW,uBAAuB,CAAC,QAAQ,GAAG,OAAO;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,QAAQ,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,yGAAyG;AACzG,MAAM,WAAW,+BAA+B,CAAC,QAAQ,GAAG,OAAO;IACjE,oCAAoC;IACpC,KAAK,CAAC,QAAQ,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,uGAAuG;IACvG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,kGAAkG;IAClG,IAAI,IAAI,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAAC;IAC1C,kCAAkC;IAClC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,wHAAwH;AACxH,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;CACxC;AAED,sFAAsF;AACtF,MAAM,MAAM,0BAA0B,GAClC,eAAe,GAAG,gBAAgB,GAAG,eAAe,GAAG,mBAAmB,GAC1E,gBAAgB,GAAG,cAAc,GAAG,cAAc,GAAG,aAAa,CAAC;AAEvE,yCAAyC;AACzC,MAAM,MAAM,oBAAoB,CAAC,QAAQ,GAAG,OAAO,IAC/C;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,GAChF;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,0BAA0B,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE7F,6FAA6F;AAC7F,MAAM,MAAM,mCAAmC,GAAG,SAAS,GAAG,WAAW,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;AAE/G,oDAAoD;AACpD,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,mCAAmC,CAAC;IAC9C,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/build/_modules/game/_models/game-save.interface.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * BFR-WARFACTORY-011 — headless game-save contracts. No provider credential, platform binding or game payload shape
+ * lives here: the payload is opaque (`TPayload`, typically the serialized game state), adapters are the game's.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=game-save.interface.js.map

package/build/_modules/game/_models/game-save.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-save.interface.js","sourceRoot":"","sources":["../../../../src/_modules/game/_models/game-save.interface.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

package/build/_modules/game/_models/viewport.control-model.d.ts

@@ -0,0 +1,58 @@
+import { DyFM_Viewport_Config, DyFM_Viewport_Point, DyFM_Viewport_State } from './viewport.interface';
+/**
+ * BFR-WARFACTORY-013 — framework-independent zoom / pan viewport. It is deliberately NOT "the camera": the same model
+ * drives a world canvas and a DOM panel (e.g. a zoomable tech tree). Input handling (pointer, wheel, keys) belongs to
+ * a UI adapter that calls these methods.
+ *
+ * - `worldToScreen` / `screenToWorld` — the only transform; the screen centre shows `center`.
+ * - `zoomAt(screenPoint, factor)` — the world point UNDER the pointer stays under the pointer (wheel / pinch feel).
+ * - `panByScreen(dx, dy)` — drag: the content follows the pointer at any zoom.
+ * - `move(direction, speed, elapsedSeconds)` — elapsed-time keyboard panning; each step is capped
+ *   (`maxMoveStepSeconds`), so a hitch never makes the camera jump; speed is in SCREEN px/s (same feel at any zoom).
+ * - Zoom is clamped to [minZoom, maxZoom], the centre to `worldBounds`; non-finite input is ignored, never stored.
+ */
+export declare class DyFM_Viewport_ControlModel {
+    private screenWidth;
+    private screenHeight;
+    private readonly minZoom;
+    private readonly maxZoom;
+    private readonly bounds;
+    private readonly stepFactor;
+    private readonly maxMoveStep;
+    private centerPoint;
+    private zoomValue;
+    /** Creates the viewport; an invalid configuration throws `DYFM-VIEWPORT-CONFIG`. */
+    constructor(config: DyFM_Viewport_Config);
+    /** The world point shown at the screen centre. */
+    get center(): DyFM_Viewport_Point;
+    /** Screen pixels per world unit. */
+    get zoom(): number;
+    /** World → screen pixels. */
+    worldToScreen(world: DyFM_Viewport_Point): DyFM_Viewport_Point;
+    /** Screen pixels → world. */
+    screenToWorld(screen: DyFM_Viewport_Point): DyFM_Viewport_Point;
+    /** Sets the zoom (clamped), keeping the centre. */
+    setZoom(zoom: number): void;
+    /** Zooms by `factor` keeping the world point under `screenPoint` fixed on screen (then clamps). */
+    zoomAt(screenPoint: DyFM_Viewport_Point, factor: number): void;
+    /** `steps` notches (+ in, − out) at `screenPoint` (default: the screen centre). */
+    zoomStep(steps: number, screenPoint?: DyFM_Viewport_Point): void;
+    /** Drag by a screen delta: the content moves WITH the pointer. */
+    panByScreen(dx: number, dy: number): void;
+    /**
+     * Elapsed-time panning (keyboard): `direction` is normalised, `speedScreenPxPerSecond` is screen speed, the elapsed
+     * time is capped at `maxMoveStepSeconds` per call. Returns the world distance actually moved.
+     */
+    move(direction: DyFM_Viewport_Point, speedScreenPxPerSecond: number, elapsedSeconds: number): number;
+    /** Centres on a world point (clamped). */
+    centerOn(world: DyFM_Viewport_Point): void;
+    /** The screen changed size (e.g. a window resize); the centre stays. */
+    resize(screenWidth: number, screenHeight: number): void;
+    /** Save state. */
+    exportState(): DyFM_Viewport_State;
+    /** Restore state (clamped to THIS viewport's limits); `false` and no change when unreadable. */
+    importState(state: unknown): boolean;
+    private clampZoom;
+    private clampCenter;
+}
+//# sourceMappingURL=viewport.control-model.d.ts.map

package/build/_modules/game/_models/viewport.control-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport.control-model.d.ts","sourceRoot":"","sources":["../../../../src/_modules/game/_models/viewport.control-model.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEtG;;;;;;;;;;;GAWG;AACH,qBAAa,0BAA0B;IACrC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAC7D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,SAAS,CAAa;IAE9B,oFAAoF;gBACxE,MAAM,EAAE,oBAAoB;IAyBxC,kDAAkD;IAClD,IAAI,MAAM,IAAI,mBAAmB,CAEhC;IAED,oCAAoC;IACpC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,6BAA6B;IAC7B,aAAa,CAAC,KAAK,EAAE,mBAAmB,GAAG,mBAAmB;IAO9D,6BAA6B;IAC7B,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB;IAO/D,mDAAmD;IACnD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM3B,mGAAmG;IACnG,MAAM,CAAC,WAAW,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAe9D,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,mBAAmB,GAAG,IAAI;IAMhE,kEAAkE;IAClE,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IASzC;;;OAGG;IACH,IAAI,CAAC,SAAS,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM;IAoBpG,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI;IAM1C,wEAAwE;IACxE,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IAOvD,kBAAkB;IAClB,WAAW,IAAI,mBAAmB;IAIlC,gGAAgG;IAChG,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAapC,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,WAAW;CAUpB"}