@futdevpro/fsm-dynamo 1.16.38 → 1.16.40

package/src/_modules/game/_models/audio-mixer.control-model.ts

@@ -1,419 +1,419 @@
-
-
-import { DyFM_Error } from '../../../_models/control-models/error.control-model';
-
-import { DyFM_AudioScale_Util } from '../_collections/audio-scale.util';
-
-import { DyFM_AudioMixer_Config } from './audio-mixer-config.interface';
-import { DyFM_AudioMixer_Settings } from './audio-mixer-settings.interface';
-import { DyFM_AudioMixer_State } from './audio-mixer-state.interface';
-import { DyFM_AudioScale } from './audio-scale.interface';
-
-
-/**
- * **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 readonly masterChannel: string = 'master';
-
-  /** A validalt, sajat peldany-config (a hivo altal atadott objektumtol fuggetlen masolat). */
-  private readonly config: DyFM_AudioMixer_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: DyFM_AudioMixer_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: string[] = [];
-
-    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: DyFM_AudioScale = 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(): DyFM_AudioMixer_ControlModel {
-    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: string[],
-    defaults?: Record<string, number>,
-    defaultMaster?: number,
-  ): DyFM_AudioMixer_ControlModel {
-    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: DyFM_AudioMixer_Settings): DyFM_AudioMixer_State {
-    const safe: DyFM_AudioMixer_Settings = settings ?? ({} as DyFM_AudioMixer_Settings);
-    const scale: DyFM_AudioScale = 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: DyFM_AudioMixer_State): DyFM_AudioMixer_Settings {
-    const safe: DyFM_AudioMixer_State = this.merge(state);
-    const scale: DyFM_AudioScale = this.config.scale;
-
-    const classic: DyFM_AudioMixer_Settings = {
-      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(): DyFM_AudioMixer_Config {
-    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(): string[] {
-    return [...this.config.channels];
-  }
-
-  /** Igaz, ha a nev a deklaralt csatornak kozott van (a `master` NEM az). */
-  hasChannel(channel: string): boolean {
-    return this.config.channels.includes(channel);
-  }
-
-  /**
-   * Alapertelmezett allapot a **sajat skalan**. Minden hivas UJ objektumot ad vissza, hogy a
-   * hivo szabadon mutalhassa.
-   */
-  getDefaults(): DyFM_AudioMixer_State {
-    const channels: Record<string, number> = {};
-
-    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?: Partial<DyFM_AudioMixer_State> | null): DyFM_AudioMixer_State {
-    const defaults: DyFM_AudioMixer_State = this.getDefaults();
-
-    if (!partial) {
-      return defaults;
-    }
-
-    const source: Record<string, number> = partial.channels ?? {};
-    const channels: Record<string, number> = {};
-
-    for (const channel of this.config.channels) {
-      const raw: number = source[channel];
-
-      channels[channel] = raw === undefined || raw === null
-        ? defaults.channels[channel]
-        : DyFM_AudioScale_Util.clampToScale(raw, this.config.scale, defaults.channels[channel]);
-    }
-
-    const master: number = 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: boolean =
-      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: DyFM_AudioMixer_State, channel: string): number {
-    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: DyFM_AudioMixer_State = this.merge(state);
-
-    if (safe.muted) {
-      return 0;
-    }
-
-    const masterUnit: number = DyFM_AudioScale_Util.toUnit(safe.master, this.config.scale);
-
-    if (channel === DyFM_AudioMixer_ControlModel.masterChannel) {
-      return masterUnit;
-    }
-
-    const channelUnit: number = 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: DyFM_AudioMixer_State,
-    channel: string,
-    volume: number,
-  ): DyFM_AudioMixer_State {
-    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: DyFM_AudioMixer_State = 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: DyFM_AudioMixer_State, volume: number): DyFM_AudioMixer_State {
-    const next: DyFM_AudioMixer_State = this.merge(state);
-    next.master = DyFM_AudioScale_Util.clampToScale(volume, this.config.scale);
-
-    return next;
-  }
-
-  /** Nemitas beallitasa — UJ allapot-objektumot ad vissza. */
-  withMuted(state: DyFM_AudioMixer_State, muted: boolean): DyFM_AudioMixer_State {
-    const next: DyFM_AudioMixer_State = 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: DyFM_AudioMixer_State,
-    playWhenUnfocused: boolean,
-  ): DyFM_AudioMixer_State {
-    const next: DyFM_AudioMixer_State = this.merge(state);
-    next.playWhenUnfocused = playWhenUnfocused === true;
-
-    return next;
-  }
-
-  /** Ket allapot ertek szerinti egyezese (mentes-szukseg / change-detection dontesehez). */
-  isEqual(a: DyFM_AudioMixer_State, b: DyFM_AudioMixer_State): boolean {
-    const left: DyFM_AudioMixer_State = this.merge(a);
-    const right: DyFM_AudioMixer_State = 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). */
-  private getDefaultMaster(): number {
-    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%). */
-  private getDefaultChannelVolume(channel: string): number {
-    const perChannel: number = (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);
-  }
-}
+
+
+import { DyFM_Error } from '../../../_models/control-models/error.control-model';
+
+import { DyFM_AudioScale_Util } from '../_collections/audio-scale.util';
+
+import { DyFM_AudioMixer_Config } from './audio-mixer-config.interface';
+import { DyFM_AudioMixer_Settings } from './audio-mixer-settings.interface';
+import { DyFM_AudioMixer_State } from './audio-mixer-state.interface';
+import { DyFM_AudioScale } from './audio-scale.interface';
+
+
+/**
+ * **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 readonly masterChannel: string = 'master';
+
+  /** A validalt, sajat peldany-config (a hivo altal atadott objektumtol fuggetlen masolat). */
+  private readonly config: DyFM_AudioMixer_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: DyFM_AudioMixer_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: string[] = [];
+
+    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: DyFM_AudioScale = 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(): DyFM_AudioMixer_ControlModel {
+    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: string[],
+    defaults?: Record<string, number>,
+    defaultMaster?: number,
+  ): DyFM_AudioMixer_ControlModel {
+    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: DyFM_AudioMixer_Settings): DyFM_AudioMixer_State {
+    const safe: DyFM_AudioMixer_Settings = settings ?? ({} as DyFM_AudioMixer_Settings);
+    const scale: DyFM_AudioScale = 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: DyFM_AudioMixer_State): DyFM_AudioMixer_Settings {
+    const safe: DyFM_AudioMixer_State = this.merge(state);
+    const scale: DyFM_AudioScale = this.config.scale;
+
+    const classic: DyFM_AudioMixer_Settings = {
+      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(): DyFM_AudioMixer_Config {
+    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(): string[] {
+    return [...this.config.channels];
+  }
+
+  /** Igaz, ha a nev a deklaralt csatornak kozott van (a `master` NEM az). */
+  hasChannel(channel: string): boolean {
+    return this.config.channels.includes(channel);
+  }
+
+  /**
+   * Alapertelmezett allapot a **sajat skalan**. Minden hivas UJ objektumot ad vissza, hogy a
+   * hivo szabadon mutalhassa.
+   */
+  getDefaults(): DyFM_AudioMixer_State {
+    const channels: Record<string, number> = {};
+
+    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?: Partial<DyFM_AudioMixer_State> | null): DyFM_AudioMixer_State {
+    const defaults: DyFM_AudioMixer_State = this.getDefaults();
+
+    if (!partial) {
+      return defaults;
+    }
+
+    const source: Record<string, number> = partial.channels ?? {};
+    const channels: Record<string, number> = {};
+
+    for (const channel of this.config.channels) {
+      const raw: number = source[channel];
+
+      channels[channel] = raw === undefined || raw === null
+        ? defaults.channels[channel]
+        : DyFM_AudioScale_Util.clampToScale(raw, this.config.scale, defaults.channels[channel]);
+    }
+
+    const master: number = 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: boolean =
+      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: DyFM_AudioMixer_State, channel: string): number {
+    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: DyFM_AudioMixer_State = this.merge(state);
+
+    if (safe.muted) {
+      return 0;
+    }
+
+    const masterUnit: number = DyFM_AudioScale_Util.toUnit(safe.master, this.config.scale);
+
+    if (channel === DyFM_AudioMixer_ControlModel.masterChannel) {
+      return masterUnit;
+    }
+
+    const channelUnit: number = 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: DyFM_AudioMixer_State,
+    channel: string,
+    volume: number,
+  ): DyFM_AudioMixer_State {
+    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: DyFM_AudioMixer_State = 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: DyFM_AudioMixer_State, volume: number): DyFM_AudioMixer_State {
+    const next: DyFM_AudioMixer_State = this.merge(state);
+    next.master = DyFM_AudioScale_Util.clampToScale(volume, this.config.scale);
+
+    return next;
+  }
+
+  /** Nemitas beallitasa — UJ allapot-objektumot ad vissza. */
+  withMuted(state: DyFM_AudioMixer_State, muted: boolean): DyFM_AudioMixer_State {
+    const next: DyFM_AudioMixer_State = 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: DyFM_AudioMixer_State,
+    playWhenUnfocused: boolean,
+  ): DyFM_AudioMixer_State {
+    const next: DyFM_AudioMixer_State = this.merge(state);
+    next.playWhenUnfocused = playWhenUnfocused === true;
+
+    return next;
+  }
+
+  /** Ket allapot ertek szerinti egyezese (mentes-szukseg / change-detection dontesehez). */
+  isEqual(a: DyFM_AudioMixer_State, b: DyFM_AudioMixer_State): boolean {
+    const left: DyFM_AudioMixer_State = this.merge(a);
+    const right: DyFM_AudioMixer_State = 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). */
+  private getDefaultMaster(): number {
+    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%). */
+  private getDefaultChannelVolume(channel: string): number {
+    const perChannel: number = (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);
+  }
+}