@vived/host 4.6.0 → 4.8.0

package/dist/esm/StateMachine/Entities/HostEditingStateEntity.js

@@ -1,15 +1,39 @@
 import { MemoizedBoolean } from "@vived/core";
 import { getSingletonComponent, AppObjectEntity } from "@vived/core";
 import { HostStateMachine } from "./HostStateMachine";
+/**
+ * HostEditingStateEntity handles the editing workflow for state entities.
+ *
+ * This singleton component manages the process of creating new states or editing
+ * existing states in the host state machine. It tracks changes made during editing,
+ * maintains the original state for cancellation/rollback, and provides validation.
+ *
+ * The component implements a standard editing pattern:
+ * 1. Start editing (startEditing) or create new (startNewState)
+ * 2. Make changes to the editingState directly
+ * 3. Complete with either finishEditing (commit) or cancelEditState (rollback)
+ *
+ * This entity is a critical part of the state authoring workflow and works closely
+ * with HostStateMachine and HostStateEntity.
+ */
 export class HostEditingStateEntity extends AppObjectEntity {
     static get(appObjects) {
         return getSingletonComponent(HostEditingStateEntity.type, appObjects);
     }
 }
 HostEditingStateEntity.type = "HostEditingStateEntity";
+/**
+ * Factory function for creating a HostEditingStateEntity instance
+ * @param appObject The AppObject to associate with this entity
+ * @returns A new HostEditingStateEntity instance
+ */
 export function makeHostEditingStateEntity(appObject) {
     return new HostEditingStateEntityImp(appObject);
 }
