@futdevpro/fsm-dynamo 1.20.92 → 1.20.93

package/build-esm/_modules/deployment/_collections/atomic-rollback-manifest.util.js

@@ -0,0 +1,348 @@
+import * as CryptoJS from 'crypto-js';
+const dyfm_exactManifestKeys = [
+    'authority',
+    'configuration',
+    'contractVersion',
+    'environment',
+    'images',
+    'operationId',
+    'postChecks',
+    'sourceRevision',
+    'targetChecksum',
+].join(',');
+const dyfm_exactAuthorityKeys = 'evidenceId,principalId';
+const dyfm_exactConfigurationKeys = 'compatibilityVersion,policyChecksum,revision,sha256';
+const dyfm_exactImageKeys = 'digest,immutableReference,mutableReference,service,version';
+const dyfm_exactPostCheckKeys = 'checkId,endpoint,expectedProbeContract,service';
+const dyfm_revisionPattern = /^[0-9a-f]{40}$/u;
+const dyfm_sha256Pattern = /^[0-9a-f]{64}$/u;
+const dyfm_digestPattern = /^sha256:[0-9a-f]{64}$/u;
+const dyfm_operationPattern = /^rollback_[0-9a-f]{32}$/u;
+const dyfm_safeIdPattern = /^[a-z0-9][a-z0-9._-]{0,127}$/u;
+const dyfm_versionPattern = /^[0-9A-Za-z][0-9A-Za-z._-]{0,63}$/u;
+const dyfm_compatibilityPattern = /^[a-z0-9][a-z0-9-]{1,63}\/[1-9][0-9]{0,8}$/u;
+const dyfm_contractPattern = /^[a-z0-9][a-z0-9-]{1,63}\/[1-9][0-9]{0,8}$/u;
+const dyfm_imageReferencePattern = /^(?:[a-z0-9]+(?:[._-][a-z0-9]+)*(?::[0-9]+)?\/)+[a-z0-9]+(?:[._-][a-z0-9]+)*:[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+/** Determines whether an unknown value is a non-array object. */
+function dyfm_isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Compares an object's sorted keys with one exact key signature. */
+function dyfm_hasExactKeys(value, expected) {
+    return Object.keys(value).sort().join(',') === expected;
+}
+/** Narrows a value to a deployment environment supported by the contract. */
+function dyfm_isEnvironment(value) {
+    return value === 'test' || value === 'production';
+}
+/** Allows bounded HTTPS probes and service-local HTTP probes without credentials or query data. */
+function dyfm_isSafePostCheckEndpoint(value, service) {
+    if (value.length > 2048) {
+        return false;
+    }
+    try {
+        const endpoint = new URL(value);
+        if (endpoint.username
+            || endpoint.password
+            || endpoint.search
+            || endpoint.hash
+            || !/^\/[A-Za-z0-9/_-]{0,127}$/u.test(endpoint.pathname)) {
+            return false;
+        }
+        if (endpoint.protocol === 'https:') {
+            return true;
+        }
+        return endpoint.protocol === 'http:'
+            && [service, '127.0.0.1', 'localhost'].includes(endpoint.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/** Parses bounded deployment authority evidence without returning rejected content. */
+function dyfm_parseAuthority(value, gapCodes) {
+    if (!dyfm_isRecord(value) || !dyfm_hasExactKeys(value, dyfm_exactAuthorityKeys)) {
+        gapCodes.push('FDP|ATOMIC_ROLLBACK|AUTHORITY_SHAPE_INVALID');
+        return undefined;
+    }
+    if (typeof value.principalId !== 'string' || !dyfm_safeIdPattern.test(value.principalId)) {
+        gapCodes.push('FDP|ATOMIC_ROLLBACK|AUTHORITY_PRINCIPAL_INVALID');
+    }
+    if (typeof value.evidenceId !== 'string' || !dyfm_sha256Pattern.test(value.evidenceId)) {
+        gapCodes.push('FDP|ATOMIC_ROLLBACK|AUTHORITY_EVIDENCE_INVALID');
+    }
+    if (typeof value.principalId !== 'string'
+        || typeof value.evidenceId !== 'string'
+        || gapCodes.some((code) => code.startsWith('FDP|ATOMIC_ROLLBACK|AUTHORITY_'))) {
+        return undefined;
+    }
+    return { principalId: value.principalId, evidenceId: value.evidenceId };
+}
+/** Parses an exact configuration and compatibility target. */
+function dyfm_parseConfiguration(value, gapCodes) {
+    if (!dyfm_isRecord(value) || !dyfm_hasExactKeys(value, dyfm_exactConfigurationKeys)) {
+        gapCodes.push('FDP|ATOMIC_ROLLBACK|CONFIGURATION_SHAPE_INVALID');
+        return undefined;
+    }
+    if (typeof value.revision !== 'string' || !dyfm_revisionPattern.test(value.revision)) {
+        gapCodes.push('FDP|ATOMIC_ROLLBACK|CONFIGURATION_REVISION_INVALID');
+    }
+    if (typeof value.sha256 !== 'string' || !dyfm_sha256Pattern.test(value.sha256)) {
+        gapCodes.push('FDP|ATOMIC_ROLLBACK|CONFIGURATION_CHECKSUM_INVALID');
+    }
+    if (typeof value.compatibilityVersion !== 'string'
+        || !dyfm_compatibilityPattern.test(value.compatibilityVersion)) {
+        gapCodes.push('FDP|ATOMIC_ROLLBACK|CONFIGURATION_COMPATIBILITY_INVALID');
+    }
+    if (typeof value.policyChecksum !== 'string' || !dyfm_sha256Pattern.test(value.policyChecksum)) {
+        gapCodes.push('FDP|ATOMIC_ROLLBACK|CONFIGURATION_POLICY_CHECKSUM_INVALID');
+    }
+    if (typeof value.revision !== 'string'
+        || typeof value.sha256 !== 'string'
+        || typeof value.compatibilityVersion !== 'string'
+        || typeof value.policyChecksum !== 'string'
+        || gapCodes.some((code) => code.startsWith('FDP|ATOMIC_ROLLBACK|CONFIGURATION_'))) {
+        return undefined;
+    }
+    return {
+        revision: value.revision,
+        sha256: value.sha256,
+        compatibilityVersion: value.compatibilityVersion,
+        policyChecksum: value.policyChecksum,
+    };
+}
+/** Parses the complete immutable image promotion set. */
+function dyfm_parseImages(value, gapCodes) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > 16) {
+        gapCodes.push('FDP|ATOMIC_ROLLBACK|IMAGE_SET_CARDINALITY_INVALID');
+        return [];
+    }
+    const images = [];
+    for (const candidate of value) {
+        if (!dyfm_isRecord(candidate) || !dyfm_hasExactKeys(candidate, dyfm_exactImageKeys)) {
+            gapCodes.push('FDP|ATOMIC_ROLLBACK|IMAGE_SHAPE_INVALID');
+            continue;
+        }
+        const service = typeof candidate.service === 'string' ? candidate.service : undefined;
+        const version = typeof candidate.version === 'string' ? candidate.version : undefined;
+        const immutableReference = typeof candidate.immutableReference === 'string'
+            ? candidate.immutableReference
+            : undefined;
+        const mutableReference = typeof candidate.mutableReference === 'string'
+            ? candidate.mutableReference
+            : undefined;
+        const digest = typeof candidate.digest === 'string' ? candidate.digest : undefined;
+        if (!service || !dyfm_safeIdPattern.test(service)) {
+            gapCodes.push('FDP|ATOMIC_ROLLBACK|IMAGE_SERVICE_INVALID');
+            continue;
+        }
+        if (!version || !dyfm_versionPattern.test(version)) {
+            gapCodes.push(`FDP|ATOMIC_ROLLBACK|IMAGE_VERSION_INVALID|${service}`);
+            continue;
+        }
+        if (!immutableReference
+            || immutableReference.length > 512
+            || !dyfm_imageReferencePattern.test(immutableReference)
+            || !immutableReference.endsWith(`/${service}:release-${version}`)) {
+            gapCodes.push(`FDP|ATOMIC_ROLLBACK|IMAGE_IMMUTABLE_REFERENCE_INVALID|${service}`);
+            continue;
+        }
+        if (!mutableReference
+            || mutableReference.length > 512
+            || !dyfm_imageReferencePattern.test(mutableReference)
+            || !mutableReference.endsWith(`/${service}:release`)) {
+            gapCodes.push(`FDP|ATOMIC_ROLLBACK|IMAGE_MUTABLE_REFERENCE_INVALID|${service}`);
+            continue;
+        }
+        if (immutableReference.slice(0, immutableReference.lastIndexOf(':'))
+            !== mutableReference.slice(0, mutableReference.lastIndexOf(':'))) {
+            gapCodes.push(`FDP|ATOMIC_ROLLBACK|IMAGE_REPOSITORY_MISMATCH|${service}`);
+            continue;
+        }
+        if (!digest || !dyfm_digestPattern.test(digest)) {
+            gapCodes.push(`FDP|ATOMIC_ROLLBACK|IMAGE_DIGEST_INVALID|${service}`);
+            continue;
+        }
+        images.push({
+            service: service,
+            version: version,
+            immutableReference: immutableReference,
+            mutableReference: mutableReference,
+            digest: digest,
+        });
+    }
+    const services = images.map((image) => image.service);
+    if (new Set(services).size !== services.length) {
+        gapCodes.push('FDP|ATOMIC_ROLLBACK|IMAGE_SERVICE_DUPLICATED');
+    }
+    return images;
+}
+/** Parses bounded post-deployment checks targeting manifest services only. */
+function dyfm_parsePostChecks(value, gapCodes) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > 32) {
+        gapCodes.push('FDP|ATOMIC_ROLLBACK|POST_CHECK_SET_CARDINALITY_INVALID');
+        return [];
+    }
+    const postChecks = [];
+    for (const candidate of value) {
+        if (!dyfm_isRecord(candidate) || !dyfm_hasExactKeys(candidate, dyfm_exactPostCheckKeys)) {
+            gapCodes.push('FDP|ATOMIC_ROLLBACK|POST_CHECK_SHAPE_INVALID');
+            continue;
+        }
+        const checkId = typeof candidate.checkId === 'string' ? candidate.checkId : undefined;
+        const service = typeof candidate.service === 'string' ? candidate.service : undefined;
+        const endpoint = typeof candidate.endpoint === 'string' ? candidate.endpoint : undefined;
+        const expectedProbeContract = typeof candidate.expectedProbeContract === 'string'
+            ? candidate.expectedProbeContract
+            : undefined;
+        if (!checkId || !dyfm_safeIdPattern.test(checkId)) {
+            gapCodes.push('FDP|ATOMIC_ROLLBACK|POST_CHECK_ID_INVALID');
+            continue;
+        }
+        if (!service || !dyfm_safeIdPattern.test(service)) {
+            gapCodes.push(`FDP|ATOMIC_ROLLBACK|POST_CHECK_SERVICE_INVALID|${checkId}`);
+            continue;
+        }
+        if (!endpoint || !dyfm_isSafePostCheckEndpoint(endpoint, service)) {
+            gapCodes.push(`FDP|ATOMIC_ROLLBACK|POST_CHECK_ENDPOINT_INVALID|${checkId}`);
+            continue;
+        }
+        if (!expectedProbeContract || !dyfm_contractPattern.test(expectedProbeContract)) {
+            gapCodes.push(`FDP|ATOMIC_ROLLBACK|POST_CHECK_CONTRACT_INVALID|${checkId}`);
+            continue;
+        }
+        postChecks.push({
+            checkId: checkId,
+            service: service,
+            endpoint: endpoint,
+            expectedProbeContract: expectedProbeContract,
+        });
+    }
+    if (new Set(postChecks.map((check) => check.checkId)).size
+        !== postChecks.length) {
+        gapCodes.push('FDP|ATOMIC_ROLLBACK|POST_CHECK_ID_DUPLICATED');
+    }
+    return postChecks;
+}
+/** Creates the exact, insertion-order-independent JSON value hashed by every producer and consumer. */
+function dyfm_canonicalTarget(manifest) {
+    return JSON.stringify({
+        contractVersion: manifest.contractVersion,
+        operationId: manifest.operationId,
+        environment: manifest.environment,
+        authority: {
+            principalId: manifest.authority.principalId,
+            evidenceId: manifest.authority.evidenceId,
+        },
+        sourceRevision: manifest.sourceRevision,
+        configuration: {
+            revision: manifest.configuration.revision,
+            sha256: manifest.configuration.sha256,
+            compatibilityVersion: manifest.configuration.compatibilityVersion,
+            policyChecksum: manifest.configuration.policyChecksum,
+        },
+        images: [...manifest.images].sort((left, right) => left.service
+            .localeCompare(right.service)).map((image) => ({
+            service: image.service,
+            version: image.version,
+            immutableReference: image.immutableReference,
+            mutableReference: image.mutableReference,
+            digest: image.digest,
+        })),
+        postChecks: [...manifest.postChecks].sort((left, right) => left
+            .checkId.localeCompare(right.checkId)).map((check) => ({
+            checkId: check.checkId,
+            service: check.service,
+            endpoint: check.endpoint,
+            expectedProbeContract: check.expectedProbeContract,
+        })),
+    });
+}
+/** Canonical manifest checksum and strict content-free local validation. */
+export class DyFM_AtomicRollbackManifest_Util {
+    /** Calculates the canonical SHA-256 target checksum for a typed manifest. */
+    static computeTargetChecksum(manifest) {
+        return CryptoJS.SHA256(dyfm_canonicalTarget(manifest)).toString();
+    }
+    /** Validates an unknown manifest without reflecting rejected content. */
+    static validate(value) {
+        if (!dyfm_isRecord(value) || !dyfm_hasExactKeys(value, dyfm_exactManifestKeys)) {
+            return {
+                contractVersion: 'fdp-atomic-rollback-local-validation/1',
+                valid: false,
+                environment: 'invalid',
+                operationId: 'invalid',
+                targetChecksum: 'invalid',
+                serviceCount: 0,
+                postCheckCount: 0,
+                gapCodes: ['FDP|ATOMIC_ROLLBACK|MANIFEST_SHAPE_INVALID'],
+            };
+        }
+        const gapCodes = [];
+        if (value.contractVersion !== 'fdp-atomic-rollback-manifest/1') {
+            gapCodes.push('FDP|ATOMIC_ROLLBACK|CONTRACT_VERSION_INVALID');
+        }
+        if (typeof value.operationId !== 'string' || !dyfm_operationPattern.test(value.operationId)) {
+            gapCodes.push('FDP|ATOMIC_ROLLBACK|OPERATION_ID_INVALID');
+        }
+        if (!dyfm_isEnvironment(value.environment)) {
+            gapCodes.push('FDP|ATOMIC_ROLLBACK|ENVIRONMENT_INVALID');
+        }
+        if (typeof value.sourceRevision !== 'string' || !dyfm_revisionPattern.test(value.sourceRevision)) {
+            gapCodes.push('FDP|ATOMIC_ROLLBACK|SOURCE_REVISION_INVALID');
+        }
+        const authority = dyfm_parseAuthority(value.authority, gapCodes);
+        const configuration = dyfm_parseConfiguration(value.configuration, gapCodes);
+        const images = dyfm_parseImages(value.images, gapCodes);
+        const postChecks = dyfm_parsePostChecks(value.postChecks, gapCodes);
+        const imageServices = new Set(images.map((image) => image.service));
+        if (postChecks.some((check) => !imageServices.has(check.service))) {
+            gapCodes.push('FDP|ATOMIC_ROLLBACK|POST_CHECK_SERVICE_NOT_TARGETED');
+        }
+        if (typeof value.targetChecksum !== 'string' || !dyfm_sha256Pattern.test(value.targetChecksum)) {
+            gapCodes.push('FDP|ATOMIC_ROLLBACK|TARGET_CHECKSUM_INVALID');
+        }
+        let manifest;
+        if (!gapCodes.length
+            && typeof value.operationId === 'string'
+            && dyfm_isEnvironment(value.environment)
+            && authority
+            && typeof value.sourceRevision === 'string'
+            && configuration
+            && images.length > 0
+            && postChecks.length > 0
+            && typeof value.targetChecksum === 'string') {
+            manifest = {
+                contractVersion: 'fdp-atomic-rollback-manifest/1',
+                operationId: value.operationId,
+                environment: value.environment,
+                authority: authority,
+                sourceRevision: value.sourceRevision,
+                configuration: configuration,
+                images: images,
+                postChecks: postChecks,
+                targetChecksum: value.targetChecksum,
+            };
+            if (this.computeTargetChecksum(manifest) !== value.targetChecksum) {
+                gapCodes.push('FDP|ATOMIC_ROLLBACK|TARGET_CHECKSUM_MISMATCH');
+                manifest = undefined;
+            }
+        }
+        const normalizedGapCodes = [...new Set(gapCodes)].sort();
+        return {
+            contractVersion: 'fdp-atomic-rollback-local-validation/1',
+            valid: !normalizedGapCodes.length,
+            environment: dyfm_isEnvironment(value.environment) ? value.environment : 'invalid',
+            operationId: !normalizedGapCodes.length && typeof value.operationId === 'string'
+                ? value.operationId
+                : 'invalid',
+            targetChecksum: !normalizedGapCodes.length && typeof value.targetChecksum === 'string'
+                ? value.targetChecksum
+                : 'invalid',
+            serviceCount: images.length,
+            postCheckCount: postChecks.length,
+            gapCodes: normalizedGapCodes,
+            ...(manifest ? { manifest: manifest } : {}),
+        };
+    }
+}

