npm - @futdevpro/fsm-dynamo - Versions diffs - 1.20.103 → 1.20.105 - Mend

@futdevpro/fsm-dynamo 1.20.103 → 1.20.105

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/build/_models/control-models/data-property-params.control-model.js CHANGED Viewed

@@ -36,7 +36,7 @@ class DyFM_DataPropertyParams_ControlModel extends data_property_settings_contro
                     `\n stackLocation: ${(0, stack_util_1.DyFM_getConstructionStackLocation)(2)}`);
             }
             if (set.dependencyDataName) {
-                if (set.required === false) {
+                if (set.required === false && !set.isOptionalDependency) {
                     log_util_1.DyFM_Log.warn('DYNAMO WARNING: ', `\n required is not recommended to be false if dependency is set at "${set.key}" in ` +
                         `"${parentDataParams?.dataName}" model.` +
                         `\n stackLocation: ${(0, stack_util_1.DyFM_getConstructionStackLocation)(2)}`);

package/build/_models/control-models/data-property-params.control-model.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"data-property-params.control-model.js","sourceRoot":"","sources":["../../../src/_models/control-models/data-property-params.control-model.ts"],"names":[],"mappings":";;;AAAA,gEAA6D;AAC7D,oEAAwF;AACxF,oFAAgF;AAEhF,iGAAoF;AAUpF,qFAAqF;AAErF;6DAC6D;AAC7D;;;;;;;;;;;GAWG;AACH,MAAa,oCACX,SAAQ,iEAA8C;IACtD;QACE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,0BAA0B,EAAE,CAAC,CAAC;IAC7E,CAAC;IAED,mEAAmE;IACnE,0DAA0D;IAEjD,oBAAoB,GAA2D,EAAE,CAAC;IAE3F,YACE,GAAmD,EACnD,gBAA6C;QAE7C,KAAK,EAAE,CAAC;QAER,IAAI,GAAG,EAAE,CAAC;YACR,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;gBAChC,mBAAQ,CAAC,KAAK,CACZ,gBAAgB,EAChB,2DAA2D,GAAG,CAAC,GAAG,OAAO;oBACvE,IAAI,gBAAgB,EAAE,QAAQ,UAAU;oBAC1C,qBAAqB,IAAA,8CAAiC,EAAC,CAAC,CAAC,EAAE,CAC5D,CAAC;YACJ,CAAC;YAED,IAAI,GAAG,CAAC,kBAAkB,EAAE,CAAC;gBAC3B,IAAI,GAAG,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;~~oBAC3B~~,mBAAQ,CAAC,IAAI,CACX,kBAAkB,EAClB,uEAAuE,GAAG,CAAC,GAAG,OAAO;wBACrF,IAAI,gBAAgB,EAAE,QAAQ,UAAU;wBACxC,qBAAqB,IAAA,8CAAiC,EAAC,CAAC,CAAC,EAAE,CAC5D,CAAC;gBACJ,CAAC;qBAAM,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;oBACtC,mBAAQ,CAAC,IAAI,CACX,kBAAkB,EAClB,iEAAiE,GAAG,CAAC,GAAG,OAAO;wBAC7E,IAAI,gBAAgB,EAAE,QAAQ,UAAU;wBAC1C,iDAAiD;wBACjD,6DAA6D;wBAC7D,qBAAqB,IAAA,8CAAiC,EAAC,CAAC,CAAC,EAAE,CAC5D,CAAC;oBACF,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC;gBACtB,CAAC;YACH,CAAC;YAED,IAAI,GAAG,CAAC,cAAc,EAAE,CAAC;gBACvB,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;oBACd,mBAAQ,CAAC,IAAI,CACX,kBAAkB,EAClB,kFAAkF,GAAG,CAAC,GAAG,OAAO;wBAC9F,IAAI,gBAAgB,EAAE,QAAQ,UAAU;wBAC1C,8DAA8D;wBAC9D,qBAAqB,IAAA,8CAAiC,EAAC,CAAC,CAAC,EAAE,CAC5D,CAAC;oBAEF,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC;gBACpB,CAAC;gBAED,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,CAAC;oBAC3B,mBAAQ,CAAC,MAAM,CACb,kBAAkB,EAClB,iEAAiE,GAAG,CAAC,GAAG,OAAO;wBAC7E,IAAI,gBAAgB,EAAE,QAAQ,gCAAgC,GAAG,CAAC,GAAG,eAAe;wBACtF,qBAAqB,IAAA,8CAAiC,EAAC,CAAC,CAAC,EAAE,CAC5D,CAAC;oBACF,GAAG,CAAC,iBAAiB,GAAG,GAAG,CAAC,GAAG,CAAC;gBAClC,CAAC;YACH,CAAC;YAED,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC3B,CAAC;aAAM,CAAC;YACN,mBAAQ,CAAC,KAAK,CACZ,gBAAgB,EAChB,+DAA+D,IAAI,CAAC,GAAG,IAAI;gBAC3E,qBAAqB,IAAA,8CAAiC,EAAC,CAAC,CAAC,EAAE,CAC5D,CAAC;QACJ,CAAC;IACH,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC;IACd,CAAC;IAED,sCAAsC;IACtC,SAAS;QACP,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAClB,KAAK,kDAAuB,CAAC,MAAM;gBACjC,OAAO,MAAM,CAAC;YAEhB,KAAK,kDAAuB,CAAC,MAAM;gBACjC,OAAO,MAAM,CAAC;YAEhB,KAAK,kDAAuB,CAAC,OAAO;gBAClC,OAAO,OAAO,CAAC;YAEjB,KAAK,kDAAuB,CAAC,IAAI;gBAC/B,OAAO,IAAI,CAAC;YAEd,KAAK,kDAAuB,CAAC,MAAM,CAAC;YACpC;gBACE,IAAI,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC9B,OAAO,KAAK,CAAC;gBACf,CAAC;qBAAM,IAAI,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;oBACxE,OAAO,QAAQ,CAAC;gBAClB,CAAC;qBAAM,CAAC;oBACN,OAAO,MAAM,CAAC;gBAChB,CAAC;QACL,CAAC;IACH,CAAC;CACF;AAhHD,oFAgHC;AAGgD,wEAAwB"}
1	+ {"version":3,"file":"data-property-params.control-model.js","sourceRoot":"","sources":["../../../src/_models/control-models/data-property-params.control-model.ts"],"names":[],"mappings":"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"}

package/build/_models/control-models/data-property-settings.control-model.d.ts CHANGED Viewed

@@ -26,6 +26,13 @@ export declare class DyFM_DataPropertySettings_ControlModel<T_Property, T_Data>
     encrypt?: DyFM_DeprecatedBooleanAlias;
     isEncrypted?: boolean;
     dependencyDataName?: string;
+    /**
+     * The dependency is DELIBERATELY optional (`required: false` + `dependencyDataName`) — e.g. an anonymous feedback
+     * whose owner account may be missing, yet "my feedbacks" still lists by it. Silences the "required is not
+     * recommended to be false" warning, which otherwise printed on every boot of every consumer (measured 2026-09-25:
+     * every `fdp` command, after the feedback model's owner became optional in BFR-FUTDEVPRO-033).
+     */
+    isOptionalDependency?: boolean;
     /** @deprecated Use isArchiveable; archiveable remains the serialized compatibility key. */
     archiveable?: DyFM_DeprecatedBooleanAlias;
     isArchiveable?: boolean;

package/build/_models/control-models/data-property-settings.control-model.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"data-property-settings.control-model.d.ts","sourceRoot":"","sources":["../../../src/_models/control-models/data-property-settings.control-model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAC;AAChF,OAAO,EAAE,2BAA2B,EAAE,MAAM,wCAAwC,CAAC;AACrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAE3E,+DAA+D;AAC/D,qBAAa,sCAAsC,CAAC,UAAU,EAAE,MAAM;IAKpE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAG,uBAAuB,GAAG,MAAM,CAAC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,UAAU,CAAC;IAErB,iFAAiF;IACjF,MAAM,CAAC,EAAE,2BAA2B,CAAC;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,EAAE,2BAA2B,CAAC;IAC/B,UAAU,CAAC,EAAE,OAAO,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,EAAE,2BAA2B,CAAC;IAC/B,UAAU,CAAC,EAAE,OAAO,CAAC;IAC7B,iFAAiF;IACjF,KAAK,CAAC,EAAE,2BAA2B,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;IAC5B,uFAAuF;IACvF,SAAS,CAAC,EAAE,2BAA2B,CAAC;IAChC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC9B,qFAAqF;IACrF,OAAO,CAAC,EAAE,2BAA2B,CAAC;IAC9B,WAAW,CAAC,EAAE,OAAO,CAAC;IAE9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2FAA2F;IAC3F,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAClC,aAAa,CAAC,EAAE,OAAO,CAAC;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oGAAoG;IACpG,eAAe,CAAC,EAAE,2BAA2B,CAAC;IACtC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACrC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAC3C,oBAAoB,CAAC,EAAE,CAAC,CAAC,aAAa,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,EAAE,CAAC;CAC9E;AA6BD,gGAAgG;AAChG,OAAO,EAAE,sCAAsC,IAAI,0BAA0B,EAAE,CAAC"}
1	+ {"version":3,"file":"data-property-settings.control-model.d.ts","sourceRoot":"","sources":["../../../src/_models/control-models/data-property-settings.control-model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAC;AAChF,OAAO,EAAE,2BAA2B,EAAE,MAAM,wCAAwC,CAAC;AACrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAE3E,+DAA+D;AAC/D,qBAAa,sCAAsC,CAAC,UAAU,EAAE,MAAM;IAKpE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAG,uBAAuB,GAAG,MAAM,CAAC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,UAAU,CAAC;IAErB,iFAAiF;IACjF,MAAM,CAAC,EAAE,2BAA2B,CAAC;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,EAAE,2BAA2B,CAAC;IAC/B,UAAU,CAAC,EAAE,OAAO,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,EAAE,2BAA2B,CAAC;IAC/B,UAAU,CAAC,EAAE,OAAO,CAAC;IAC7B,iFAAiF;IACjF,KAAK,CAAC,EAAE,2BAA2B,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;IAC5B,uFAAuF;IACvF,SAAS,CAAC,EAAE,2BAA2B,CAAC;IAChC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC9B,qFAAqF;IACrF,OAAO,CAAC,EAAE,2BAA2B,CAAC;IAC9B,WAAW,CAAC,EAAE,OAAO,CAAC;IAE9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,2FAA2F;IAC3F,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAClC,aAAa,CAAC,EAAE,OAAO,CAAC;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oGAAoG;IACpG,eAAe,CAAC,EAAE,2BAA2B,CAAC;IACtC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACrC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAC3C,oBAAoB,CAAC,EAAE,CAAC,CAAC,aAAa,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,EAAE,CAAC;CAC9E;AA6BD,gGAAgG;AAChG,OAAO,EAAE,sCAAsC,IAAI,0BAA0B,EAAE,CAAC"}

package/build/_models/control-models/data-property-settings.control-model.js CHANGED Viewed

@@ -23,6 +23,13 @@ class DyFM_DataPropertySettings_ControlModel {
     /** @deprecated Use isEncrypted; encrypt remains the serialized compatibility key. */
     encrypt;
     dependencyDataName;
+    /**
+     * The dependency is DELIBERATELY optional (`required: false` + `dependencyDataName`) — e.g. an anonymous feedback
+     * whose owner account may be missing, yet "my feedbacks" still lists by it. Silences the "required is not
+     * recommended to be false" warning, which otherwise printed on every boot of every consumer (measured 2026-09-25:
+     * every `fdp` command, after the feedback model's owner became optional in BFR-FUTDEVPRO-033).
+     */
+    isOptionalDependency;
     /** @deprecated Use isArchiveable; archiveable remains the serialized compatibility key. */
     archiveable;
     archiveListAfter;

package/build/_models/control-models/data-property-settings.control-model.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"data-property-settings.control-model.js","sourceRoot":"","sources":["../../../src/_models/control-models/data-property-settings.control-model.ts"],"names":[],"mappings":";;;AAIA,+DAA+D;AAC/D,MAAa,sCAAsC;IACjD;QACE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,4BAA4B,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,GAAG,CAAU;IACb,IAAI,CAAoC;IACxC,YAAY,CAAU;IACtB,OAAO,CAAc;IAErB,iFAAiF;IACjF,MAAM,CAA+B;IAErC,qFAAqF;IACrF,QAAQ,CAA+B;IAEvC,qFAAqF;IACrF,QAAQ,CAA+B;IAEvC,iFAAiF;IACjF,KAAK,CAA+B;IAEpC,uFAAuF;IACvF,SAAS,CAA+B;IAExC,qFAAqF;IACrF,OAAO,CAA+B;IAGtC,kBAAkB,CAAU;IAC5B,2FAA2F;IAC3F,WAAW,CAA+B;IAE1C,gBAAgB,CAAU;IAC1B,cAAc,CAAY;IAC1B,cAAc,CAAU;IACxB,oGAAoG;IACpG,eAAe,CAA+B;IAE9C,iBAAiB,CAAU;IAC3B,SAAS,CAAU;IACnB,SAAS,CAAU;IACnB,eAAe,CAA4B;IAC3C,oBAAoB,CAAyD;CAC9E;~~AA5CD~~,~~wFA4CC~~;AA8BkD,4EAA0B;AA5B7E,MAAM,cAAc,GAA2C;IAC7D,CAAE,QAAQ,EAAE,UAAU,CAAE;IACxB,CAAE,UAAU,EAAE,YAAY,CAAE;IAC5B,CAAE,UAAU,EAAE,YAAY,CAAE;IAC5B,CAAE,OAAO,EAAE,WAAW,CAAE;IACxB,CAAE,WAAW,EAAE,aAAa,CAAE;IAC9B,CAAE,SAAS,EAAE,aAAa,CAAE;IAC5B,CAAE,aAAa,EAAE,eAAe,CAAE;IAClC,CAAE,iBAAiB,EAAE,oBAAoB,CAAE;CAC5C,CAAC;AAEF,cAAc,CAAC,OAAO,CAAC,CAAC,YAAuC,EAAQ,EAAE;IACvE,MAAM,UAAU,GAAW,YAAY,CAAC,CAAC,CAAC,CAAC;IAC3C,MAAM,aAAa,GAAW,YAAY,CAAC,CAAC,CAAC,CAAC;IAE9C,MAAM,CAAC,cAAc,CAAC,sCAAsC,CAAC,SAAS,EAAE,aAAa,EAAE;QACrF,YAAY,EAAE,IAAI;QAClB,UAAU,EAAE,KAAK;QACjB,GAAG,EAAE;YACH,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC;QAC1B,CAAC;QACD,GAAG,EAAE,UAAU,OAA4B;YACzC,IAAI,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC;QAC7B,CAAC;KACF,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
1	+ {"version":3,"file":"data-property-settings.control-model.js","sourceRoot":"","sources":["../../../src/_models/control-models/data-property-settings.control-model.ts"],"names":[],"mappings":";;;AAIA,+DAA+D;AAC/D,MAAa,sCAAsC;IACjD;QACE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,4BAA4B,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,GAAG,CAAU;IACb,IAAI,CAAoC;IACxC,YAAY,CAAU;IACtB,OAAO,CAAc;IAErB,iFAAiF;IACjF,MAAM,CAA+B;IAErC,qFAAqF;IACrF,QAAQ,CAA+B;IAEvC,qFAAqF;IACrF,QAAQ,CAA+B;IAEvC,iFAAiF;IACjF,KAAK,CAA+B;IAEpC,uFAAuF;IACvF,SAAS,CAA+B;IAExC,qFAAqF;IACrF,OAAO,CAA+B;IAGtC,kBAAkB,CAAU;IAC5B;;;;;OAKG;IACH,oBAAoB,CAAW;IAC/B,2FAA2F;IAC3F,WAAW,CAA+B;IAE1C,gBAAgB,CAAU;IAC1B,cAAc,CAAY;IAC1B,cAAc,CAAU;IACxB,oGAAoG;IACpG,eAAe,CAA+B;IAE9C,iBAAiB,CAAU;IAC3B,SAAS,CAAU;IACnB,SAAS,CAAU;IACnB,eAAe,CAA4B;IAC3C,oBAAoB,CAAyD;CAC9E;AAnDD,wFAmDC;AA8BkD,4EAA0B;AA5B7E,MAAM,cAAc,GAA2C;IAC7D,CAAE,QAAQ,EAAE,UAAU,CAAE;IACxB,CAAE,UAAU,EAAE,YAAY,CAAE;IAC5B,CAAE,UAAU,EAAE,YAAY,CAAE;IAC5B,CAAE,OAAO,EAAE,WAAW,CAAE;IACxB,CAAE,WAAW,EAAE,aAAa,CAAE;IAC9B,CAAE,SAAS,EAAE,aAAa,CAAE;IAC5B,CAAE,aAAa,EAAE,eAAe,CAAE;IAClC,CAAE,iBAAiB,EAAE,oBAAoB,CAAE;CAC5C,CAAC;AAEF,cAAc,CAAC,OAAO,CAAC,CAAC,YAAuC,EAAQ,EAAE;IACvE,MAAM,UAAU,GAAW,YAAY,CAAC,CAAC,CAAC,CAAC;IAC3C,MAAM,aAAa,GAAW,YAAY,CAAC,CAAC,CAAC,CAAC;IAE9C,MAAM,CAAC,cAAc,CAAC,sCAAsC,CAAC,SAAS,EAAE,aAAa,EAAE;QACrF,YAAY,EAAE,IAAI;QAClB,UAAU,EAAE,KAAK;QACjB,GAAG,EAAE;YACH,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC;QAC1B,CAAC;QACD,GAAG,EAAE,UAAU,OAA4B;YACzC,IAAI,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC;QAC7B,CAAC;KACF,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/build/_modules/game/_models/narration-player.control-model.d.ts ADDED Viewed

@@ -0,0 +1,53 @@
+import { DyFM_NarrationLine, DyFM_NarrationPlayer_Options, DyFM_NarrationState } from './narration-player.interface';
+/**
+ * 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 declare class DyFM_NarrationPlayer_ControlModel {
+    private readonly options;
+    private readonly listeners;
+    private audio;
+    private revision;
+    private lastLine;
+    private state;
+    constructor(options: DyFM_NarrationPlayer_Options);
+    /** A copy of the current state. */
+    getState(): DyFM_NarrationState;
+    /** Subscribe to state changes; returns the unsubscribe. A throwing listener is logged and isolated. */
+    onChange(listener: (state: DyFM_NarrationState) => void): () => void;
+    /** Marks a user gesture — from now on automatic narration may play. */
+    activate(): void;
+    /** Plays a line (automatic path: respects the gesture gate). */
+    playLine(line: DyFM_NarrationLine): Promise<boolean>;
+    /** Plays a catalog entry; an unknown key refuses with `unknown-line`. */
+    playCatalog(key: string): Promise<boolean>;
+    /** From a user gesture: activates the session, then plays. */
+    activateAndPlay(line: DyFM_NarrationLine): Promise<boolean>;
+    /** Replays the last requested line (a replay button is a gesture). */
+    replay(): Promise<boolean>;
+    /** Stops the active line (or clears a blocked / failed one). */
+    stop(): void;
+    setEnabled(enabled: boolean): void;
+    setVolume(volume: number): void;
+    /** Re-applies the effective volume (call it when the game's master volume / mute changes); 0 stops the line. */
+    applyVolume(): void;
+    private play;
+    private detach;
+    private effectiveVolume;
+    private set;
+    private loadSettings;
+    private saveSettings;
+}
+//# sourceMappingURL=narration-player.control-model.d.ts.map

package/build/_modules/game/_models/narration-player.control-model.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"narration-player.control-model.d.ts","sourceRoot":"","sources":["../../../../src/_modules/game/_models/narration-player.control-model.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,kBAAkB,EAClB,4BAA4B,EAE5B,mBAAmB,EACpB,MAAM,8BAA8B,CAAC;AAEtC;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,iCAAiC;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgD;IAC1E,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,KAAK,CAGX;gBAEU,OAAO,EAAE,4BAA4B;IAKjD,mCAAmC;IACnC,QAAQ,IAAI,mBAAmB;IAI/B,uGAAuG;IACvG,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAAG,MAAM,IAAI;IAYpE,uEAAuE;IACvE,QAAQ,IAAI,IAAI;IAMhB,gEAAgE;IAC1D,QAAQ,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAI1D,yEAAyE;IACnE,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYhD,8DAA8D;IACxD,eAAe,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAMjE,sEAAsE;IAChE,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAShC,gEAAgE;IAChE,IAAI,IAAI,IAAI;IAMZ,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAQlC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAM/B,gHAAgH;IAChH,WAAW,IAAI,IAAI;YAWL,IAAI;IA4DlB,OAAO,CAAC,MAAM;IAgBd,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,GAAG;IAcX,OAAO,CAAC,YAAY;IAsBpB,OAAO,CAAC,YAAY;CAYrB"}

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

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DyFM_NarrationPlayer_ControlModel = void 0;
+const log_util_1 = require("../../../_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`.
+ */
+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) {
+                log_util_1.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) {
+                log_util_1.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)
+            log_util_1.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) {
+            log_util_1.DyFM_Log.error(`DyFM_NarrationPlayer: settings could not be saved under '${settings.key}'`, error);
+        }
+    }
+}
+exports.DyFM_NarrationPlayer_ControlModel = DyFM_NarrationPlayer_ControlModel;
+//# sourceMappingURL=narration-player.control-model.js.map

package/build/_modules/game/_models/narration-player.control-model.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"narration-player.control-model.js","sourceRoot":"","sources":["../../../../src/_modules/game/_models/narration-player.control-model.ts"],"names":[],"mappings":"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"}