+/**
+ * Implementation of the HostEditingStateEntity abstract class
+ * Manages the state editing workflow and tracks changes
+ */
 class HostEditingStateEntityImp extends HostEditingStateEntity {
     get editingState() {
         return this._editingState;
@@ -29,6 +53,10 @@ class HostEditingStateEntityImp extends HostEditingStateEntity {
         this._stateValidationMessage = val;
         this.notifyOnChange();
     }
+    /**
+     * Reference to the HostStateMachine singleton
+     * Used for creating and managing states
+     */
     get hostStateMachine() {
         return this.getCachedSingleton(HostStateMachine.type);
     }
@@ -38,7 +66,16 @@ class HostEditingStateEntityImp extends HostEditingStateEntity {
     constructor(appObject) {
         super(appObject, HostEditingStateEntity.type);
         this._isNewState = false;
+        /**
+         * Tracks whether changes have been made to the state being edited
+         * Uses a memoized value to efficiently notify observers only when value changes
+         */
         this.memoizedSomethingHasChanged = new MemoizedBoolean(false, this.notifyOnChange);
+        /**
+         * Compares the current state with the original state to detect changes
+         * Performs deep comparison of all relevant properties
+         * @returns true if changes were detected, false otherwise
+         */
         this.checkForChange = () => {
             if (!this._editingState)
                 return false;
@@ -66,9 +103,17 @@ class HostEditingStateEntityImp extends HostEditingStateEntity {
                 return true;
             return false;
         };
+        /**
+         * Observer callback for state changes
+         * Updates the somethingHasChanged flag when the state being edited changes
+         */
         this.onStateEntityChange = () => {
             this.memoizedSomethingHasChanged.val = this.checkForChange();
         };
+        /**
+         * Creates a new state and begins editing it
+         * @returns The newly created state entity or undefined if creation failed
+         */
         this.startNewState = () => {
             if (!this.hostStateMachine)
                 return;
@@ -79,12 +124,21 @@ class HostEditingStateEntityImp extends HostEditingStateEntity {
             this.memoizedSomethingHasChanged.val = true;
             return this._editingState;
         };
+        /**
+         * Begins editing an existing state
+         * @param state The state entity to edit
+         */
         this.startEditing = (state) => {
             this._editingState = state;
             this.originalStateData = state.getDTO();
             this._editingState.addChangeObserver(this.onStateEntityChange);
             this.notifyOnChange();
         };
+        /**
+         * Cancels editing and reverts changes
+         * For new states, removes them from the state machine
+         * For existing states, restores the original values
+         */
         this.cancelEditState = () => {
             if (!this._editingState)
                 return;
@@ -96,9 +150,17 @@ class HostEditingStateEntityImp extends HostEditingStateEntity {
             }
             this.resetInternalState();
         };
+        /**
+         * Completes editing, keeping all changes
+         * Simply cleans up the internal state without reverting changes
+         */
         this.finishEditing = () => {
             this.resetInternalState();
         };
+        /**
+         * Resets the internal state after editing is complete
+         * Cleans up observers and notifies clients of the change
+         */
         this.resetInternalState = () => {
             if (!this._editingState)
                 return;

package/dist/esm/StateMachine/Entities/HostEditingStateEntity.js.map

@@ -1 +1 @@
-{"version":3,"file":"HostEditingStateEntity.js","sourceRoot":"","sources":["../../../../src/StateMachine/Entities/HostEditingStateEntity.ts"],"names":[],"mappings":"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","sourcesContent":["import { MemoizedBoolean } from \"@vived/core\";\r\nimport {\r\n  getSingletonComponent,\r\n  AppObject,\r\n  AppObjectEntity,\r\n  AppObjectRepo\r\n} from \"@vived/core\";\r\nimport { HostStateEntity, StateDTO } from \"./HostStateEntity\";\r\nimport { HostStateMachine } from \"./HostStateMachine\";\r\n\r\nexport abstract class HostEditingStateEntity extends AppObjectEntity {\r\n  static type = \"HostEditingStateEntity\";\r\n\r\n  abstract get isEditing(): boolean;\r\n  abstract get isNewState(): boolean;\r\n  abstract get editingState(): HostStateEntity | undefined;\r\n  abstract get somethingHasChanged(): boolean;\r\n  abstract stateValidationMessage?: string;\r\n\r\n  abstract startNewState(): HostStateEntity | undefined;\r\n  abstract startEditing(state: HostStateEntity): void;\r\n  abstract cancelEditState(): void;\r\n  abstract finishEditing(): void;\r\n\r\n  static get(appObjects: AppObjectRepo) {\r\n    return getSingletonComponent<HostEditingStateEntity>(\r\n      HostEditingStateEntity.type,\r\n      appObjects\r\n    );\r\n  }\r\n}\r\n\r\nexport function makeHostEditingStateEntity(\r\n  appObject: AppObject\r\n): HostEditingStateEntity {\r\n  return new HostEditingStateEntityImp(appObject);\r\n}\r\n\r\nclass HostEditingStateEntityImp extends HostEditingStateEntity {\r\n  private originalStateData?: StateDTO;\r\n  \r\n  private _editingState?: HostStateEntity;\r\n  get editingState() {\r\n    return this._editingState;\r\n  }\r\n\r\n  get isEditing(): boolean {\r\n    return this._editingState !== undefined;\r\n  }\r\n\r\n  private _isNewState = false;\r\n  get isNewState(): boolean {\r\n    return this._isNewState;\r\n  }\r\n\r\n  private _stateValidationMessage?: string | undefined;\r\n  get stateValidationMessage(): string | undefined {\r\n    return this._stateValidationMessage;\r\n  }\r\n  set stateValidationMessage(val: string | undefined) {\r\n    if (this._stateValidationMessage === val) return;\r\n\r\n    this._stateValidationMessage = val;\r\n    this.notifyOnChange();\r\n  }\r\n\r\n  private get hostStateMachine() {\r\n    return this.getCachedSingleton<HostStateMachine>(HostStateMachine.type);\r\n  }\r\n\r\n  private memoizedSomethingHasChanged = new MemoizedBoolean(\r\n    false,\r\n    this.notifyOnChange\r\n  );\r\n  get somethingHasChanged(): boolean {\r\n    return this.memoizedSomethingHasChanged.val;\r\n  }\r\n\r\n  private checkForChange = () => {\r\n    if (!this._editingState) return false;\r\n    if (!this.originalStateData) return true;\r\n\r\n    if (this._editingState.name !== this.originalStateData.name) return true;\r\n\r\n    if (this._editingState.expectedResponse !== this.originalStateData.response)\r\n      return true;\r\n\r\n    if (\r\n      this._editingState.assets.length !== this.originalStateData.assets.length\r\n    )\r\n      return true;\r\n    let assetsHaveChanged = false;\r\n    this._editingState.assets.forEach((currentAssetID, i) => {\r\n      const originalAssetId = this.originalStateData!.assets[i];\r\n      if (originalAssetId !== currentAssetID) {\r\n        assetsHaveChanged = true;\r\n      }\r\n    });\r\n\r\n    if (assetsHaveChanged) {\r\n      return true;\r\n    }\r\n\r\n    const currentDataString = JSON.stringify(this._editingState.stateData);\r\n    const originalData = JSON.stringify(this.originalStateData?.data ?? \"\");\r\n    if (currentDataString !== originalData) return true;\r\n\r\n    return false;\r\n  };\r\n\r\n  private onStateEntityChange = (): void => {\r\n    this.memoizedSomethingHasChanged.val = this.checkForChange();\r\n  };\r\n\r\n  startNewState = (): HostStateEntity | undefined => {\r\n    if (!this.hostStateMachine) return;\r\n\r\n    this.originalStateData = undefined;\r\n    this._isNewState = true;\r\n    this._editingState = this.hostStateMachine.createNewState();\r\n    this._editingState.addChangeObserver(this.onStateEntityChange);\r\n    this.memoizedSomethingHasChanged.val = true;\r\n\r\n    return this._editingState;\r\n  };\r\n\r\n  startEditing = (state: HostStateEntity): void => {\r\n    this._editingState = state;\r\n\r\n    this.originalStateData = state.getDTO();\r\n    this._editingState.addChangeObserver(this.onStateEntityChange);\r\n\r\n    this.notifyOnChange();\r\n  };\r\n\r\n  cancelEditState = (): void => {\r\n    if (!this._editingState) return;\r\n\r\n    if (this.originalStateData) {\r\n      this._editingState.setDTO(this.originalStateData);\r\n    } else {\r\n      this.hostStateMachine?.deleteState(this._editingState.id);\r\n    }\r\n\r\n    this.resetInternalState();\r\n  };\r\n\r\n  finishEditing = (): void => {\r\n    this.resetInternalState();\r\n  };\r\n\r\n  private resetInternalState = () => {\r\n    if (!this._editingState) return;\r\n\r\n    this._isNewState = false;\r\n    this._editingState.removeChangeObserver(this.onStateEntityChange);\r\n    this._stateValidationMessage = undefined;\r\n    this._editingState = undefined;\r\n    this.memoizedSomethingHasChanged.val = false;\r\n    this.notifyOnChange();\r\n  };\r\n\r\n  constructor(appObject: AppObject) {\r\n    super(appObject, HostEditingStateEntity.type);\r\n    this.appObjects.registerSingleton(this);\r\n  }\r\n}\r\n"]}
+{"version":3,"file":"HostEditingStateEntity.js","sourceRoot":"","sources":["../../../../src/StateMachine/Entities/HostEditingStateEntity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,qBAAqB,EAErB,eAAe,EAEhB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAgB,sBAAuB,SAAQ,eAAe;IA2ClE,MAAM,CAAC,GAAG,CAAC,UAAyB;QAClC,OAAO,qBAAqB,CAC1B,sBAAsB,CAAC,IAAI,EAC3B,UAAU,CACX,CAAC;IACJ,CAAC;;AA/CM,2BAAI,GAAG,wBAAwB,CAAC;AAkDzC;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,SAAoB;IAEpB,OAAO,IAAI,yBAAyB,CAAC,SAAS,CAAC,CAAC;AAClD,CAAC;AAED;;;GAGG;AACH,MAAM,yBAA0B,SAAQ,sBAAsB;IAK5D,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,aAAa,KAAK,SAAS,CAAC;IAC1C,CAAC;IAGD,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAGD,IAAI,sBAAsB;QACxB,OAAO,IAAI,CAAC,uBAAuB,CAAC;IACtC,CAAC;IACD,IAAI,sBAAsB,CAAC,GAAuB;QAChD,IAAI,IAAI,CAAC,uBAAuB,KAAK,GAAG;YAAE,OAAO;QAEjD,IAAI,CAAC,uBAAuB,GAAG,GAAG,CAAC;QACnC,IAAI,CAAC,cAAc,EAAE,CAAC;IACxB,CAAC;IAED;;;OAGG;IACH,IAAY,gBAAgB;QAC1B,OAAO,IAAI,CAAC,kBAAkB,CAAmB,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC1E,CAAC;IAUD,IAAI,mBAAmB;QACrB,OAAO,IAAI,CAAC,2BAA2B,CAAC,GAAG,CAAC;IAC9C,CAAC;IAoHD,YAAY,SAAoB;QAC9B,KAAK,CAAC,SAAS,EAAE,sBAAsB,CAAC,IAAI,CAAC,CAAC;QAvJxC,gBAAW,GAAG,KAAK,CAAC;QAwB5B;;;WAGG;QACK,gCAA2B,GAAG,IAAI,eAAe,CACvD,KAAK,EACL,IAAI,CAAC,cAAc,CACpB,CAAC;QAKF;;;;WAIG;QACK,mBAAc,GAAG,GAAG,EAAE;YAC5B,IAAI,CAAC,IAAI,CAAC,aAAa;gBAAE,OAAO,KAAK,CAAC;YACtC,IAAI,CAAC,IAAI,CAAC,iBAAiB;gBAAE,OAAO,IAAI,CAAC;YAEzC,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,KAAK,IAAI,CAAC,iBAAiB,CAAC,IAAI;gBAAE,OAAO,IAAI,CAAC;YAEzE,IAAI,IAAI,CAAC,aAAa,CAAC,gBAAgB,KAAK,IAAI,CAAC,iBAAiB,CAAC,QAAQ;gBACzE,OAAO,IAAI,CAAC;YAEd,IACE,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,KAAK,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,MAAM;gBAEzE,OAAO,IAAI,CAAC;YACd,IAAI,iBAAiB,GAAG,KAAK,CAAC;YAC9B,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,cAAc,EAAE,CAAC,EAAE,EAAE;gBACtD,MAAM,eAAe,GAAG,IAAI,CAAC,iBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;gBAC1D,IAAI,eAAe,KAAK,cAAc,EAAE,CAAC;oBACvC,iBAAiB,GAAG,IAAI,CAAC;gBAC3B,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,IAAI,iBAAiB,EAAE,CAAC;gBACtB,OAAO,IAAI,CAAC;YACd,CAAC;YAED,MAAM,iBAAiB,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;YACvE,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,iBAAiB,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;YACxE,IAAI,iBAAiB,KAAK,YAAY;gBAAE,OAAO,IAAI,CAAC;YAEpD,OAAO,KAAK,CAAC;QACf,CAAC,CAAC;QAEF;;;WAGG;QACK,wBAAmB,GAAG,GAAS,EAAE;YACvC,IAAI,CAAC,2BAA2B,CAAC,GAAG,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QAC/D,CAAC,CAAC;QAEF;;;WAGG;QACH,kBAAa,GAAG,GAAgC,EAAE;YAChD,IAAI,CAAC,IAAI,CAAC,gBAAgB;gBAAE,OAAO;YAEnC,IAAI,CAAC,iBAAiB,GAAG,SAAS,CAAC;YACnC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;YACxB,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,gBAAgB,CAAC,cAAc,EAAE,CAAC;YAC5D,IAAI,CAAC,aAAa,CAAC,iBAAiB,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;YAC/D,IAAI,CAAC,2BAA2B,CAAC,GAAG,GAAG,IAAI,CAAC;YAE5C,OAAO,IAAI,CAAC,aAAa,CAAC;QAC5B,CAAC,CAAC;QAEF;;;WAGG;QACH,iBAAY,GAAG,CAAC,KAAsB,EAAQ,EAAE;YAC9C,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;YAE3B,IAAI,CAAC,iBAAiB,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YACxC,IAAI,CAAC,aAAa,CAAC,iBAAiB,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;YAE/D,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,CAAC,CAAC;QAEF;;;;WAIG;QACH,oBAAe,GAAG,GAAS,EAAE;YAC3B,IAAI,CAAC,IAAI,CAAC,aAAa;gBAAE,OAAO;YAEhC,IAAI,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBAC3B,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;YACpD,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,gBAAgB,EAAE,WAAW,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;YAC5D,CAAC;YAED,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC5B,CAAC,CAAC;QAEF;;;WAGG;QACH,kBAAa,GAAG,GAAS,EAAE;YACzB,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC5B,CAAC,CAAC;QAEF;;;WAGG;QACK,uBAAkB,GAAG,GAAG,EAAE;YAChC,IAAI,CAAC,IAAI,CAAC,aAAa;gBAAE,OAAO;YAEhC,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;YACzB,IAAI,CAAC,aAAa,CAAC,oBAAoB,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;YAClE,IAAI,CAAC,uBAAuB,GAAG,SAAS,CAAC;YACzC,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;YAC/B,IAAI,CAAC,2BAA2B,CAAC,GAAG,GAAG,KAAK,CAAC;YAC7C,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,CAAC,CAAC;QAIA,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;CACF","sourcesContent":["import { MemoizedBoolean } from \"@vived/core\";\r\nimport {\r\n  getSingletonComponent,\r\n  AppObject,\r\n  AppObjectEntity,\r\n  AppObjectRepo\r\n} from \"@vived/core\";\r\nimport { HostStateEntity, StateDTO } from \"./HostStateEntity\";\r\nimport { HostStateMachine } from \"./HostStateMachine\";\r\n\r\n/**\r\n * HostEditingStateEntity handles the editing workflow for state entities.\r\n *\r\n * This singleton component manages the process of creating new states or editing\r\n * existing states in the host state machine. It tracks changes made during editing,\r\n * maintains the original state for cancellation/rollback, and provides validation.\r\n *\r\n * The component implements a standard editing pattern:\r\n * 1. Start editing (startEditing) or create new (startNewState)\r\n * 2. Make changes to the editingState directly\r\n * 3. Complete with either finishEditing (commit) or cancelEditState (rollback)\r\n *\r\n * This entity is a critical part of the state authoring workflow and works closely\r\n * with HostStateMachine and HostStateEntity.\r\n */\r\nexport abstract class HostEditingStateEntity extends AppObjectEntity {\r\n  static type = \"HostEditingStateEntity\";\r\n\r\n  /** Whether currently in edit mode for a state */\r\n  abstract get isEditing(): boolean;\r\n\r\n  /** Whether editing a newly created state (true) or existing state (false) */\r\n  abstract get isNewState(): boolean;\r\n\r\n  /** The state entity currently being edited, if any */\r\n  abstract get editingState(): HostStateEntity | undefined;\r\n\r\n  /** Whether changes have been made since starting edit mode */\r\n  abstract get somethingHasChanged(): boolean;\r\n\r\n  /** Validation message if the current state is invalid, undefined if valid */\r\n  abstract stateValidationMessage?: string;\r\n\r\n  /**\r\n   * Creates a new state entity and begins editing it\r\n   * @returns The newly created state entity that's being edited\r\n   */\r\n  abstract startNewState(): HostStateEntity | undefined;\r\n\r\n  /**\r\n   * Begins editing an existing state entity\r\n   * @param state The state entity to begin editing\r\n   */\r\n  abstract startEditing(state: HostStateEntity): void;\r\n\r\n  /**\r\n   * Cancels the current edit operation and reverts any changes\r\n   * For new states, removes them from the state machine\r\n   * For existing states, reverts to original values\r\n   */\r\n  abstract cancelEditState(): void;\r\n\r\n  /**\r\n   * Completes the current edit operation, keeping all changes\r\n   * Performs no validation - validation should happen before calling this\r\n   */\r\n  abstract finishEditing(): void;\r\n\r\n  static get(appObjects: AppObjectRepo) {\r\n    return getSingletonComponent<HostEditingStateEntity>(\r\n      HostEditingStateEntity.type,\r\n      appObjects\r\n    );\r\n  }\r\n}\r\n\r\n/**\r\n * Factory function for creating a HostEditingStateEntity instance\r\n * @param appObject The AppObject to associate with this entity\r\n * @returns A new HostEditingStateEntity instance\r\n */\r\nexport function makeHostEditingStateEntity(\r\n  appObject: AppObject\r\n): HostEditingStateEntity {\r\n  return new HostEditingStateEntityImp(appObject);\r\n}\r\n\r\n/**\r\n * Implementation of the HostEditingStateEntity abstract class\r\n * Manages the state editing workflow and tracks changes\r\n */\r\nclass HostEditingStateEntityImp extends HostEditingStateEntity {\r\n  /** Stores the original state data for reverting changes on cancel */\r\n  private originalStateData?: StateDTO;\r\n\r\n  private _editingState?: HostStateEntity;\r\n  get editingState() {\r\n    return this._editingState;\r\n  }\r\n\r\n  get isEditing(): boolean {\r\n    return this._editingState !== undefined;\r\n  }\r\n\r\n  private _isNewState = false;\r\n  get isNewState(): boolean {\r\n    return this._isNewState;\r\n  }\r\n\r\n  private _stateValidationMessage?: string | undefined;\r\n  get stateValidationMessage(): string | undefined {\r\n    return this._stateValidationMessage;\r\n  }\r\n  set stateValidationMessage(val: string | undefined) {\r\n    if (this._stateValidationMessage === val) return;\r\n\r\n    this._stateValidationMessage = val;\r\n    this.notifyOnChange();\r\n  }\r\n\r\n  /**\r\n   * Reference to the HostStateMachine singleton\r\n   * Used for creating and managing states\r\n   */\r\n  private get hostStateMachine() {\r\n    return this.getCachedSingleton<HostStateMachine>(HostStateMachine.type);\r\n  }\r\n\r\n  /**\r\n   * Tracks whether changes have been made to the state being edited\r\n   * Uses a memoized value to efficiently notify observers only when value changes\r\n   */\r\n  private memoizedSomethingHasChanged = new MemoizedBoolean(\r\n    false,\r\n    this.notifyOnChange\r\n  );\r\n  get somethingHasChanged(): boolean {\r\n    return this.memoizedSomethingHasChanged.val;\r\n  }\r\n\r\n  /**\r\n   * Compares the current state with the original state to detect changes\r\n   * Performs deep comparison of all relevant properties\r\n   * @returns true if changes were detected, false otherwise\r\n   */\r\n  private checkForChange = () => {\r\n    if (!this._editingState) return false;\r\n    if (!this.originalStateData) return true;\r\n\r\n    if (this._editingState.name !== this.originalStateData.name) return true;\r\n\r\n    if (this._editingState.expectedResponse !== this.originalStateData.response)\r\n      return true;\r\n\r\n    if (\r\n      this._editingState.assets.length !== this.originalStateData.assets.length\r\n    )\r\n      return true;\r\n    let assetsHaveChanged = false;\r\n    this._editingState.assets.forEach((currentAssetID, i) => {\r\n      const originalAssetId = this.originalStateData!.assets[i];\r\n      if (originalAssetId !== currentAssetID) {\r\n        assetsHaveChanged = true;\r\n      }\r\n    });\r\n\r\n    if (assetsHaveChanged) {\r\n      return true;\r\n    }\r\n\r\n    const currentDataString = JSON.stringify(this._editingState.stateData);\r\n    const originalData = JSON.stringify(this.originalStateData?.data ?? \"\");\r\n    if (currentDataString !== originalData) return true;\r\n\r\n    return false;\r\n  };\r\n\r\n  /**\r\n   * Observer callback for state changes\r\n   * Updates the somethingHasChanged flag when the state being edited changes\r\n   */\r\n  private onStateEntityChange = (): void => {\r\n    this.memoizedSomethingHasChanged.val = this.checkForChange();\r\n  };\r\n\r\n  /**\r\n   * Creates a new state and begins editing it\r\n   * @returns The newly created state entity or undefined if creation failed\r\n   */\r\n  startNewState = (): HostStateEntity | undefined => {\r\n    if (!this.hostStateMachine) return;\r\n\r\n    this.originalStateData = undefined;\r\n    this._isNewState = true;\r\n    this._editingState = this.hostStateMachine.createNewState();\r\n    this._editingState.addChangeObserver(this.onStateEntityChange);\r\n    this.memoizedSomethingHasChanged.val = true;\r\n\r\n    return this._editingState;\r\n  };\r\n\r\n  /**\r\n   * Begins editing an existing state\r\n   * @param state The state entity to edit\r\n   */\r\n  startEditing = (state: HostStateEntity): void => {\r\n    this._editingState = state;\r\n\r\n    this.originalStateData = state.getDTO();\r\n    this._editingState.addChangeObserver(this.onStateEntityChange);\r\n\r\n    this.notifyOnChange();\r\n  };\r\n\r\n  /**\r\n   * Cancels editing and reverts changes\r\n   * For new states, removes them from the state machine\r\n   * For existing states, restores the original values\r\n   */\r\n  cancelEditState = (): void => {\r\n    if (!this._editingState) return;\r\n\r\n    if (this.originalStateData) {\r\n      this._editingState.setDTO(this.originalStateData);\r\n    } else {\r\n      this.hostStateMachine?.deleteState(this._editingState.id);\r\n    }\r\n\r\n    this.resetInternalState();\r\n  };\r\n\r\n  /**\r\n   * Completes editing, keeping all changes\r\n   * Simply cleans up the internal state without reverting changes\r\n   */\r\n  finishEditing = (): void => {\r\n    this.resetInternalState();\r\n  };\r\n\r\n  /**\r\n   * Resets the internal state after editing is complete\r\n   * Cleans up observers and notifies clients of the change\r\n   */\r\n  private resetInternalState = () => {\r\n    if (!this._editingState) return;\r\n\r\n    this._isNewState = false;\r\n    this._editingState.removeChangeObserver(this.onStateEntityChange);\r\n    this._stateValidationMessage = undefined;\r\n    this._editingState = undefined;\r\n    this.memoizedSomethingHasChanged.val = false;\r\n    this.notifyOnChange();\r\n  };\r\n\r\n  constructor(appObject: AppObject) {\r\n    super(appObject, HostEditingStateEntity.type);\r\n    this.appObjects.registerSingleton(this);\r\n  }\r\n}\r\n"]}

package/dist/esm/StateMachine/Entities/HostStateEntity.js

@@ -1,5 +1,9 @@
 import { MemoizedString } from "@vived/core";
 import { AppObjectEntity } from "@vived/core";
+/**
+ * Defines the types of challenge responses that can be expected in a state
+ * These represent different feedback mechanisms available to the user
+ */
 export var ChallengeResponse;
 (function (ChallengeResponse) {
     ChallengeResponse["NONE"] = "NONE";
@@ -7,19 +11,63 @@ export var ChallengeResponse;
     ChallengeResponse["HIT"] = "HIT";
     ChallengeResponse["MULTIHIT"] = "MULTIHIT";
     ChallengeResponse["PROGRESS"] = "PROGRESS";
-    ChallengeResponse["QUALITY"] = "QUALITY";
+    ChallengeResponse["QUALITY"] = "QUALITY"; // Quality-rated response
 })(ChallengeResponse || (ChallengeResponse = {}));
+/**
+ * Defines the loading states for streaming assets in a state
+ */
+export var StreamState;
+(function (StreamState) {
+    StreamState["INIT"] = "INIT";
+    StreamState["LOADING"] = "LOADING";
+    StreamState["READY"] = "READY";
+    StreamState["ERROR"] = "ERROR"; // Error occurred during loading
+})(StreamState || (StreamState = {}));
+/**
+ * HostStateEntity represents a single state within a state machine.
+ *
+ * Each state contains:
+ * - Metadata (name, ID)
+ * - References to assets needed by the state
+ * - Custom state data specific to the app implementation
+ * - Expected response type for challenge/interaction
+ *
+ * States are managed by the HostStateMachine and can be persisted/restored
+ * through the DTO pattern.
+ *
+ * This is a core component of the VIVED platform's state-based application model,
+ * allowing apps to define discrete states with specific content and behaviors.
+ */
 export class HostStateEntity extends AppObjectEntity {
+    /**
+     * Gets an existing HostStateEntity by ID
+     * @param id The unique identifier for the state
+     * @param appObjects The app object repository
+     * @returns The state entity if found, undefined otherwise
+     */
     static get(id, appObjects) {
         const ao = appObjects.get(id);
         return ao?.getComponent(HostStateEntity.type);
     }
 }
 HostStateEntity.type = "HostStateEntity";
+/**
+ * Factory function for creating a HostStateEntity instance
+ * @param appObject The AppObject to associate with this entity
+ * @returns A new HostStateEntity instance
+ */
 export function makeHostStateEntity(appObject) {
     return new HostStateEntityImp(appObject);
 }
+/**
+ * Implementation of the HostStateEntity abstract class
+ * Provides concrete implementation of state properties and methods
+ */
 class HostStateEntityImp extends HostStateEntity {
+    /**
+     * The unique identifier for this state
+     * Derived from the associated AppObject ID
+     */
     get id() {
         return this.appObject.id;
     }
@@ -32,6 +80,11 @@ class HostStateEntityImp extends HostStateEntity {
     get stateData() {
         return this._data;
     }
+    /**
+     * Updates the state data, optionally checking if it actually changed
+     * @param val New state data
+     * @param checkForChange If true, only notifies on actual changes
+     */
     setStateData(val, checkForChange) {
         let notify = true;
         if (checkForChange) {
@@ -77,6 +130,10 @@ class HostStateEntityImp extends HostStateEntity {
         this._expectedResponse = val;
         this.notifyOnChange();
     }
+    /**
+     * Serializes state to a data transfer object
+     * Used for persistence and state management
+     */
     getDTO() {
         return {
             id: this.id,
@@ -87,6 +144,11 @@ class HostStateEntityImp extends HostStateEntity {
             appID: this.appID
         };
     }
+    /**
+     * Applies state data from a DTO
+     * Used when restoring state or rolling back changes
+     * @param dto The data transfer object to apply
+     */
     setDTO(dto) {
         if (dto.id !== this.id) {
             this.warn("DTO id does not match my ID. Skipping");
@@ -109,12 +171,39 @@ class HostStateEntityImp extends HostStateEntity {
     set appID(val) {
         this.memoisedAppID.val = val;
     }
+    get streamState() {
+        return this.memoizedStreamState.val;
+    }
+    set streamState(val) {
+        this.memoizedStreamState.val = val;
+    }
     constructor(appObject) {
         super(appObject, HostStateEntity.type);
+        /**
+         * Memoized name property with change notification
+         * Uses MemoizedString to efficiently track changes
+         */
         this.memoizedName = new MemoizedString("", this.notifyOnChange);
+        /**
+         * Custom state data object
+         * This is app-specific data that defines the state behavior
+         */
         this._data = {};
+        /**
+         * Array of asset IDs required by this state
+         * Assets are loaded before the state becomes active
+         */
         this._assets = [];
+        /**
+         * ID of the app this state belongs to
+         * States can only be used with their associated app
+         */
         this.memoisedAppID = new MemoizedString("", this.notifyOnChange);
+        /**
+         * Current loading state for streaming assets
+         * Used to track progress when loading assets for this state
+         */
+        this.memoizedStreamState = new MemoizedString(StreamState.INIT, this.notifyOnChange);
     }
 }
 //# sourceMappingURL=HostStateEntity.js.map

package/dist/esm/StateMachine/Entities/HostStateEntity.js.map

@@ -1 +1 @@
-{"version":3,"file":"HostStateEntity.js","sourceRoot":"","sources":["../../../../src/StateMachine/Entities/HostStateEntity.ts"],"names":[],"mappings":"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","sourcesContent":["import { MemoizedString } from \"@vived/core\";\r\nimport { AppObject, AppObjectEntity, AppObjectRepo } from \"@vived/core\";\r\n\r\nexport enum ChallengeResponse {\r\n  NONE = \"NONE\",\r\n  SCORE = \"SCORE\",\r\n  HIT = \"HIT\",\r\n  MULTIHIT = \"MULTIHIT\",\r\n  PROGRESS = \"PROGRESS\",\r\n  QUALITY = \"QUALITY\"\r\n}\r\n\r\nexport interface StateDTO {\r\n  id: string;\r\n  name: string;\r\n  data: object;\r\n  assets: string[];\r\n  response: string | undefined;\r\n  appID: string;\r\n}\r\n\r\nexport abstract class HostStateEntity extends AppObjectEntity {\r\n  static type = \"HostStateEntity\";\r\n\r\n  abstract get id(): string;\r\n\r\n  abstract name: string;\r\n  abstract assets: string[];\r\n  abstract expectedResponse: ChallengeResponse | undefined;\r\n  abstract appID: string;\r\n  abstract getDTO(): StateDTO;\r\n  abstract setDTO(dto: StateDTO): void;\r\n\r\n  abstract get stateData(): object;\r\n  abstract setStateData(val: object, checkForChange?: boolean): void;\r\n\r\n  static get(id: string, appObjects: AppObjectRepo) {\r\n    const ao = appObjects.get(id);\r\n    return ao?.getComponent<HostStateEntity>(HostStateEntity.type);\r\n  }\r\n}\r\n\r\nexport function makeHostStateEntity(appObject: AppObject): HostStateEntity {\r\n  return new HostStateEntityImp(appObject);\r\n}\r\n\r\nclass HostStateEntityImp extends HostStateEntity {\r\n  get id(): string {\r\n    return this.appObject.id;\r\n  }\r\n\r\n  private memoizedName = new MemoizedString(\"\", this.notifyOnChange);\r\n  get name(): string {\r\n    return this.memoizedName.val;\r\n  }\r\n  set name(val: string) {\r\n    this.memoizedName.val = val;\r\n  }\r\n\r\n  private _data = {};\r\n  get stateData(): object {\r\n    return this._data;\r\n  }\r\n\r\n  setStateData(val: object, checkForChange?: boolean): void {\r\n    let notify = true;\r\n    if (checkForChange) {\r\n      const currentData = JSON.stringify(this._data);\r\n      const newData = JSON.stringify(val);\r\n\r\n      if (currentData === newData) {\r\n        notify = false;\r\n      }\r\n    }\r\n\r\n    this._data = val;\r\n    if (notify) {\r\n      this.notifyOnChange();\r\n    }\r\n  }\r\n\r\n  private _assets: string[] = [];\r\n  get assets() {\r\n    return [...this._assets];\r\n  }\r\n  set assets(val: string[]) {\r\n    if (val.length !== this._assets.length) {\r\n      this._assets = val;\r\n      this.notifyOnChange();\r\n      return;\r\n    }\r\n\r\n    let somethingHasChanged = false;\r\n    val.forEach((newAsset, i) => {\r\n      const existingAsset = this._assets[i];\r\n      if (existingAsset !== newAsset) {\r\n        somethingHasChanged = true;\r\n      }\r\n    });\r\n\r\n    if (!somethingHasChanged) {\r\n      return;\r\n    }\r\n\r\n    this._assets = val;\r\n    this.notifyOnChange();\r\n  }\r\n\r\n  private _expectedResponse: ChallengeResponse | undefined;\r\n  get expectedResponse() {\r\n    return this._expectedResponse;\r\n  }\r\n  set expectedResponse(val: ChallengeResponse | undefined) {\r\n    if (val === this._expectedResponse) return;\r\n\r\n    this._expectedResponse = val;\r\n    this.notifyOnChange();\r\n  }\r\n\r\n  getDTO(): StateDTO {\r\n    return {\r\n      id: this.id,\r\n      assets: [...this._assets],\r\n      data: this._data,\r\n      name: this.memoizedName.val,\r\n      response: this._expectedResponse,\r\n      appID: this.appID\r\n    };\r\n  }\r\n\r\n  setDTO(dto: StateDTO): void {\r\n    if (dto.id !== this.id) {\r\n      this.warn(\"DTO id does not match my ID. Skipping\");\r\n      return;\r\n    }\r\n\r\n    this.setStateData(dto.data, true);\r\n    this.assets = [...dto.assets];\r\n    this.memoizedName.val = dto.name;\r\n    this.memoisedAppID.val = dto.appID;\r\n\r\n    if ((Object as any).values(ChallengeResponse).includes(dto.response)) {\r\n      this.expectedResponse = dto.response as ChallengeResponse;\r\n    } else {\r\n      this.expectedResponse = undefined;\r\n    }\r\n  }\r\n\r\n  private memoisedAppID = new MemoizedString(\"\", this.notifyOnChange);\r\n  get appID(): string {\r\n    return this.memoisedAppID.val;\r\n  }\r\n  set appID(val: string) {\r\n    this.memoisedAppID.val = val;\r\n  }\r\n\r\n  constructor(appObject: AppObject) {\r\n    super(appObject, HostStateEntity.type);\r\n  }\r\n}\r\n"]}
+{"version":3,"file":"HostStateEntity.js","sourceRoot":"","sources":["../../../../src/StateMachine/Entities/HostStateEntity.ts"],"names":[],"mappings":"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","sourcesContent":["import { MemoizedString } from \"@vived/core\";\r\nimport { AppObject, AppObjectEntity, AppObjectRepo } from \"@vived/core\";\r\n\r\n/**\r\n * Defines the types of challenge responses that can be expected in a state\r\n * These represent different feedback mechanisms available to the user\r\n */\r\nexport enum ChallengeResponse {\r\n  NONE = \"NONE\", // No specific response expected\r\n  SCORE = \"SCORE\", // Numeric score-based response\r\n  HIT = \"HIT\", // Binary hit/miss response\r\n  MULTIHIT = \"MULTIHIT\", // Multiple hit targets response\r\n  PROGRESS = \"PROGRESS\", // Continuous progress response\r\n  QUALITY = \"QUALITY\" // Quality-rated response\r\n}\r\n\r\n/**\r\n * Defines the loading states for streaming assets in a state\r\n */\r\nexport enum StreamState {\r\n  INIT = \"INIT\", // Initial state before loading\r\n  LOADING = \"LOADING\", // Assets are currently loading\r\n  READY = \"READY\", // Assets have loaded successfully\r\n  ERROR = \"ERROR\" // Error occurred during loading\r\n}\r\n\r\n/**\r\n * Data Transfer Object for serializing/deserializing state data\r\n * Used for persistence, state management, and undo/redo operations\r\n */\r\nexport interface StateDTO {\r\n  id: string; // Unique identifier for the state\r\n  name: string; // Display name for the state\r\n  data: object; // Custom state data - structure depends on app implementation\r\n  assets: string[]; // Array of asset IDs referenced by this state\r\n  response: string | undefined; // Expected challenge response type\r\n  appID: string; // ID of the app this state belongs to\r\n}\r\n\r\n/**\r\n * HostStateEntity represents a single state within a state machine.\r\n *\r\n * Each state contains:\r\n * - Metadata (name, ID)\r\n * - References to assets needed by the state\r\n * - Custom state data specific to the app implementation\r\n * - Expected response type for challenge/interaction\r\n *\r\n * States are managed by the HostStateMachine and can be persisted/restored\r\n * through the DTO pattern.\r\n *\r\n * This is a core component of the VIVED platform's state-based application model,\r\n * allowing apps to define discrete states with specific content and behaviors.\r\n */\r\nexport abstract class HostStateEntity extends AppObjectEntity {\r\n  static type = \"HostStateEntity\";\r\n\r\n  /** Unique identifier for this state */\r\n  abstract get id(): string;\r\n\r\n  /** Human-readable name of the state */\r\n  abstract name: string;\r\n\r\n  /** List of asset IDs required by this state */\r\n  abstract assets: string[];\r\n\r\n  /** Type of response expected from user interactions in this state */\r\n  abstract expectedResponse: ChallengeResponse | undefined;\r\n\r\n  /** ID of the app this state belongs to */\r\n  abstract appID: string;\r\n\r\n  /** Current loading state for streaming assets */\r\n  abstract streamState: StreamState;\r\n\r\n  /**\r\n   * Serializes the state to a plain object for persistence\r\n   * @returns StateDTO containing all state data\r\n   */\r\n  abstract getDTO(): StateDTO;\r\n\r\n  /**\r\n   * Deserializes from a DTO and updates this state's properties\r\n   * @param dto The state data transfer object to apply\r\n   */\r\n  abstract setDTO(dto: StateDTO): void;\r\n\r\n  /**\r\n   * Gets the custom state data object\r\n   * Structure is specific to the app implementation\r\n   */\r\n  abstract get stateData(): object;\r\n\r\n  /**\r\n   * Updates the custom state data object\r\n   * @param val New state data object\r\n   * @param checkForChange If true, only notifies observers when actual changes occur\r\n   */\r\n  abstract setStateData(val: object, checkForChange?: boolean): void;\r\n\r\n  /**\r\n   * Gets an existing HostStateEntity by ID\r\n   * @param id The unique identifier for the state\r\n   * @param appObjects The app object repository\r\n   * @returns The state entity if found, undefined otherwise\r\n   */\r\n  static get(id: string, appObjects: AppObjectRepo) {\r\n    const ao = appObjects.get(id);\r\n    return ao?.getComponent<HostStateEntity>(HostStateEntity.type);\r\n  }\r\n}\r\n\r\n/**\r\n * Factory function for creating a HostStateEntity instance\r\n * @param appObject The AppObject to associate with this entity\r\n * @returns A new HostStateEntity instance\r\n */\r\nexport function makeHostStateEntity(appObject: AppObject): HostStateEntity {\r\n  return new HostStateEntityImp(appObject);\r\n}\r\n\r\n/**\r\n * Implementation of the HostStateEntity abstract class\r\n * Provides concrete implementation of state properties and methods\r\n */\r\nclass HostStateEntityImp extends HostStateEntity {\r\n  /**\r\n   * The unique identifier for this state\r\n   * Derived from the associated AppObject ID\r\n   */\r\n  get id(): string {\r\n    return this.appObject.id;\r\n  }\r\n\r\n  /**\r\n   * Memoized name property with change notification\r\n   * Uses MemoizedString to efficiently track changes\r\n   */\r\n  private memoizedName = new MemoizedString(\"\", this.notifyOnChange);\r\n  get name(): string {\r\n    return this.memoizedName.val;\r\n  }\r\n  set name(val: string) {\r\n    this.memoizedName.val = val;\r\n  }\r\n\r\n  /**\r\n   * Custom state data object\r\n   * This is app-specific data that defines the state behavior\r\n   */\r\n  private _data = {};\r\n  get stateData(): object {\r\n    return this._data;\r\n  }\r\n\r\n  /**\r\n   * Updates the state data, optionally checking if it actually changed\r\n   * @param val New state data\r\n   * @param checkForChange If true, only notifies on actual changes\r\n   */\r\n  setStateData(val: object, checkForChange?: boolean): void {\r\n    let notify = true;\r\n    if (checkForChange) {\r\n      const currentData = JSON.stringify(this._data);\r\n      const newData = JSON.stringify(val);\r\n\r\n      if (currentData === newData) {\r\n        notify = false;\r\n      }\r\n    }\r\n\r\n    this._data = val;\r\n    if (notify) {\r\n      this.notifyOnChange();\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Array of asset IDs required by this state\r\n   * Assets are loaded before the state becomes active\r\n   */\r\n  private _assets: string[] = [];\r\n  get assets() {\r\n    return [...this._assets];\r\n  }\r\n  set assets(val: string[]) {\r\n    if (val.length !== this._assets.length) {\r\n      this._assets = val;\r\n      this.notifyOnChange();\r\n      return;\r\n    }\r\n\r\n    let somethingHasChanged = false;\r\n    val.forEach((newAsset, i) => {\r\n      const existingAsset = this._assets[i];\r\n      if (existingAsset !== newAsset) {\r\n        somethingHasChanged = true;\r\n      }\r\n    });\r\n\r\n    if (!somethingHasChanged) {\r\n      return;\r\n    }\r\n\r\n    this._assets = val;\r\n    this.notifyOnChange();\r\n  }\r\n\r\n  /**\r\n   * Type of response expected from user interactions\r\n   * Determines how challenge results are processed\r\n   */\r\n  private _expectedResponse: ChallengeResponse | undefined;\r\n  get expectedResponse() {\r\n    return this._expectedResponse;\r\n  }\r\n  set expectedResponse(val: ChallengeResponse | undefined) {\r\n    if (val === this._expectedResponse) return;\r\n\r\n    this._expectedResponse = val;\r\n    this.notifyOnChange();\r\n  }\r\n\r\n  /**\r\n   * Serializes state to a data transfer object\r\n   * Used for persistence and state management\r\n   */\r\n  getDTO(): StateDTO {\r\n    return {\r\n      id: this.id,\r\n      assets: [...this._assets],\r\n      data: this._data,\r\n      name: this.memoizedName.val,\r\n      response: this._expectedResponse,\r\n      appID: this.appID\r\n    };\r\n  }\r\n\r\n  /**\r\n   * Applies state data from a DTO\r\n   * Used when restoring state or rolling back changes\r\n   * @param dto The data transfer object to apply\r\n   */\r\n  setDTO(dto: StateDTO): void {\r\n    if (dto.id !== this.id) {\r\n      this.warn(\"DTO id does not match my ID. Skipping\");\r\n      return;\r\n    }\r\n\r\n    this.setStateData(dto.data, true);\r\n    this.assets = [...dto.assets];\r\n    this.memoizedName.val = dto.name;\r\n    this.memoisedAppID.val = dto.appID;\r\n\r\n    if ((Object as any).values(ChallengeResponse).includes(dto.response)) {\r\n      this.expectedResponse = dto.response as ChallengeResponse;\r\n    } else {\r\n      this.expectedResponse = undefined;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * ID of the app this state belongs to\r\n   * States can only be used with their associated app\r\n   */\r\n  private memoisedAppID = new MemoizedString(\"\", this.notifyOnChange);\r\n  get appID(): string {\r\n    return this.memoisedAppID.val;\r\n  }\r\n  set appID(val: string) {\r\n    this.memoisedAppID.val = val;\r\n  }\r\n\r\n  /**\r\n   * Current loading state for streaming assets\r\n   * Used to track progress when loading assets for this state\r\n   */\r\n  private memoizedStreamState = new MemoizedString(\r\n    StreamState.INIT,\r\n    this.notifyOnChange\r\n  );\r\n  get streamState(): StreamState {\r\n    return this.memoizedStreamState.val as StreamState;\r\n  }\r\n  set streamState(val: StreamState) {\r\n    this.memoizedStreamState.val = val;\r\n  }\r\n\r\n  constructor(appObject: AppObject) {\r\n    super(appObject, HostStateEntity.type);\r\n  }\r\n}\r\n"]}

package/dist/esm/StateMachine/Entities/HostStateMachine.js

@@ -1,25 +1,68 @@
 import { generateUniqueID, MemoizedBoolean } from "@vived/core";
 import { getSingletonComponent, AppObjectEntity } from "@vived/core";
 import { makeHostStateEntity } from "./HostStateEntity";
+/**
+ * HostStateMachine manages a collection of states and controls state transitions.
+ *
+ * This singleton component serves as the central controller for the VIVED platform's
+ * state-based application model. It maintains an ordered collection of states,
+ * tracks the currently active state, and provides methods for state transitions,
+ * creation, deletion, and reordering.
+ *
+ * The state machine can be used in both runtime and authoring modes:
+ * - In runtime: For navigating between predefined states in an application
+ * - In authoring: For creating and organizing states through a content editor
+ *
+ * This entity works closely with HostStateEntity (individual states) and
+ * HostEditingStateEntity (for state authoring).
+ */
 export class HostStateMachine extends AppObjectEntity {
+    /**
+     * Gets the singleton instance of HostStateMachine
+     * @param appObjects The app object repository
+     * @returns The HostStateMachine instance
+     */
     static get(appObjects) {
         return getSingletonComponent(HostStateMachine.type, appObjects);
     }
 }
 HostStateMachine.type = "HostStateMachine";
+/**
+ * Factory function for creating a HostStateMachine instance
+ * @param appObject The AppObject to associate with this entity
+ * @returns A new HostStateMachine instance
+ */
 export function makeHostStateMachine(appObject) {
     return new HostStateMachineImp(appObject);
 }
+/**
+ * Implementation of the HostStateMachine abstract class
+ * Provides concrete implementation of state machine functionality
+ */
 class HostStateMachineImp extends HostStateMachine {
+    /**
+     * List of all state IDs in order
+     * @returns Array of state IDs
+     */
     get states() {
         return this._states.map((state) => state.id);
     }
+    /**
+     * Total number of states in the machine
+     * @returns Number of states
+     */
     get stateCount() {
         return this._states.length;
     }
     get activeState() {
         return this._activeState;
     }
+    /**
+     * ID of the state preceding the active state
+     * Returns undefined if:
+     * - No active state
+     * - Active state is the first state
+     */
     get previousState() {
         if (!this._activeState)
             return undefined;
@@ -28,6 +71,12 @@ class HostStateMachineImp extends HostStateMachine {
             return undefined;
         return this._states[currentIndex - 1].id;
     }
+    /**
+     * ID of the state following the active state
+     * Returns undefined if:
+     * - No active state
+     * - Active state is the last state
+     */
     get nextState() {
         if (!this._activeState)
             return undefined;
@@ -63,6 +112,11 @@ class HostStateMachineImp extends HostStateMachine {
     set lastAssets(lastAssets) {
         this._lastAssets = lastAssets;
     }
+    /**
+     * Helper method to find a state by ID
+     * @param id ID to search for
+     * @returns The state entity or undefined if not found
+     */
     findStateByID(id) {
         for (const state of this._states) {
             if (state.id === id) {
@@ -73,10 +127,25 @@ class HostStateMachineImp extends HostStateMachine {
     }
     constructor(appObject) {
         super(appObject, HostStateMachine.type);
+        /** Internal storage for state entities */
         this._states = [];
+        /** Duration for transitions between states (in seconds) */
         this.transitionDuration = 1;
+        /**
+         * Whether the state machine is in authoring mode
+         * In authoring mode, additional editing features are enabled
+         */
         this.memoizedIsAuthoring = new MemoizedBoolean(false, this.notifyOnChange);
+        /**
+         * Tracks assets used in previous state for preloading optimization
+         * Helps optimize asset loading between state transitions
+         */
         this._lastAssets = [];
+        /**
+         * Checks if a state with the given ID exists
+         * @param id ID to check
+         * @returns true if state exists, false otherwise
+         */
         this.hasState = (id) => {
             const state = this.findStateByID(id);
             if (state) {
@@ -86,6 +155,10 @@ class HostStateMachineImp extends HostStateMachine {
                 return false;
             }
         };
+        /**
+         * Sets the active state by its ID
+         * @param id ID of the state to activate
+         */
         this.setActiveStateByID = (id) => {
             const state = this.findStateByID(id);
             if (!state)
@@ -95,35 +168,66 @@ class HostStateMachineImp extends HostStateMachine {
             this._activeState = state.id;
             this.notifyOnChange();
         };
+        /**
+         * Sets the active state by its index in the states array
+         * @param index Zero-based index of the state to activate
+         */
         this.setActiveStateByIndex = (index) => {
             if (index < 0 || index >= this._states.length)
                 return;
             const state = this._states[index];
             this.setActiveStateByID(state.id);
         };
+        /**
+         * Clears the active state (no state will be active)
+         */
         this.clearActiveState = () => {
             if (!this.activeState)
                 return;
             this._activeState = undefined;
             this.notifyOnChange();
         };
+        /**
+         * Replaces all states with a new collection
+         * @param states Array of state entities to use
+         */
         this.setStates = (states) => {
             this._states = states;
             this.notifyOnChange();
         };
+        /**
+         * Factory function for creating state entities
+         * Creates a new AppObject with the given ID and wraps it in a HostStateEntity
+         * @param id ID for the new state
+         * @returns A new HostStateEntity instance
+         */
         this.stateFactory = (id) => {
             const ao = this.appObjects.getOrCreate(id);
             return makeHostStateEntity(ao);
         };
+        /**
+         * Creates a new empty state and adds it to the end of the states array
+         * @returns The newly created state entity
+         */
         this.createNewState = () => {
             const newState = this.stateFactory(generateUniqueID());
             this._states.push(newState);
             this.notifyOnChange();
             return newState;
         };
+        /**
+         * Gets a state entity by its ID
+         * @param id ID of the state to retrieve
+         * @returns The state entity or undefined if not found
+         */
         this.getStateByID = (id) => {
             return this.findStateByID(id);
         };
+        /**
+         * Deletes a state from the machine by its ID
+         * Also disposes the associated AppObject
+         * @param id ID of the state to delete
+         */
         this.deleteState = (id) => {
             const index = this.getStateIndex(id);
             if (index === undefined) {
@@ -134,6 +238,10 @@ class HostStateMachineImp extends HostStateMachine {
             this._states.splice(index, 1);
             this.notifyOnChange();
         };
+        /**
+         * Deletes all states from the machine
+         * Also disposes all associated AppObjects
+         */
         this.deleteAllStates = () => {
             if (this._states.length === 0)
                 return;
@@ -145,6 +253,11 @@ class HostStateMachineImp extends HostStateMachine {
             this.clearActiveState();
             this.notifyOnChange();
         };
+        /**
+         * Gets the index of a state in the states array
+         * @param id ID of the state
+         * @returns Zero-based index or undefined if not found
+         */
         this.getStateIndex = (id) => {
             let index = -1;
             this._states.forEach((state, i) => {
@@ -159,16 +272,30 @@ class HostStateMachineImp extends HostStateMachine {
                 return undefined;
             }
         };
+        /**
+         * Activates the state before the current active state
+         * Does nothing if there is no previous state
+         */
         this.setPreviousStateActive = () => {
             if (!this.previousState)
                 return;
             this.setActiveStateByID(this.previousState);
         };
+        /**
+         * Activates the state after the current active state
+         * Does nothing if there is no next state
+         */
         this.setNextStateActive = () => {
             if (!this.nextState)
                 return;
             this.setActiveStateByID(this.nextState);
         };
+        /**
+         * Moves a state to a different position in the states array
+         * Used for reordering states in the state machine
+         * @param stateID ID of the state to move
+         * @param index Destination index
+         */
         this.setStateIndex = (stateID, index) => {
             // Check if the state exists
             const state = this.getStateByID(stateID);