package/build-esm/_modules/deployment/_models/atomic-rollback-manifest.interface.js

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

package/build-esm/_modules/deployment/index.js

@@ -0,0 +1,2 @@
+export * from './_collections/atomic-rollback-manifest.util';
+export * from './_models/atomic-rollback-manifest.interface';

package/build-esm/_modules/game/_collections/audio-mixer.util.js

@@ -0,0 +1,109 @@
+import { DyFM_AudioChannel } from '../_enums/audio-channel.enum';
+/**
+ * Statikus util a jatek-audio mixer beallitasaihoz.
+ *
+ * Rendereles-agnosztikus es platform-fuggetlen: NINCS benne DOM, Web Audio, Angular vagy Node
+ * fuggoseg — a tenyleges lejatszast az `@futdevpro/ngx-dynamo` game-modulja (vagy a projekt sajat
+ * motorja) vegzi, ez csak a **modell + szamitas**.
+ *
+ * **Hasznalat:**
+ * ```typescript
+ * const settings: DyFM_AudioMixer_Settings = DyFM_AudioMixer_Util.merge(loadedFromSave);
+ * const volume: number = DyFM_AudioMixer_Util.getEffectiveVolume(settings, DyFM_AudioChannel.music);
+ * audioElement.volume = volume;
+ * ```
+ */
+export class DyFM_AudioMixer_Util {
+    /** Alapertelmezett hangero minden csatornara (0..1). */
+    static defaultVolume = 0.8;
+    /**
+     * Az alapertelmezett mixer-beallitas. Minden hivas UJ objektumot ad vissza, hogy a
+     * hivo szabadon mutalhassa (nincs megosztott referencia).
+     */
+    static getDefaults() {
+        return {
+            master: this.defaultVolume,
+            music: this.defaultVolume,
+            ambience: this.defaultVolume,
+            effects: this.defaultVolume,
+            muted: false,
+        };
+    }
+    /**
+     * Egy hangero-erteket a 0..1 tartomanyba szorit. A nem-szamokat (NaN, undefined, null,
+     * nem-szam tipus) a `fallback`-re cseréli — igy egy serult save-payload sem tud NaN-t
+     * juttatni a lejatszoba (a `HTMLAudioElement.volume = NaN` dobna).
+     */
+    static clamp(value, fallback = DyFM_AudioMixer_Util.defaultVolume) {
+        if (typeof value !== 'number' || Number.isNaN(value)) {
+            return fallback;
+        }
+        if (value < 0) {
+            return 0;
+        }
+        if (1 < value) {
+            return 1;
+        }
+        return value;
+    }
+    /**
+     * Reszleges (vagy hianyzo) beallitas-objektumbol teljes, ervenyes settingset allit elo:
+     * a hianyzo mezoket a defaultbol veszi, a meglevoket 0..1-re szoritja.
+     *
+     * **Ez a migracios biztositek:** egy regi save-payload, ami meg nem ismerte az `ambience`
+     * csatornat, igy is betoltheto marad.
+     */
+    static merge(partial) {
+        const defaults = this.getDefaults();
+        if (!partial) {
+            return defaults;
+        }
+        return {
+            master: this.clamp(partial.master ?? defaults.master, defaults.master),
+            music: this.clamp(partial.music ?? defaults.music, defaults.music),
+            ambience: this.clamp(partial.ambience ?? defaults.ambience, defaults.ambience),
+            effects: this.clamp(partial.effects ?? defaults.effects, defaults.effects),
+            muted: partial.muted === true,
+        };
+    }
+    /**
+     * Egy csatorna EFFEKTIV hangereje: a csatorna sajat erteke szorozva a master-rel.
+     * Nemitas (`muted`) eseten mindig 0. A `master` csatornara a sajat erteket adja vissza
+     * (nem negyzetre emelve).
+     */
+    static getEffectiveVolume(settings, channel) {
+        const safe = this.merge(settings);
+        if (safe.muted) {
+            return 0;
+        }
+        if (channel === DyFM_AudioChannel.master) {
+            return safe.master;
+        }
+        return this.clamp(safe[channel] * safe.master);
+    }
+    /**
+     * Egy csatorna hangerejenek beallitasa — UJ settings-objektumot ad vissza (immutable update),
+     * hogy signal-/state-alapu tarolokban is biztonsagos legyen.
+     */
+    static withChannelVolume(settings, channel, volume) {
+        const next = this.merge(settings);
+        next[channel] = this.clamp(volume);
+        return next;
+    }
+    /** Nemitas beallitasa — UJ settings-objektumot ad vissza (immutable update). */
+    static withMuted(settings, muted) {
+        const next = this.merge(settings);
+        next.muted = muted === true;
+        return next;
+    }
+    /** Ket beallitas ertek szerinti egyezese (mentes-szukseg / change-detection dontesehez). */
+    static isEqual(a, b) {
+        const left = this.merge(a);
+        const right = this.merge(b);
+        return left.master === right.master
+            && left.music === right.music
+            && left.ambience === right.ambience
+            && left.effects === right.effects
+            && left.muted === right.muted;
+    }
+}