package/build/_modules/game/_models/narration-player.interface.d.ts ADDED Viewed

@@ -0,0 +1,64 @@
+/** BFR-WARFACTORY-014 — one narration line: the asset is the core address, the subtitle the always-available fallback. */
+export interface DyFM_NarrationLine {
+    /** Stable id (a catalog key or an asset id). */
+    lineId: string;
+    /** The audio source (URL / path) — resolved by the audio factory. */
+    src: string;
+    /** Shown while it plays AND when it cannot play (blocked / failed): the text is never lost. */
+    subtitle?: string;
+}
+/**
+ * The audio element surface the player uses — structural, so an `HTMLAudioElement` fits it and specs can use a fake.
+ * `play()` rejects with a `NotAllowedError`-named error when the browser blocks autoplay.
+ */
+export interface DyFM_NarrationAudio_Interface {
+    volume: number;
+    currentTime: number;
+    onended: (() => void) | null;
+    onerror: (() => void) | null;
+    play(): Promise<void>;
+    pause(): void;
+}
+/** A persisted-settings store (e.g. `localStorage`); optional. */
+export interface DyFM_NarrationSettingsStore_Interface {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+export interface DyFM_NarrationPlayer_Options {
+    /** Creates the audio for a source — in a browser: `(src) => new Audio(src)`. */
+    audioFactory: (src: string) => DyFM_NarrationAudio_Interface;
+    /**
+     * When true, `play()` only plays after `activate()` (a user gesture) — automatic narration then refuses with
+     * `no-gesture` instead of hitting the browser's autoplay block. `activateAndPlay()` / `replay()` count as a gesture.
+     */
+    requireGesture?: boolean;
+    /** The game's master volume 0..1 (and mute as 0) — multiplied into the narration volume. Default: 1. */
+    masterVolume?: () => number;
+    /** Optional catalog: `playCatalog(key)` resolves through it (an asset-id layer on top of the core). */
+    catalog?: Record<string, DyFM_NarrationLine>;
+    /** Optional settings persistence (enabled + volume). */
+    settings?: {
+        store: DyFM_NarrationSettingsStore_Interface;
+        key: string;
+    };
+}
+export type DyFM_NarrationPlayback_Type = 'idle' | 'playing' | 'blocked' | 'failed';
+/**
+ * Why the last `play` did not play — the diagnosis a silent narration otherwise lacks.
+ * `autoplay-blocked` is the one the UI must tell the player about ("click to enable sound").
+ */
+export type DyFM_NarrationRefusal_Type = 'disabled' | 'muted' | 'no-gesture' | 'autoplay-blocked' | 'error' | 'unknown-line';
+/** Everything a UI needs (the five WF signals + the subtitle + the refusal reason). */
+export interface DyFM_NarrationState {
+    playback: DyFM_NarrationPlayback_Type;
+    /** The line playing, or the one that could not play (blocked / failed) — null when idle. */
+    activeLineId: string | null;
+    /** The active line's subtitle (also while blocked / failed — the text fallback). */
+    subtitle: string | null;
+    enabled: boolean;
+    /** The narration's own volume 0..1 (before the master volume). */
+    volume: number;
+    sessionActivated: boolean;
+    lastRefusal: DyFM_NarrationRefusal_Type | null;
+}
+//# sourceMappingURL=narration-player.interface.d.ts.map

package/build/_modules/game/_models/narration-player.interface.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"narration-player.interface.d.ts","sourceRoot":"","sources":["../../../../src/_modules/game/_models/narration-player.interface.ts"],"names":[],"mappings":"AAAA,0HAA0H;AAC1H,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7B,OAAO,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,kEAAkE;AAClE,MAAM,WAAW,qCAAqC;IACpD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,4BAA4B;IAC3C,gFAAgF;IAChF,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,6BAA6B,CAAC;IAC7D;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,wGAAwG;IACxG,YAAY,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,uGAAuG;IACvG,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC7C,wDAAwD;IACxD,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,qCAAqC,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1E;AAED,MAAM,MAAM,2BAA2B,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEpF;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAAG,UAAU,GAAG,OAAO,GAAG,YAAY,GAAG,kBAAkB,GAAG,OAAO,GAAG,cAAc,CAAC;AAE7H,uFAAuF;AACvF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,2BAA2B,CAAC;IACtC,4FAA4F;IAC5F,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,oFAAoF;IACpF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,OAAO,CAAC;IAC1B,WAAW,EAAE,0BAA0B,GAAG,IAAI,CAAC;CAChD"}

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

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=narration-player.interface.js.map

