@futdevpro/fsm-dynamo 1.20.92 → 1.20.93

package/build-esm/_modules/game/_models/audio-mixer.control-model.js

@@ -0,0 +1,337 @@
+import { DyFM_Error } from '../../../_models/control-models/error.control-model';
+import { DyFM_AudioScale_Util } from '../_collections/audio-scale.util';
+/**
+ * **Csatorna- es skala-agnosztikus** jatek-audio mixer: a projekt deklaralja a sajat
+ * csatornait es szamabrazolasat, a modell pedig kezeli az allapotot es kiszamolja az
+ * effektiv hangerot.
+ *
+ * **Miert letezik a `DyFM_AudioMixer_Util` (round-1) mellett:** az a util negy FIX csatornara
+ * (`music` / `ambience` / `effects`) es `0..1` skalara epul. Ez a Prototyper harom prototipusara
+ * igaz, de a **Hero Coordinator** csatornai `music` / `dialog` / `interface`, az ertekei pedig
+ * `0-100` egeszek. A fix alak ott csatorna-vesztessel es kotelezo adat-migracioval jarna.
+ * Ez a modell mindkettot kiszolgalja; a round-1 alak `createClassic()` presetkent tovabb el.
+ *
+ * **Rendereles-agnosztikus:** NINCS DOM, Web Audio, Angular vagy Node fuggese. A tenyleges
+ * lejatszas (HTMLAudioElement, Web Audio `GainNode`, vagy barmi mas) a fogyasztoe — ez a
+ * **modell + szamitas**.
+ *
+ * **Hasznalat (Hero Coordinator-stilus, 0-100 egesz):**
+ * ```typescript
+ * const mixer = DyFM_AudioMixer_ControlModel.createPercent(['music', 'dialog', 'interface'], {
+ *   music: 36, dialog: 84, interface: 68,
+ * }, 72);
+ *
+ * let state = mixer.merge(JSON.parse(localStorage.getItem('audio') ?? 'null'));
+ * gainNode.gain.value = mixer.getEffectiveVolume(state, 'interface'); // MINDIG 0..1
+ *
+ * state = mixer.withChannelVolume(state, 'music', 40); // a sajat skalajan adjuk meg
+ * localStorage.setItem('audio', JSON.stringify(state));
+ * ```
+ *
+ * **Hasznalat (Prototyper-stilus, 0..1):**
+ * ```typescript
+ * const mixer = DyFM_AudioMixer_ControlModel.createClassic();
+ * const state = DyFM_AudioMixer_ControlModel.fromClassicSettings(legacySettings);
+ * ```
+ */
+export class DyFM_AudioMixer_ControlModel {
+    /** A `master` fenntartott nev — nem lehet sima csatorna, mert minden csatornara szorzodik. */
+    static masterChannel = 'master';
+    /** A validalt, sajat peldany-config (a hivo altal atadott objektumtol fuggetlen masolat). */
+    config;
+    /**
+     * A config validalasa **konstruktor-idoben** tortenik: egy elgepelt csatorna-nev vagy hianyzo
+     * skala igy a jatek inditasakor derul ki, nem hangleajatszas kozben.
+     */
+    constructor(config) {
+        if (!config || !Array.isArray(config.channels) || !config.channels.length) {
+            throw new DyFM_Error({
+                errorCode: 'DYFM-AUDIO-MIXER-001',
+                message: 'DyFM_AudioMixer_ControlModel: config.channels must be a non-empty string array',
+                additionalContent: { config: config },
+            });
+        }
+        const seen = [];
+        for (const channel of config.channels) {
+            if (typeof channel !== 'string' || !channel.length) {
+                throw new DyFM_Error({
+                    errorCode: 'DYFM-AUDIO-MIXER-002',
+                    message: 'DyFM_AudioMixer_ControlModel: every channel name must be a non-empty string',
+                    additionalContent: { channels: config.channels },
+                });
+            }
+            if (channel === DyFM_AudioMixer_ControlModel.masterChannel) {
+                throw new DyFM_Error({
+                    errorCode: 'DYFM-AUDIO-MIXER-003',
+                    message: 'DyFM_AudioMixer_ControlModel: "master" is reserved and must not be listed in channels',
+                    additionalContent: { channels: config.channels },
+                });
+            }
+            if (seen.includes(channel)) {
+                throw new DyFM_Error({
+                    errorCode: 'DYFM-AUDIO-MIXER-004',
+                    message: 'DyFM_AudioMixer_ControlModel: duplicate channel name',
+                    additionalContent: { channel: channel, channels: config.channels },
+                });
+            }
+            seen.push(channel);
+        }
+        const scale = config.scale && typeof config.scale.max === 'number'
+            ? { max: config.scale.max, integer: config.scale.integer === true }
+            : DyFM_AudioScale_Util.getUnitScale();
+        this.config = {
+            channels: [...config.channels],
+            scale: scale,
+            defaults: config.defaults ? { ...config.defaults } : {},
+            defaultMaster: config.defaultMaster,
+            defaultChannelVolume: config.defaultChannelVolume,
+            defaultPlayWhenUnfocused: config.defaultPlayWhenUnfocused === true,
+        };
+    }
+    /**
+     * A round-1 `DyFM_AudioMixer_Settings` alakjaval egyenerteku mixer (`music` / `ambience` /
+     * `effects`, `0..1` skala, 0.8 default). A Prototyper-stilusu fogyasztoknak.
+     */
+    static createClassic() {
+        return new DyFM_AudioMixer_ControlModel({
+            channels: ['music', 'ambience', 'effects'],
+            scale: DyFM_AudioScale_Util.getUnitScale(),
+            defaultMaster: DyFM_AudioScale_Util.defaultRatio,
+            defaultChannelVolume: DyFM_AudioScale_Util.defaultRatio,
+        });
+    }
+    /**
+     * `0-100` egesz skalaju mixer tetszoleges csatorna-keszlettel — a Hero Coordinator-stilusu
+     * fogyasztoknak, akik igy **adat-migracio nelkul** vehetik hasznalatba a bedrock modellt.
+     */
+    static createPercent(channels, defaults, defaultMaster) {
+        return new DyFM_AudioMixer_ControlModel({
+            channels: channels,
+            scale: DyFM_AudioScale_Util.getPercentScale(),
+            defaults: defaults,
+            defaultMaster: defaultMaster,
+        });
+    }
+    /** A round-1 fix alakot atalakitja a nyitott allapot-alakra (migracios hid). */
+    static fromClassicSettings(settings) {
+        const safe = settings ?? {};
+        const scale = DyFM_AudioScale_Util.getUnitScale();
+        return {
+            master: DyFM_AudioScale_Util.toUnit(safe.master, scale),
+            channels: {
+                music: DyFM_AudioScale_Util.toUnit(safe.music, scale),
+                ambience: DyFM_AudioScale_Util.toUnit(safe.ambience, scale),
+                effects: DyFM_AudioScale_Util.toUnit(safe.effects, scale),
+            },
+            muted: safe.muted === true,
+            // Statikus metodus -> nincs peldany-config, ezert a GLOBALIS default (`false`) ervenyes.
+            playWhenUnfocused: safe.playWhenUnfocused === true,
+        };
+    }
+    /**
+     * A nyitott allapot-alakot visszaalakitja a round-1 fix alakra (migracios hid visszafele).
+     *
+     * **Peldany-metodus**, mert a helyes konverziohoz ismerni kell a peldany skalajat: egy
+     * `0-100`-as allapotot igy is `0..1`-re normalizal, ahogy a round-1 alak varja. (Statikus
+     * valtozatban ez nemaan rossz erteket adna.)
+     *
+     * A klasszikus keszleten kivuli csatornak (pl. `dialog`) **elvesznek** — ez a round-1 alak
+     * korlatja, nem a konverzioe.
+     */
+    toClassicSettings(state) {
+        const safe = this.merge(state);
+        const scale = this.config.scale;
+        const classic = {
+            master: DyFM_AudioScale_Util.toUnit(safe.master, scale),
+            music: DyFM_AudioScale_Util.toUnit(safe.channels['music'], scale),
+            ambience: DyFM_AudioScale_Util.toUnit(safe.channels['ambience'], scale),
+            effects: DyFM_AudioScale_Util.toUnit(safe.channels['effects'], scale),
+            muted: safe.muted === true,
+        };
+        // A kapcsolot CSAK bekapcsolt allapotban irjuk ki. Igy a round-1 alakot mar hasznalo
+        // projektek payloadja valtozatlan marad (nem jelenik meg benne egy uj `false` mezo),
+        // a bekapcsolt allapot viszont tulel egy oda-vissza konverziot.
+        if (safe.playWhenUnfocused) {
+            classic.playWhenUnfocused = true;
+        }
+        return classic;
+    }
+    /** A peldany configja (masolat — a mutalasa nem hat vissza a modellre). */
+    getConfig() {
+        return {
+            channels: [...this.config.channels],
+            scale: { max: this.config.scale.max, integer: this.config.scale.integer },
+            defaults: { ...this.config.defaults },
+            defaultMaster: this.config.defaultMaster,
+            defaultChannelVolume: this.config.defaultChannelVolume,
+        };
+    }
+    /** A deklaralt csatorna-nevek (a `master` nelkul). */
+    getChannels() {
+        return [...this.config.channels];
+    }
+    /** Igaz, ha a nev a deklaralt csatornak kozott van (a `master` NEM az). */
+    hasChannel(channel) {
+        return this.config.channels.includes(channel);
+    }
+    /**
+     * Alapertelmezett allapot a **sajat skalan**. Minden hivas UJ objektumot ad vissza, hogy a
+     * hivo szabadon mutalhassa.
+     */
+    getDefaults() {
+        const channels = {};
+        for (const channel of this.config.channels) {
+            channels[channel] = this.getDefaultChannelVolume(channel);
+        }
+        return {
+            master: this.getDefaultMaster(),
+            channels: channels,
+            muted: false,
+            playWhenUnfocused: this.config.defaultPlayWhenUnfocused === true,
+        };
+    }
+    /**
+     * Reszleges / hianyzo / serult allapotbol teljes, ervenyes allapotot allit elo: a hianyzo
+     * csatornak a defaultot kapjak, az ertekek a sajat skalara szorulnak.
+     *
+     * **Ez a migracios biztositek:** egy regi payload, ami meg nem ismert egy kesobb bevezetett
+     * csatornat, igy is betoltheto marad. A **nem deklaralt** csatornak kiesnek — igy egy
+     * eltavolitott csatorna nem szivarog vissza a mentesbol. Serult (NaN / nem-szam) ertek eseten
+     * a csatorna DEFAULT-jat kapja, nem 0-t — egy hibas mentes ne nemitson el csendben.
+     *
+     * **Figyelem:** ez a nyitott (`channels` rekord) alakot varja. A round-1 LAPOS alakot
+     * (`{ master, music, ambience, effects, muted }`) eloszor a `fromClassicSettings()`-szel
+     * kell atalakitani — kulonben a csatornak a defaultot kapjak.
+     */
+    merge(partial) {
+        const defaults = this.getDefaults();
+        if (!partial) {
+            return defaults;
+        }
+        const source = partial.channels ?? {};
+        const channels = {};
+        for (const channel of this.config.channels) {
+            const raw = source[channel];
+            channels[channel] = raw === undefined || raw === null
+                ? defaults.channels[channel]
+                : DyFM_AudioScale_Util.clampToScale(raw, this.config.scale, defaults.channels[channel]);
+        }
+        const master = partial.master === undefined || partial.master === null
+            ? defaults.master
+            : DyFM_AudioScale_Util.clampToScale(partial.master, this.config.scale, defaults.master);
+        // A hianyzo `playWhenUnfocused` a CONFIG alapertelmezeset kapja, NEM vakon `false`-t:
+        // igy egy regi (mezo nelkuli) mentes betoltese nem irja felul a jatek sajat dontetet.
+        const playWhenUnfocused = partial.playWhenUnfocused === undefined || partial.playWhenUnfocused === null
+            ? defaults.playWhenUnfocused
+            : partial.playWhenUnfocused === true;
+        return {
+            master: master,
+            channels: channels,
+            muted: partial.muted === true,
+            playWhenUnfocused: playWhenUnfocused,
+        };
+    }
+    /**
+     * Egy csatorna **effektiv** hangereje `0..1`-ben — ezt varja a `HTMLAudioElement.volume` es a
+     * Web Audio `GainNode.gain.value`, fuggetlenul attol, milyen skalan tarol a projekt.
+     *
+     * A csatorna sajat erteke szorozva a master-rel; nemitas eseten mindig 0. A `'master'` nevre
+     * a master sajat (normalizalt) erteket adja vissza, nem negyzetre emelve.
+     *
+     * **Dob**, ha a csatorna nincs deklaralva — egy elgepelt csatorna-nev igy nem nemul el
+     * csendben, hanem azonnal kiderul (`core-rich-error-handling`).
+     */
+    getEffectiveVolume(state, channel) {
+        if (channel !== DyFM_AudioMixer_ControlModel.masterChannel && !this.hasChannel(channel)) {
+            throw new DyFM_Error({
+                errorCode: 'DYFM-AUDIO-MIXER-005',
+                message: 'DyFM_AudioMixer_ControlModel.getEffectiveVolume: unknown channel',
+                additionalContent: { channel: channel, declaredChannels: this.config.channels },
+            });
+        }
+        const safe = this.merge(state);
+        if (safe.muted) {
+            return 0;
+        }
+        const masterUnit = DyFM_AudioScale_Util.toUnit(safe.master, this.config.scale);
+        if (channel === DyFM_AudioMixer_ControlModel.masterChannel) {
+            return masterUnit;
+        }
+        const channelUnit = DyFM_AudioScale_Util.toUnit(safe.channels[channel], this.config.scale);
+        return DyFM_AudioScale_Util.clampUnit(channelUnit * masterUnit);
+    }
+    /**
+     * Egy csatorna hangerejenek beallitasa a **sajat skalan** — UJ allapot-objektumot ad vissza
+     * (immutable update), hogy signal-/state-alapu tarolokban is biztonsagos legyen.
+     */
+    withChannelVolume(state, channel, volume) {
+        if (!this.hasChannel(channel)) {
+            throw new DyFM_Error({
+                errorCode: 'DYFM-AUDIO-MIXER-006',
+                message: 'DyFM_AudioMixer_ControlModel.withChannelVolume: unknown channel',
+                additionalContent: { channel: channel, declaredChannels: this.config.channels },
+            });
+        }
+        const next = this.merge(state);
+        next.channels[channel] = DyFM_AudioScale_Util.clampToScale(volume, this.config.scale);
+        return next;
+    }
+    /** A master beallitasa a **sajat skalan** — UJ allapot-objektumot ad vissza. */
+    withMasterVolume(state, volume) {
+        const next = this.merge(state);
+        next.master = DyFM_AudioScale_Util.clampToScale(volume, this.config.scale);
+        return next;
+    }
+    /** Nemitas beallitasa — UJ allapot-objektumot ad vissza. */
+    withMuted(state, muted) {
+        const next = this.merge(state);
+        next.muted = muted === true;
+        return next;
+    }
+    /**
+     * A "szoljon-e hattervben" kapcsolo beallitasa — UJ allapot-objektumot ad vissza.
+     *
+     * A modell csak a SZANDEKOT tarolja; a tenyleges szuneteltetes a lejatszo-reteg dolga
+     * (`visibilitychange` / `blur`), mert ez a reteg DOM-fuggetlen.
+     */
+    withPlayWhenUnfocused(state, playWhenUnfocused) {
+        const next = this.merge(state);
+        next.playWhenUnfocused = playWhenUnfocused === true;
+        return next;
+    }
+    /** Ket allapot ertek szerinti egyezese (mentes-szukseg / change-detection dontesehez). */
+    isEqual(a, b) {
+        const left = this.merge(a);
+        const right = this.merge(b);
+        if (left.master !== right.master
+            || left.muted !== right.muted
+            || left.playWhenUnfocused !== right.playWhenUnfocused) {
+            return false;
+        }
+        for (const channel of this.config.channels) {
+            if (left.channels[channel] !== right.channels[channel]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /** A master alapertelmezese a sajat skalan (config, kulonben a maximum 80%-a). */
+    getDefaultMaster() {
+        if (typeof this.config.defaultMaster === 'number' && !Number.isNaN(this.config.defaultMaster)) {
+            return DyFM_AudioScale_Util.clampToScale(this.config.defaultMaster, this.config.scale);
+        }
+        return DyFM_AudioScale_Util.fromUnit(DyFM_AudioScale_Util.defaultRatio, this.config.scale);
+    }
+    /** Egy csatorna alapertelmezese a sajat skalan (per-csatorna, kulonben kozos, kulonben 80%). */
+    getDefaultChannelVolume(channel) {
+        const perChannel = (this.config.defaults ?? {})[channel];
+        if (typeof perChannel === 'number' && !Number.isNaN(perChannel)) {
+            return DyFM_AudioScale_Util.clampToScale(perChannel, this.config.scale);
+        }
+        if (typeof this.config.defaultChannelVolume === 'number'
+            && !Number.isNaN(this.config.defaultChannelVolume)) {
+            return DyFM_AudioScale_Util.clampToScale(this.config.defaultChannelVolume, this.config.scale);
+        }
+        return DyFM_AudioScale_Util.fromUnit(DyFM_AudioScale_Util.defaultRatio, this.config.scale);
+    }
+}

package/build-esm/_modules/game/_models/audio-scale.interface.js

@@ -0,0 +1 @@
+export {};

package/build-esm/_modules/game/_models/flying-effect.control-model.js

@@ -0,0 +1,212 @@
+import { DyFM_Error } from '../../../_models/control-models/error.control-model';
+/** Deterministic, renderer-independent lifecycle for short-lived game presentation effects. */
+export class DyFM_FlyingEffect_ControlModel {
+    maxItems;
+    defaultDurationMs;
+    defaultRisePx;
+    defaultStackGapPx;
+    items = [];
+    sequence = 0;
+    paused = false;
+    pauseStartedAtMs = null;
+    lastTimeMs = null;
+    spawnedCount = 0;
+    mergedCount = 0;
+    expiredCount = 0;
+    evictedCount = 0;
+    highWatermark = 0;
+    constructor(config = {}) {
+        this.maxItems = this.positiveInteger(config.maxItems ?? 100, 'maxItems', 'DYFM-FLYING-EFFECT-001');
+        this.defaultDurationMs = this.positive(config.defaultDurationMs ?? 1_400, 'defaultDurationMs');
+        this.defaultRisePx = this.nonNegative(config.defaultRisePx ?? 52, 'defaultRisePx');
+        this.defaultStackGapPx = this.nonNegative(config.defaultStackGapPx ?? 18, 'defaultStackGapPx');
+    }
+    spawn(command, nowMs) {
+        this.validateCommand(command);
+        const durationMs = this.positive(command.durationMs ?? this.defaultDurationMs, 'durationMs');
+        const risePx = this.nonNegative(command.risePx ?? this.defaultRisePx, 'risePx');
+        const stackGapPx = this.nonNegative(command.stackGapPx ?? this.defaultStackGapPx, 'stackGapPx');
+        const mergeKey = this.optionalKey(command.mergeKey, 'mergeKey');
+        const stackKey = this.resolveStackKey(command);
+        this.assertMonotonicTime(nowMs);
+        this.advanceTo(nowMs);
+        const effectiveNow = this.paused ? this.pauseStartedAtMs : nowMs;
+        const existing = mergeKey
+            ? this.items.find((item) => item.mergeKey === mergeKey)
+            : undefined;
+        if (existing) {
+            existing.text = command.text;
+            existing.anchor = { ...command.anchor };
+            existing.style = { ...(command.style ?? {}) };
+            existing.createdAtMs = effectiveNow;
+            existing.expiresAtMs = effectiveNow + durationMs;
+            existing.durationMs = durationMs;
+            existing.risePx = risePx;
+            existing.stackGapPx = stackGapPx;
+            existing.stackKey = stackKey;
+            this.mergedCount += 1;
+            return this.getSnapshots().find((item) => item.id === existing.id);
+        }
+        if (this.items.length >= this.maxItems) {
+            this.items.sort((a, b) => a.sequence - b.sequence);
+            this.items.shift();
+            this.evictedCount += 1;
+        }
+        const effect = {
+            id: `dyfm-fx-${++this.sequence}`,
+            sequence: this.sequence,
+            text: command.text,
+            anchor: { ...command.anchor },
+            style: { ...(command.style ?? {}) },
+            createdAtMs: effectiveNow,
+            expiresAtMs: effectiveNow + durationMs,
+            durationMs,
+            risePx,
+            stackGapPx,
+            stackKey,
+            mergeKey,
+        };
+        this.items.push(effect);
+        this.spawnedCount += 1;
+        this.highWatermark = Math.max(this.highWatermark, this.items.length);
+        return this.getSnapshots().find((item) => item.id === effect.id);
+    }
+    advanceTo(nowMs) {
+        this.assertMonotonicTime(nowMs);
+        this.lastTimeMs = nowMs;
+        if (!this.paused) {
+            const before = this.items.length;
+            this.items = this.items.filter((item) => nowMs < item.expiresAtMs);
+            this.expiredCount += before - this.items.length;
+        }
+        return this.getSnapshots();
+    }
+    setPaused(paused, nowMs) {
+        this.advanceTo(nowMs);
+        if (paused === this.paused) {
+            return this.getSnapshots();
+        }
+        if (paused) {
+            this.paused = true;
+            this.pauseStartedAtMs = nowMs;
+        }
+        else {
+            const frozenMs = nowMs - this.pauseStartedAtMs;
+            this.items.forEach((item) => {
+                item.createdAtMs += frozenMs;
+                item.expiresAtMs += frozenMs;
+            });
+            this.paused = false;
+            this.pauseStartedAtMs = null;
+        }
+        return this.getSnapshots();
+    }
+    clear() {
+        this.items = [];
+    }
+    getSnapshots() {
+        const renderTime = this.paused
+            ? this.pauseStartedAtMs
+            : this.lastTimeMs ?? 0;
+        const stackCounts = new Map();
+        return [...this.items]
+            .sort((a, b) => a.sequence - b.sequence)
+            .map((item) => {
+            const stackIndex = stackCounts.get(item.stackKey) ?? 0;
+            stackCounts.set(item.stackKey, stackIndex + 1);
+            const progress = Math.max(0, Math.min(1, (renderTime - item.createdAtMs) / item.durationMs));
+            return {
+                id: item.id,
+                text: item.text,
+                anchor: { ...item.anchor },
+                style: { ...item.style },
+                createdAtMs: item.createdAtMs,
+                expiresAtMs: item.expiresAtMs,
+                durationMs: item.durationMs,
+                risePx: item.risePx,
+                stackGapPx: item.stackGapPx,
+                stackKey: item.stackKey,
+                mergeKey: item.mergeKey,
+                progress,
+                opacity: 1 - progress,
+                offsetY: -(item.risePx * progress + item.stackGapPx * stackIndex),
+                stackIndex,
+            };
+        });
+    }
+    getDiagnostics() {
+        return {
+            activeCount: this.items.length,
+            highWatermark: this.highWatermark,
+            spawnedCount: this.spawnedCount,
+            mergedCount: this.mergedCount,
+            expiredCount: this.expiredCount,
+            evictedCount: this.evictedCount,
+            paused: this.paused,
+            lastTimeMs: this.lastTimeMs,
+        };
+    }
+    validateCommand(command) {
+        if (!command || typeof command.text !== 'string' || !command.text.trim()) {
+            this.fail('DYFM-FLYING-EFFECT-002', 'spawn text must be a non-empty string', { command });
+        }
+        if (!command.anchor || ![command.anchor.x, command.anchor.y].every(Number.isFinite)) {
+            this.fail('DYFM-FLYING-EFFECT-003', 'spawn anchor must contain finite x/y coordinates', { command });
+        }
+        if (command.style?.color !== undefined
+            && (typeof command.style.color !== 'string' || !command.style.color.trim())) {
+            this.fail('DYFM-FLYING-EFFECT-008', 'style.color must be a non-empty string when provided', { command });
+        }
+        if (command.style?.fontSizePx !== undefined
+            && (!Number.isFinite(command.style.fontSizePx) || command.style.fontSizePx <= 0)) {
+            this.fail('DYFM-FLYING-EFFECT-009', 'style.fontSizePx must be finite and positive when provided', { command });
+        }
+        if (command.style?.emphasis !== undefined
+            && !['normal', 'strong', 'critical'].includes(command.style.emphasis)) {
+            this.fail('DYFM-FLYING-EFFECT-010', 'style.emphasis is not supported', { command });
+        }
+    }
+    resolveStackKey(command) {
+        return this.optionalKey(command.stackKey, 'stackKey')
+            ?? this.optionalKey(command.mergeKey, 'mergeKey')
+            ?? `${command.anchor.x}:${command.anchor.y}`;
+    }
+    optionalKey(value, field) {
+        if (value === undefined) {
+            return undefined;
+        }
+        if (typeof value !== 'string' || !value.trim()) {
+            this.fail('DYFM-FLYING-EFFECT-004', `${field} must be a non-empty string when provided`, { value });
+        }
+        return value;
+    }
+    assertMonotonicTime(nowMs) {
+        if (!Number.isFinite(nowMs) || (this.lastTimeMs !== null && nowMs < this.lastTimeMs)) {
+            this.fail('DYFM-FLYING-EFFECT-005', 'time must be finite and monotonic', {
+                nowMs,
+                lastTimeMs: this.lastTimeMs,
+            });
+        }
+    }
+    positive(value, field) {
+        if (!Number.isFinite(value) || value <= 0) {
+            this.fail('DYFM-FLYING-EFFECT-006', `${field} must be finite and positive`, { value });
+        }
+        return value;
+    }
+    positiveInteger(value, field, code) {
+        if (!Number.isInteger(value) || value <= 0) {
+            this.fail(code, `${field} must be a positive integer`, { value });
+        }
+        return value;
+    }
+    nonNegative(value, field) {
+        if (!Number.isFinite(value) || value < 0) {
+            this.fail('DYFM-FLYING-EFFECT-007', `${field} must be finite and non-negative`, { value });
+        }
+        return value;
+    }
+    fail(code, message, additionalContent) {
+        throw new DyFM_Error({ errorCode: code, message: `DyFM_FlyingEffect_ControlModel: ${message}`, additionalContent });
+    }
+}

package/build-esm/_modules/game/_models/flying-effect.interface.js

@@ -0,0 +1 @@
+export {};

package/build-esm/_modules/game/_models/seeded-random-registry.control-model.js

@@ -0,0 +1,124 @@
+import { DyFM_SeededRandom } from './seeded-random.control-model';
+/**
+ * BFR-WARFACTORY-009 — **gyökér-seedelt, FÜGGETLEN RNG-stream registry.**
+ *
+ * ⚠️ **A megoldandó baj:** a `DyFM_SeededRandom` egyetlen sorozat. Ha a játék minden véletlenét
+ * egyetlen példányból húzza, akkor **egy harci dobás hozzáadása eltolja a térkép-generálást, a
+ * loot-ot, az azonosítókat és a tutorial-állapotot is** — ugyanaz a mentés más világot ad, mert
+ * közben egy csatában eggyel többször dobtunk. Ez a determinizmus leggyakoribb, legnehezebben
+ * észrevehető elvesztése.
+ *
+ * ⭐ A megoldás: **egy gyökér-seed → sok, névvel azonosított, egymástól független stream.** A
+ * `'combat'` csatorna fogyasztása nem érinti a `'worldgen'`-t, viszont ugyanabból a gyökér-seedből
+ * az egész készlet **reprodukálható**.
+ *
+ * ⚠️ **A származtatás determinisztikus és név-alapú** (`<rootSeed>::<channel>`), nem sorrend-alapú.
+ * Ez tudatos: ha a streameket a létrehozásuk sorrendje szerint származtatnánk, egy ÚJ csatorna
+ * bevezetése — vagy csak a kód átrendezése — elmozdítaná az összes utána következő sorozatot.
+ * Névvel a `'combat'` mindig ugyanaz, függetlenül attól, hány másik csatorna létezik.
+ *
+ * ⛔ A registry **nem** hoz létre csatornát a hívó tudta nélkül a `get()`-en kívül: az `require()`
+ * ismeretlen névre **dob**, mert egy elgépelt csatornanév különben csendben egy vadonatúj, üres
+ * sorozatot adna — és a hiba csak a reprodukálhatóság elvesztésekor derülne ki.
+ */
+export class DyFM_SeededRandomRegistry_ControlModel {
+    rootSeed;
+    streams = new Map();
+    constructor(rootSeed) {
+        this.rootSeed = rootSeed;
+    }
+    /** Új registry egy gyökér-seedből. Csatornák igény szerint, a `get()` hívásakor jönnek létre. */
+    static fromRootSeed(rootSeed) {
+        return new DyFM_SeededRandomRegistry_ControlModel(`${rootSeed}`);
+    }
+    /**
+     * Registry visszatöltése mentett állapotból — minden csatorna ott folytatódik, ahol abbamaradt.
+     *
+     * @throws {Error} ha a `contractVersion` nem az ismert alak. ⚠️ Ez SZÁNDÉKOSAN dob: egy nem
+     *   értelmezhető mentés-payload csendben elfogadva friss, üres streameket adna, és a játékos
+     *   mentése némán más világot generálna.
+     */
+    static fromState(state) {
+        if (state?.contractVersion !== 'dyfm-seeded-random-registry/1') {
+            throw new Error('DyFM_SeededRandomRegistry: unknown or missing contractVersion.');
+        }
+        const registry = new DyFM_SeededRandomRegistry_ControlModel(`${state.rootSeed ?? ''}`);
+        for (const channel of Object.keys(state.channels ?? {})) {
+            registry.streams.set(channel, DyFM_SeededRandom.fromState(state.channels[channel]));
+        }
+        return registry;
+    }
+    /**
+     * Egy nevesített stream. Ugyanarra a névre **mindig ugyanaz a példány** (tehát a sorozat
+     * folytatódik, nem indul újra); ismeretlen névre determinisztikusan **létrehozza**.
+     */
+    get(channel) {
+        const name = `${channel ?? ''}`.trim();
+        if (!name.length) {
+            throw new Error('DyFM_SeededRandomRegistry: a channel name is required.');
+        }
+        const existing = this.streams.get(name);
+        if (existing) {
+            return existing;
+        }
+        // Nev-alapu szarmaztatas: a `'combat'` mindig ugyanaz, fuggetlenul attol, hany masik csatorna
+        // letezik es milyen sorrendben jottek letre.
+        const stream = DyFM_SeededRandom.fromSeed(`${this.rootSeed}::${name}`);
+        this.streams.set(name, stream);
+        return stream;
+    }
+    /**
+     * Egy MÁR LÉTEZŐ stream. Ismeretlen névre **dob**.
+     *
+     * ⭐ Ez a `get()` szigorú párja: ahol a hívó tudja, hogy a csatornának léteznie kell (pl. mentés
+     * betöltése után), ott egy elgépelt név ne csendben új, üres sorozatot adjon.
+     */
+    require(channel) {
+        const name = `${channel ?? ''}`.trim();
+        const existing = this.streams.get(name);
+        if (!existing) {
+            throw new Error(`DyFM_SeededRandomRegistry: unknown channel "${name}".`);
+        }
+        return existing;
+    }
+    /** Létezik-e már a csatorna (létrehozás NÉLKÜL). */
+    has(channel) {
+        return this.streams.has(`${channel ?? ''}`.trim());
+    }
+    /**
+     * A teljes registry mentheto allapota — ezt kell a save-payloadba tenni.
+     *
+     * A csatornak ABECESORRENDBEN kerulnek bele: igy ket azonos allapotu registry
+     * szerializalt alakja BAJTRA egyezik, ami a mentes-osszehasonlitast es a teszt-asszerciot
+     * determinisztikussa teszi.
+     */
+    getState() {
+        const channels = {};
+        for (const name of [...this.streams.keys()].sort()) {
+            channels[name] = this.streams.get(name).getState();
+        }
+        return {
+            contractVersion: 'dyfm-seeded-random-registry/1',
+            rootSeed: this.rootSeed,
+            channels: channels,
+        };
+    }
+    /**
+     * Fuggetlen masolat a TELJES registry-rol. A klon minden csatornaja ott folytatja, ahol az
+     * eredeti tart, de a ketto tovabbiakban nem befolyasolja egymast.
+     *
+     * Tipikus hasznalat: „mi lenne, ha" elore-szimulacio a fo-jatekmenet elrontasa nelkul.
+     */
+    clone() {
+        return DyFM_SeededRandomRegistry_ControlModel.fromState(this.getState());
+    }
+    /** Tartalom-mentes diagnosztika: a szerkezet, nem a sorozatok kimenete. */
+    getDiagnostics() {
+        const channels = [...this.streams.keys()].sort();
+        return {
+            rootSeed: this.rootSeed,
+            channels: channels,
+            channelCount: channels.length,
+        };
+    }
+}

package/build-esm/_modules/game/_models/seeded-random-registry.interface.js

@@ -0,0 +1 @@
+export {};

package/build-esm/_modules/game/_models/seeded-random-state.interface.js

@@ -0,0 +1 @@
+export {};