@futdevpro/fsm-dynamo 1.20.102 → 1.20.104

package/build-esm/_modules/game/_models/narration-player.control-model.js

@@ -0,0 +1,218 @@
+import { DyFM_Log } from '../../../_collections/utils/log.util';
+/**
+ * BFR-WARFACTORY-014 — the narration adapter canon (war-factory `Tutorial_Narration_Service` + portalhold voice lines):
+ *
+ * - **asset-id core**, catalog as an optional layer (`playLine` / `playCatalog`);
+ * - `Promise<boolean>` — a refusal is REPORTED, with its reason in `lastRefusal` (disabled · muted · no-gesture ·
+ *   autoplay-blocked · error · unknown-line) — a narration that silently does not play is undiagnosable;
+ * - optional **gesture gate with exposed state** (`sessionActivated`);
+ * - **exactly one active line** — every play stops the previous one;
+ * - a **staleness guard** (revision counter): a late `ended` / `error` / `play()` rejection of a replaced line never
+ *   touches the current one;
+ * - **`blocked` ≠ `failed`**: a `NotAllowedError` (browser autoplay block) is the case the player must be told about;
+ * - `replay()`; optional settings persistence; the subtitle stays available while blocked / failed (text fallback).
+ *
+ * Framework-agnostic: the audio comes from a factory (`(src) => new Audio(src)` in a browser); a UI layer mirrors
+ * `getState()` via `onChange`.
+ */
+export class DyFM_NarrationPlayer_ControlModel {
+    options;
+    listeners = [];
+    audio = null;
+    revision = 0;
+    lastLine = null;
+    state = {
+        playback: 'idle', activeLineId: null, subtitle: null, enabled: true, volume: 0.85, sessionActivated: false,
+        lastRefusal: null,
+    };
+    constructor(options) {
+        this.options = options;
+        this.loadSettings();
+    }
+    /** A copy of the current state. */
+    getState() {
+        return { ...this.state };
+    }
+    /** Subscribe to state changes; returns the unsubscribe. A throwing listener is logged and isolated. */
+    onChange(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const index = this.listeners.indexOf(listener);
+            if (index >= 0) {
+                this.listeners.splice(index, 1);
+            }
+        };
+    }
+    /** Marks a user gesture — from now on automatic narration may play. */
+    activate() {
+        if (!this.state.sessionActivated) {
+            this.set({ sessionActivated: true });
+        }
+    }
+    /** Plays a line (automatic path: respects the gesture gate). */
+    async playLine(line) {
+        return this.play(line);
+    }
+    /** Plays a catalog entry; an unknown key refuses with `unknown-line`. */
+    async playCatalog(key) {
+        const line = this.options.catalog?.[key];
+        if (!line) {
+            this.set({ lastRefusal: 'unknown-line' });
+            return false;
+        }
+        return this.play(line);
+    }
+    /** From a user gesture: activates the session, then plays. */
+    async activateAndPlay(line) {
+        this.activate();
+        return this.play(line);
+    }
+    /** Replays the last requested line (a replay button is a gesture). */
+    async replay() {
+        if (!this.lastLine) {
+            return false;
+        }
+        this.activate();
+        return this.play(this.lastLine);
+    }
+    /** Stops the active line (or clears a blocked / failed one). */
+    stop() {
+        this.revision++;
+        this.detach();
+        this.set({ playback: 'idle', activeLineId: null, subtitle: null });
+    }
+    setEnabled(enabled) {
+        this.set({ enabled: enabled });
+        this.saveSettings();
+        if (!enabled && this.audio) {
+            this.stop();
+        }
+    }
+    setVolume(volume) {
+        this.set({ volume: Math.min(1, Math.max(0, Number.isFinite(volume) ? volume : 0)) });
+        this.saveSettings();
+        this.applyVolume();
+    }
+    /** Re-applies the effective volume (call it when the game's master volume / mute changes); 0 stops the line. */
+    applyVolume() {
+        const effective = this.effectiveVolume();
+        if (this.audio) {
+            this.audio.volume = effective;
+            if (effective <= 0) {
+                this.stop();
+            }
+        }
+    }
+    async play(line) {
+        this.lastLine = line;
+        const refusal = !this.state.enabled
+            ? 'disabled'
+            : this.effectiveVolume() <= 0
+                ? 'muted'
+                : this.options.requireGesture && !this.state.sessionActivated ? 'no-gesture' : null;
+        if (refusal) {
+            this.set({ lastRefusal: refusal });
+            return false;
+        }
+        // exactly one active line: the previous one is stopped and its late callbacks become stale
+        const revision = ++this.revision;
+        this.detach();
+        let audio;
+        try {
+            audio = this.options.audioFactory(line.src);
+            audio.volume = this.effectiveVolume();
+            audio.onended = () => {
+                if (revision === this.revision) {
+                    this.audio = null;
+                    this.set({ playback: 'idle', activeLineId: null, subtitle: null });
+                }
+            };
+            audio.onerror = () => {
+                if (revision === this.revision) {
+                    this.audio = null;
+                    this.set({ playback: 'failed', lastRefusal: 'error' });
+                }
+            };
+            this.audio = audio;
+            this.set({ activeLineId: line.lineId, subtitle: line.subtitle ?? null, lastRefusal: null });
+            await audio.play();
+        }
+        catch (error) {
+            if (revision !== this.revision) {
+                return false; // a newer line replaced this one while play() was pending
+            }
+            this.audio = null;
+            const blocked = error?.name === 'NotAllowedError';
+            this.set({ playback: blocked ? 'blocked' : 'failed', lastRefusal: blocked ? 'autoplay-blocked' : 'error' });
+            return false;
+        }
+        if (revision !== this.revision) {
+            return false;
+        }
+        this.set({ playback: 'playing' });
+        return true;
+    }
+    detach() {
+        if (this.audio) {
+            const audio = this.audio;
+            this.audio = null;
+            audio.onended = null;
+            audio.onerror = null;
+            try {
+                audio.pause();
+                audio.currentTime = 0;
+            }
+            catch (error) {
+                DyFM_Log.error('DyFM_NarrationPlayer: stopping the previous line failed', error);
+            }
+        }
+    }
+    effectiveVolume() {
+        const master = this.options.masterVolume ? this.options.masterVolume() : 1;
+        return Math.min(1, Math.max(0, this.state.volume * (Number.isFinite(master) ? master : 0)));
+    }
+    set(patch) {
+        this.state = { ...this.state, ...patch };
+        const snapshot = this.getState();
+        for (const listener of [...this.listeners]) {
+            try {
+                listener(snapshot);
+            }
+            catch (error) {
+                DyFM_Log.error('DyFM_NarrationPlayer: an onChange listener threw', error);
+            }
+        }
+    }
+    loadSettings() {
+        const settings = this.options.settings;
+        if (!settings) {
+            return;
+        }
+        try {
+            const stored = settings.store.getItem(settings.key);
+            const parsed = stored ? JSON.parse(stored) : {};
+            if (typeof parsed.enabled === 'boolean') {
+                this.state.enabled = parsed.enabled;
+            }
+            if (typeof parsed.volume === 'number' && Number.isFinite(parsed.volume)) {
+                this.state.volume = Math.min(1, Math.max(0, parsed.volume));
+            }
+        }
+        catch (error) {
+            // a broken stored value falls back to the defaults (the session still works)
+            DyFM_Log.error(`DyFM_NarrationPlayer: unreadable settings under '${settings.key}' — defaults used`, error);
+        }
+    }
+    saveSettings() {
+        const settings = this.options.settings;
+        if (!settings) {
+            return;
+        }
+        try {
+            settings.store.setItem(settings.key, JSON.stringify({ enabled: this.state.enabled, volume: this.state.volume }));
+        }
+        catch (error) {
+            DyFM_Log.error(`DyFM_NarrationPlayer: settings could not be saved under '${settings.key}'`, error);
+        }
+    }
+}

package/build-esm/_modules/game/_models/narration-player.interface.js

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

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

@@ -22,6 +22,10 @@ export * from './_models/viewport.interface';
 export * from './_models/viewport.control-model';
 export * from './_models/input-action.interface';
 export * from './_models/input-action-registry.control-model';
+export * from './_models/guided-onboarding.interface';
+export * from './_models/guided-onboarding.control-model';
+export * from './_models/narration-player.interface';
+export * from './_models/narration-player.control-model';
 // COLLECTIONS
 export * from './_collections/audio-mixer.util';
 export * from './_collections/audio-scale.util';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@futdevpro/fsm-dynamo",
-  "version": "1.20.102",
+  "version": "1.20.104",
   "description": "Full Stack Model Collection for Dynamic (NodeJS-Typescript) Framework called Dynamo, by Future Development Ltd.",
   "DyBu_settings": {
     "packageType": "full-stack-package",