package/build/_modules/game/_models/narration-player.interface.js.map ADDED Viewed

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

package/build/_modules/game/index.d.ts CHANGED Viewed

@@ -22,6 +22,8 @@ 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';
 export * from './_collections/audio-mixer.util';
 export * from './_collections/audio-scale.util';
 export * from './_collections/game-save.util';

package/build/_modules/game/index.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_modules/game/index.ts"],"names":[],"mappings":"AACA,cAAc,6BAA6B,CAAC;AAG5C,cAAc,wCAAwC,CAAC;AACvD,cAAc,0CAA0C,CAAC;AACzD,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,iCAAiC,CAAC;AAChD,cAAc,yCAAyC,CAAC;AACxD,cAAc,uCAAuC,CAAC;AACtD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,sCAAsC,CAAC;AACrD,cAAc,0CAA0C,CAAC;AACzD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0CAA0C,CAAC;AACzD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,uCAAuC,CAAC;AACtD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,kCAAkC,CAAC;AACjD,cAAc,+CAA+C,CAAC;AAC9D,cAAc,uCAAuC,CAAC;AACtD,cAAc,2CAA2C,CAAC;~~AAG1D~~,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uCAAuC,CAAC"}
1	+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_modules/game/index.ts"],"names":[],"mappings":"AACA,cAAc,6BAA6B,CAAC;AAG5C,cAAc,wCAAwC,CAAC;AACvD,cAAc,0CAA0C,CAAC;AACzD,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,iCAAiC,CAAC;AAChD,cAAc,yCAAyC,CAAC;AACxD,cAAc,uCAAuC,CAAC;AACtD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,sCAAsC,CAAC;AACrD,cAAc,0CAA0C,CAAC;AACzD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0CAA0C,CAAC;AACzD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,uCAAuC,CAAC;AACtD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,kCAAkC,CAAC;AACjD,cAAc,+CAA+C,CAAC;AAC9D,cAAc,uCAAuC,CAAC;AACtD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,sCAAsC,CAAC;AACrD,cAAc,0CAA0C,CAAC;AAGzD,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uCAAuC,CAAC"}