package/build-esm/_modules/game/_collections/audio-scale.util.js

@@ -0,0 +1,100 @@
+/**
+ * Skala-konverziok az audio-mixerhez: a projekt sajat szamabrazolasa (pl. `0-100` egesz)
+ * es a lejatszo API-k altal vart `0..1` kozott.
+ *
+ * **Miert statikus util:** nincs allapota — tiszta fuggvenyek, a `DyFM_Math` mintajara.
+ *
+ * **Hasznalat:**
+ * ```typescript
+ * const percent = DyFM_AudioScale_Util.getPercentScale();
+ * DyFM_AudioScale_Util.toUnit(72, percent);      // 0.72  -> ezt varja a HTMLAudio / GainNode
+ * DyFM_AudioScale_Util.fromUnit(0.725, percent); // 73    -> ezt tarolja / mutatja a projekt
+ * ```
+ */
+export class DyFM_AudioScale_Util {
+    /** Alapertelmezett hangero-arany (a skala maximumanak hanyada), ha nincs jobb ertek. */
+    static defaultRatio = 0.8;
+    /**
+     * A `0..1` lebegopontos skala — a Prototyper prototipusai (es a round-1
+     * `DyFM_AudioMixer_Settings`) ezt hasznaljak. Minden hivas UJ objektumot ad vissza, hogy a
+     * hivo szabadon mutalhassa.
+     */
+    static getUnitScale() {
+        return {
+            max: 1,
+            integer: false,
+        };
+    }
+    /**
+     * A `0-100` egesz skala — a Hero Coordinator ezt tarolja a localStorage-ban
+     * (`clampVolume` = `Math.round`). Minden hivas UJ objektumot ad vissza.
+     */
+    static getPercentScale() {
+        return {
+            max: 100,
+            integer: true,
+        };
+    }
+    /**
+     * Sajat skalan levo erteket `0..1`-re normalizal, es a tartomanyba szorit.
+     * Ervenytelen bemenet (NaN, nem-szam, null/undefined) eseten a `fallbackUnit`-ot adja —
+     * igy egy serult save-payload sem tud NaN-t juttatni a lejatszoba
+     * (`HTMLAudioElement.volume = NaN` dobna, a `GainNode.gain.value = NaN` elnemitana).
+     */
+    static toUnit(value, scale, fallbackUnit = DyFM_AudioScale_Util.defaultRatio) {
+        const max = this.getSafeMax(scale);
+        if (typeof value !== 'number' || Number.isNaN(value)) {
+            return this.clampUnit(fallbackUnit);
+        }
+        return this.clampUnit(value / max);
+    }
+    /**
+     * `0..1` erteket a sajat skalara alakit vissza. Egesz skalanal (`integer: true`) kerekit,
+     * igy a `0-100`-as UI-nak nem kell tortszamokkal dolgoznia.
+     */
+    static fromUnit(unit, scale) {
+        const max = this.getSafeMax(scale);
+        const safeUnit = typeof unit !== 'number' || Number.isNaN(unit)
+            ? 0
+            : this.clampUnit(unit);
+        const scaled = safeUnit * max;
+        return scale && scale.integer === true ? Math.round(scaled) : scaled;
+    }
+    /**
+     * Egy erteket a sajat skala `0..max` tartomanyaba szorit (egesz skalanal kerekit is).
+     *
+     * Ervenytelen bemenetre (NaN, nem-szam) a `fallbackScaleValue`-t adja — **a sajat skalan**.
+     * Alapertelmezesben `0`; a mixer viszont a csatorna DEFAULT-jat adja at, mert egy serult
+     * mentesbol jobb a hallhato alapertek, mint a nema 0 (a felhasznalo eszre sem venne).
+     */
+    static clampToScale(value, scale, fallbackScaleValue = 0) {
+        if (typeof value !== 'number' || Number.isNaN(value)) {
+            const safeFallback = typeof fallbackScaleValue === 'number'
+                && !Number.isNaN(fallbackScaleValue)
+                ? fallbackScaleValue
+                : 0;
+            return this.fromUnit(this.toUnit(safeFallback, scale, 0), scale);
+        }
+        return this.fromUnit(this.toUnit(value, scale, 0), scale);
+    }
+    /** Egy `0..1` erteket a tartomanyba szorit. */
+    static clampUnit(value) {
+        if (typeof value !== 'number' || Number.isNaN(value)) {
+            return 0;
+        }
+        if (value < 0) {
+            return 0;
+        }
+        return 1 < value ? 1 : value;
+    }
+    /**
+     * A skala maximuma vedve: a hianyzo / nem-pozitiv / NaN maximumot `1`-re cseréli, hogy a
+     * nullaval valo osztas es a NaN-terjedes kizart legyen.
+     */
+    static getSafeMax(scale) {
+        if (!scale || typeof scale.max !== 'number' || Number.isNaN(scale.max) || scale.max <= 0) {
+            return 1;
+        }
+        return scale.max;
+    }
+}