package/build/_modules/game/index.js CHANGED Viewed

@@ -27,6 +27,8 @@ tslib_1.__exportStar(require("./_models/input-action.interface"), exports);
 tslib_1.__exportStar(require("./_models/input-action-registry.control-model"), exports);
 tslib_1.__exportStar(require("./_models/guided-onboarding.interface"), exports);
 tslib_1.__exportStar(require("./_models/guided-onboarding.control-model"), exports);
+tslib_1.__exportStar(require("./_models/narration-player.interface"), exports);
+tslib_1.__exportStar(require("./_models/narration-player.control-model"), exports);
 // COLLECTIONS
 tslib_1.__exportStar(require("./_collections/audio-mixer.util"), exports);
 tslib_1.__exportStar(require("./_collections/audio-scale.util"), exports);

package/build/_modules/game/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/_modules/game/index.ts"],"names":[],"mappings":";;;AAAA,QAAQ;AACR,sEAA4C;AAE5C,SAAS;AACT,iFAAuD;AACvD,mFAAyD;AACzD,gFAAsD;AACtD,8EAAoD;AACpD,0EAAgD;AAChD,kFAAwD;AACxD,gFAAsD;AACtD,qFAA2D;AAC3D,yFAA+D;AAC/D,4EAAkD;AAClD,gFAAsD;AACtD,+EAAqD;AACrD,mFAAyD;AACzD,wEAA8C;AAC9C,mFAAyD;AACzD,uFAA6D;AAC7D,gFAAsD;AACtD,uEAA6C;AAC7C,2EAAiD;AACjD,2EAAiD;AACjD,wFAA8D;AAC9D,gFAAsD;AACtD,oFAA0D;~~AAE1D~~,cAAc;AACd,0EAAgD;AAChD,0EAAgD;AAChD,wEAA8C;AAC9C,gFAAsD"}
1	+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/_modules/game/index.ts"],"names":[],"mappings":";;;AAAA,QAAQ;AACR,sEAA4C;AAE5C,SAAS;AACT,iFAAuD;AACvD,mFAAyD;AACzD,gFAAsD;AACtD,8EAAoD;AACpD,0EAAgD;AAChD,kFAAwD;AACxD,gFAAsD;AACtD,qFAA2D;AAC3D,yFAA+D;AAC/D,4EAAkD;AAClD,gFAAsD;AACtD,+EAAqD;AACrD,mFAAyD;AACzD,wEAA8C;AAC9C,mFAAyD;AACzD,uFAA6D;AAC7D,gFAAsD;AACtD,uEAA6C;AAC7C,2EAAiD;AACjD,2EAAiD;AACjD,wFAA8D;AAC9D,gFAAsD;AACtD,oFAA0D;AAC1D,+EAAqD;AACrD,mFAAyD;AAEzD,cAAc;AACd,0EAAgD;AAChD,0EAAgD;AAChD,wEAA8C;AAC9C,gFAAsD"}

package/build-esm/_models/control-models/data-property-params.control-model.js CHANGED Viewed

@@ -33,7 +33,7 @@ export class DyFM_DataPropertyParams_ControlModel extends DyFM_DataProperty_Sett
                     `\n stackLocation: ${DyFM_getConstructionStackLocation(2)}`);
             }
             if (set.dependencyDataName) {
-                if (set.required === false) {
+                if (set.required === false && !set.isOptionalDependency) {
                     DyFM_Log.warn('DYNAMO WARNING: ', `\n required is not recommended to be false if dependency is set at "${set.key}" in ` +
                         `"${parentDataParams?.dataName}" model.` +
                         `\n stackLocation: ${DyFM_getConstructionStackLocation(2)}`);

package/build-esm/_models/control-models/data-property-settings.control-model.js CHANGED Viewed

@@ -20,6 +20,13 @@ export class DyFM_DataPropertySettings_ControlModel {
     /** @deprecated Use isEncrypted; encrypt remains the serialized compatibility key. */
     encrypt;
     dependencyDataName;
+    /**
+     * The dependency is DELIBERATELY optional (`required: false` + `dependencyDataName`) — e.g. an anonymous feedback
+     * whose owner account may be missing, yet "my feedbacks" still lists by it. Silences the "required is not
+     * recommended to be false" warning, which otherwise printed on every boot of every consumer (measured 2026-09-25:
+     * every `fdp` command, after the feedback model's owner became optional in BFR-FUTDEVPRO-033).
+     */
+    isOptionalDependency;
     /** @deprecated Use isArchiveable; archiveable remains the serialized compatibility key. */
     archiveable;
     archiveListAfter;

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

@@ -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 ADDED Viewed

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

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

@@ -24,6 +24,8 @@ 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 CHANGED Viewed

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