package/build-esm/_modules/game/_enums/audio-channel.enum.js

@@ -0,0 +1,21 @@
+/**
+ * A jatek-audio mixer **klasszikus** csatorna-keszlete.
+ *
+ * A Prototyper HAROM prototipusa (Room Cats / Cell Stage / Portalhold) egymastol fuggetlenul
+ * ugyanezt a negy csatornat vezette be — ez az enum az o kanonikus nevezektanuk.
+ *
+ * **FIGYELEM (2026-08-06 helyesbites):** ez NEM flotta-univerzalis. A **Hero Coordinator**
+ * csatornai `master` / `music` / **`dialog`** / **`interface`**, es `0-100` egeszet tarol.
+ * Ha a projekted csatorna-keszlete elter, NE ezt az enumot hasznald, hanem a
+ * `DyFM_AudioMixer_ControlModel`-t sajat config-gal (csatorna- es skala-agnosztikus).
+ *
+ * A `master` NEM onallo hangsav: minden csatorna effektiv hangereje a sajat erteke
+ * SZOROZVA a master-rel (lasd `DyFM_AudioMixer_Util.getEffectiveVolume`).
+ */
+export var DyFM_AudioChannel;
+(function (DyFM_AudioChannel) {
+    DyFM_AudioChannel["master"] = "master";
+    DyFM_AudioChannel["music"] = "music";
+    DyFM_AudioChannel["ambience"] = "ambience";
+    DyFM_AudioChannel["effects"] = "effects";
+})(DyFM_AudioChannel || (DyFM_AudioChannel = {}));

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

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

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

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

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

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