@vived/host 4.10.0 → 4.11.0

package/dist/cjs/Assets/Controllers/toggleShowArchivedAssets.js

@@ -1,7 +1,35 @@
 "use strict";
+/**
+ * toggleShowArchivedAssets.ts
+ *
+ * This controller function toggles the visibility of archived assets in the asset list.
+ * It provides a simple interface for users to show or hide archived assets from
+ * their asset management workspace.
+ *
+ * Key Concepts:
+ * - Toggles the display state of archived assets in asset lists
+ * - Directly modifies the AppAssetsEntity's showArchived property
+ * - Provides error handling for missing components
+ * - Triggers immediate UI updates through entity change notifications
+ *
+ * Usage Patterns:
+ * - Called from UI components with toggle buttons or checkboxes
+ * - Used in asset management interfaces for filtering options
+ * - Integrated with asset list displays and filter controls
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toggleShowArchivedAssets = toggleShowArchivedAssets;
 const AppAssetsEntity_1 = require("../Entities/AppAssetsEntity");
+/**
+ * Toggles the visibility of archived assets in the asset management interface.
+ *
+ * This function provides a controller-level interface for toggling archived asset visibility.
+ * It flips the current state of the showArchived property, which immediately affects
+ * what assets are displayed in asset lists and management interfaces.
+ *
+ * @param appObjects - Repository for accessing the AppAssetsEntity that controls visibility
+ * @returns void - The function operates synchronously and triggers immediate UI updates
+ */
 function toggleShowArchivedAssets(appObjects) {
     const appAssets = AppAssetsEntity_1.AppAssetsEntity.get(appObjects);
     if (appAssets) {

package/dist/cjs/Assets/Controllers/toggleShowArchivedAssets.js.map

@@ -1 +1 @@
-{"version":3,"file":"toggleShowArchivedAssets.js","sourceRoot":"","sources":["../../../../src/Assets/Controllers/toggleShowArchivedAssets.ts"],"names":[],"mappings":";;AAGA,4DAWC;AAbD,iEAA8D;AAE9D,SAAgB,wBAAwB,CAAC,UAAyB;IAChE,MAAM,SAAS,GAAG,iCAAe,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAElD,IAAI,SAAS,EAAE,CAAC;QACd,SAAS,CAAC,YAAY,GAAG,CAAC,SAAS,CAAC,YAAY,CAAC;IACnD,CAAC;SAAM,CAAC;QACN,UAAU,CAAC,aAAa,CACtB,0BAA0B,EAC1B,gCAAgC,CACjC,CAAC;IACJ,CAAC;AACH,CAAC","sourcesContent":["import { AppObjectRepo } from \"@vived/core\";\r\nimport { AppAssetsEntity } from \"../Entities/AppAssetsEntity\";\r\n\r\nexport function toggleShowArchivedAssets(appObjects: AppObjectRepo) {\r\n  const appAssets = AppAssetsEntity.get(appObjects);\r\n\r\n  if (appAssets) {\r\n    appAssets.showArchived = !appAssets.showArchived;\r\n  } else {\r\n    appObjects.submitWarning(\r\n      \"toggleShowArchivedAssets\",\r\n      \"Unable to find AppAssetsEntity\"\r\n    );\r\n  }\r\n}\r\n"]}
+{"version":3,"file":"toggleShowArchivedAssets.js","sourceRoot":"","sources":["../../../../src/Assets/Controllers/toggleShowArchivedAssets.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;AAeH,4DAWC;AAvBD,iEAA8D;AAE9D;;;;;;;;;GASG;AACH,SAAgB,wBAAwB,CAAC,UAAyB;IAChE,MAAM,SAAS,GAAG,iCAAe,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAElD,IAAI,SAAS,EAAE,CAAC;QACd,SAAS,CAAC,YAAY,GAAG,CAAC,SAAS,CAAC,YAAY,CAAC;IACnD,CAAC;SAAM,CAAC;QACN,UAAU,CAAC,aAAa,CACtB,0BAA0B,EAC1B,gCAAgC,CACjC,CAAC;IACJ,CAAC;AACH,CAAC","sourcesContent":["/**\r\n * toggleShowArchivedAssets.ts\r\n *\r\n * This controller function toggles the visibility of archived assets in the asset list.\r\n * It provides a simple interface for users to show or hide archived assets from\r\n * their asset management workspace.\r\n *\r\n * Key Concepts:\r\n * - Toggles the display state of archived assets in asset lists\r\n * - Directly modifies the AppAssetsEntity's showArchived property\r\n * - Provides error handling for missing components\r\n * - Triggers immediate UI updates through entity change notifications\r\n *\r\n * Usage Patterns:\r\n * - Called from UI components with toggle buttons or checkboxes\r\n * - Used in asset management interfaces for filtering options\r\n * - Integrated with asset list displays and filter controls\r\n */\r\n\r\nimport { AppObjectRepo } from \"@vived/core\";\r\nimport { AppAssetsEntity } from \"../Entities/AppAssetsEntity\";\r\n\r\n/**\r\n * Toggles the visibility of archived assets in the asset management interface.\r\n *\r\n * This function provides a controller-level interface for toggling archived asset visibility.\r\n * It flips the current state of the showArchived property, which immediately affects\r\n * what assets are displayed in asset lists and management interfaces.\r\n *\r\n * @param appObjects - Repository for accessing the AppAssetsEntity that controls visibility\r\n * @returns void - The function operates synchronously and triggers immediate UI updates\r\n */\r\nexport function toggleShowArchivedAssets(appObjects: AppObjectRepo) {\r\n  const appAssets = AppAssetsEntity.get(appObjects);\r\n\r\n  if (appAssets) {\r\n    appAssets.showArchived = !appAssets.showArchived;\r\n  } else {\r\n    appObjects.submitWarning(\r\n      \"toggleShowArchivedAssets\",\r\n      \"Unable to find AppAssetsEntity\"\r\n    );\r\n  }\r\n}\r\n"]}

package/dist/cjs/Assets/Controllers/updateAppAssetMeta.js

@@ -1,7 +1,37 @@
 "use strict";
+/**
+ * updateAppAssetMeta.ts
+ *
+ * This controller function handles updating asset metadata (name, description, etc.)
+ * for existing assets. It provides a streamlined interface for modifying asset
+ * information without affecting the actual asset files.
+ *
+ * Key Concepts:
+ * - Updates asset metadata without modifying the actual file content
+ * - Uses UpdateAppAssetMetaUC to handle validation and persistence
+ * - Provides error handling for missing components
+ * - Supports partial updates of asset information
+ *
+ * Usage Patterns:
+ * - Called from asset editing forms and dialogs
+ * - Used in asset management workflows for information updates
+ * - Integrated with asset detail views and editing interfaces
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.updateAppAssetMeta = updateAppAssetMeta;
 const UpdateAppAssetMetaUC_1 = require("../UCs/UpdateAppAssetMetaUC");
+/**
+ * Updates the metadata of an existing asset.
+ *
+ * This function provides a controller-level interface for updating asset metadata
+ * such as name, description, and other properties. It handles validation and
+ * persistence of the changes through the underlying use case.
+ *
+ * @param data - Data transfer object containing the metadata fields to update
+ * @param assetID - The unique identifier of the asset to update
+ * @param appObjects - Repository for accessing asset-related app objects and components
+ * @returns void - The function operates synchronously and triggers immediate updates
+ */
 function updateAppAssetMeta(data, assetID, appObjects) {
     const uc = UpdateAppAssetMetaUC_1.UpdateAppAssetMetaUC.get(assetID, appObjects);
     if (!uc) {

package/dist/cjs/Assets/Controllers/updateAppAssetMeta.js.map

@@ -1 +1 @@
-{"version":3,"file":"updateAppAssetMeta.js","sourceRoot":"","sources":["../../../../src/Assets/Controllers/updateAppAssetMeta.ts"],"names":[],"mappings":";;AAMA,gDAeC;AApBD,sEAGqC;AAErC,SAAgB,kBAAkB,CAChC,IAA2B,EAC3B,OAAe,EACf,UAAyB;IAEzB,MAAM,EAAE,GAAG,2CAAoB,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACzD,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,UAAU,CAAC,aAAa,CACtB,oBAAoB,EACpB,kCAAkC,CACnC,CAAC;QACF,OAAO;IACT,CAAC;IAED,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC","sourcesContent":["import { AppObjectRepo } from \"@vived/core\";\r\nimport {\r\n  UpdateAppAssetMetaUC,\r\n  UpdateAppAssetMetaDTO\r\n} from \"../UCs/UpdateAppAssetMetaUC\";\r\n\r\nexport function updateAppAssetMeta(\r\n  data: UpdateAppAssetMetaDTO,\r\n  assetID: string,\r\n  appObjects: AppObjectRepo\r\n) {\r\n  const uc = UpdateAppAssetMetaUC.get(assetID, appObjects);\r\n  if (!uc) {\r\n    appObjects.submitWarning(\r\n      \"updateAppAssetMeta\",\r\n      \"Unable to find UpdateAssetMetaUC\"\r\n    );\r\n    return;\r\n  }\r\n\r\n  uc.updateMeta(data);\r\n}\r\n"]}
+{"version":3,"file":"updateAppAssetMeta.js","sourceRoot":"","sources":["../../../../src/Assets/Controllers/updateAppAssetMeta.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;AAoBH,gDAeC;AAhCD,sEAGqC;AAErC;;;;;;;;;;;GAWG;AACH,SAAgB,kBAAkB,CAChC,IAA2B,EAC3B,OAAe,EACf,UAAyB;IAEzB,MAAM,EAAE,GAAG,2CAAoB,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACzD,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,UAAU,CAAC,aAAa,CACtB,oBAAoB,EACpB,kCAAkC,CACnC,CAAC;QACF,OAAO;IACT,CAAC;IAED,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC","sourcesContent":["/**\r\n * updateAppAssetMeta.ts\r\n *\r\n * This controller function handles updating asset metadata (name, description, etc.)\r\n * for existing assets. It provides a streamlined interface for modifying asset\r\n * information without affecting the actual asset files.\r\n *\r\n * Key Concepts:\r\n * - Updates asset metadata without modifying the actual file content\r\n * - Uses UpdateAppAssetMetaUC to handle validation and persistence\r\n * - Provides error handling for missing components\r\n * - Supports partial updates of asset information\r\n *\r\n * Usage Patterns:\r\n * - Called from asset editing forms and dialogs\r\n * - Used in asset management workflows for information updates\r\n * - Integrated with asset detail views and editing interfaces\r\n */\r\n\r\nimport { AppObjectRepo } from \"@vived/core\";\r\nimport {\r\n  UpdateAppAssetMetaUC,\r\n  UpdateAppAssetMetaDTO\r\n} from \"../UCs/UpdateAppAssetMetaUC\";\r\n\r\n/**\r\n * Updates the metadata of an existing asset.\r\n *\r\n * This function provides a controller-level interface for updating asset metadata\r\n * such as name, description, and other properties. It handles validation and\r\n * persistence of the changes through the underlying use case.\r\n *\r\n * @param data - Data transfer object containing the metadata fields to update\r\n * @param assetID - The unique identifier of the asset to update\r\n * @param appObjects - Repository for accessing asset-related app objects and components\r\n * @returns void - The function operates synchronously and triggers immediate updates\r\n */\r\nexport function updateAppAssetMeta(\r\n  data: UpdateAppAssetMetaDTO,\r\n  assetID: string,\r\n  appObjects: AppObjectRepo\r\n) {\r\n  const uc = UpdateAppAssetMetaUC.get(assetID, appObjects);\r\n  if (!uc) {\r\n    appObjects.submitWarning(\r\n      \"updateAppAssetMeta\",\r\n      \"Unable to find UpdateAssetMetaUC\"\r\n    );\r\n    return;\r\n  }\r\n\r\n  uc.updateMeta(data);\r\n}\r\n"]}

package/dist/cjs/Assets/Controllers/updateAssetFile.js

@@ -1,7 +1,37 @@
 "use strict";
+/**
+ * updateAssetFile.ts
+ *
+ * This controller function handles updating the actual file content of existing assets.
+ * It provides a streamlined interface for replacing asset files while preserving
+ * the asset's metadata and relationships.
+ *
+ * Key Concepts:
+ * - Updates the actual file content of existing assets
+ * - Preserves asset metadata and relationships during file replacement
+ * - Uses UpdateAssetFileUC to handle file upload and persistence
+ * - Provides error handling for missing components
+ *
+ * Usage Patterns:
+ * - Called from file upload interfaces when users replace asset files
+ * - Used in asset management workflows for content updates
+ * - Integrated with drag-and-drop file replacement interfaces
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.updateAssetFile = updateAssetFile;
 const UpdateAssetFileUC_1 = require("../UCs/UpdateAssetFileUC");
+/**
+ * Updates the file content of an existing asset.
+ *
+ * This function provides a controller-level interface for replacing the file
+ * associated with an existing asset. It handles the upload and storage of the
+ * new file while preserving all asset metadata and relationships.
+ *
+ * @param file - The new file object to replace the existing asset file
+ * @param assetID - The unique identifier of the asset whose file should be updated
+ * @param appObjects - Repository for accessing asset-related app objects and components
+ * @returns void - The function initiates the file update process asynchronously
+ */
 function updateAssetFile(file, assetID, appObjects) {
     const uc = UpdateAssetFileUC_1.UpdateAssetFileUC.get(assetID, appObjects);
     if (!uc) {

package/dist/cjs/Assets/Controllers/updateAssetFile.js.map

@@ -1 +1 @@
-{"version":3,"file":"updateAssetFile.js","sourceRoot":"","sources":["../../../../src/Assets/Controllers/updateAssetFile.ts"],"names":[],"mappings":";;AAGA,0CAeC;AAjBD,gEAA6D;AAE7D,SAAgB,eAAe,CAC7B,IAAU,EACV,OAAe,EACf,UAAyB;IAEzB,MAAM,EAAE,GAAG,qCAAiB,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACtD,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,UAAU,CAAC,aAAa,CACtB,iBAAiB,EACjB,kCAAkC,CACnC,CAAC;QACF,OAAO;IACT,CAAC;IAED,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC","sourcesContent":["import { AppObjectRepo } from \"@vived/core\";\r\nimport { UpdateAssetFileUC } from \"../UCs/UpdateAssetFileUC\";\r\n\r\nexport function updateAssetFile(\r\n  file: File,\r\n  assetID: string,\r\n  appObjects: AppObjectRepo\r\n) {\r\n  const uc = UpdateAssetFileUC.get(assetID, appObjects);\r\n  if (!uc) {\r\n    appObjects.submitWarning(\r\n      \"updateAssetFile\",\r\n      \"Unable to find UpdateAssetFileUC\"\r\n    );\r\n    return;\r\n  }\r\n\r\n  uc.updateFile(file);\r\n}\r\n"]}
+{"version":3,"file":"updateAssetFile.js","sourceRoot":"","sources":["../../../../src/Assets/Controllers/updateAssetFile.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;AAiBH,0CAeC;AA7BD,gEAA6D;AAE7D;;;;;;;;;;;GAWG;AACH,SAAgB,eAAe,CAC7B,IAAU,EACV,OAAe,EACf,UAAyB;IAEzB,MAAM,EAAE,GAAG,qCAAiB,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACtD,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,UAAU,CAAC,aAAa,CACtB,iBAAiB,EACjB,kCAAkC,CACnC,CAAC;QACF,OAAO;IACT,CAAC;IAED,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC","sourcesContent":["/**\r\n * updateAssetFile.ts\r\n *\r\n * This controller function handles updating the actual file content of existing assets.\r\n * It provides a streamlined interface for replacing asset files while preserving\r\n * the asset's metadata and relationships.\r\n *\r\n * Key Concepts:\r\n * - Updates the actual file content of existing assets\r\n * - Preserves asset metadata and relationships during file replacement\r\n * - Uses UpdateAssetFileUC to handle file upload and persistence\r\n * - Provides error handling for missing components\r\n *\r\n * Usage Patterns:\r\n * - Called from file upload interfaces when users replace asset files\r\n * - Used in asset management workflows for content updates\r\n * - Integrated with drag-and-drop file replacement interfaces\r\n */\r\n\r\nimport { AppObjectRepo } from \"@vived/core\";\r\nimport { UpdateAssetFileUC } from \"../UCs/UpdateAssetFileUC\";\r\n\r\n/**\r\n * Updates the file content of an existing asset.\r\n *\r\n * This function provides a controller-level interface for replacing the file\r\n * associated with an existing asset. It handles the upload and storage of the\r\n * new file while preserving all asset metadata and relationships.\r\n *\r\n * @param file - The new file object to replace the existing asset file\r\n * @param assetID - The unique identifier of the asset whose file should be updated\r\n * @param appObjects - Repository for accessing asset-related app objects and components\r\n * @returns void - The function initiates the file update process asynchronously\r\n */\r\nexport function updateAssetFile(\r\n  file: File,\r\n  assetID: string,\r\n  appObjects: AppObjectRepo\r\n) {\r\n  const uc = UpdateAssetFileUC.get(assetID, appObjects);\r\n  if (!uc) {\r\n    appObjects.submitWarning(\r\n      \"updateAssetFile\",\r\n      \"Unable to find UpdateAssetFileUC\"\r\n    );\r\n    return;\r\n  }\r\n\r\n  uc.updateFile(file);\r\n}\r\n"]}

package/dist/cjs/Assets/Entities/AppAssetsEntity.js

@@ -3,20 +3,102 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AppAssetsEntity = void 0;
 exports.makeAppAssets = makeAppAssets;
 const core_1 = require("@vived/core");
+/**
+ * AppAssetsEntity manages the collection of assets associated with a specific VIVED application.
+ *
+ * This singleton entity handles:
+ * 1. Asset collection management (add, remove, query operations)
+ * 2. Editing state management with automatic observer registration
+ * 3. Archive filtering functionality for showing/hiding archived assets
+ * 4. Global asset reference tracking for applications
+ *
+ * Key Concepts:
+ * - Singleton pattern ensures only one instance exists per application
+ * - Observer pattern integration for automatic UI updates when editing state changes
+ * - Smart observer management prevents memory leaks by properly registering/unregistering
+ * - Archive filtering support for improved user experience
+ *
+ * Usage Patterns:
+ * ```typescript
+ * // Get the global app assets entity
+ * const appAssets = AppAssetsEntity.get(appObjects);
+ * if (appAssets) {
+ *   // Manage asset collection
+ *   appAssets.add("asset123");
+ *   const allAssets = appAssets.getAll();
+ *   const hasAsset = appAssets.has("asset123");
+ *   appAssets.remove("asset123");
+ *
+ *   // Manage editing state
+ *   const assetEntity = AssetEntity.get(someAppObject);
+ *   appAssets.editingAsset = assetEntity; // Automatically registers observers
+ *
+ *   // Control archive visibility
+ *   appAssets.showArchived = true; // Show archived assets
+ *   appAssets.showArchived = false; // Hide archived assets
+ * }
+ * ```
+ *
+ * Integration Points:
+ * - Works with AssetRepo for asset lifecycle management
+ * - Integrates with AssetEntity for individual asset operations
+ * - Used by GetAppAssetsUC for bulk asset operations
+ * - Supports UI components through observer pattern notifications
+ */
 class AppAssetsEntity extends core_1.AppObjectEntity {
+    /**
+     * Retrieves the singleton AppAssetsEntity from the host application objects
+     * @param hostAppObjects - The application object repository to search
+     * @returns AppAssetsEntity instance or undefined if not found
+     * Uses getSingletonComponent to ensure only one instance exists
+     */
     static get(hostAppObjects) {
         return (0, core_1.getSingletonComponent)(AppAssetsEntity.type, hostAppObjects);
     }
 }
 exports.AppAssetsEntity = AppAssetsEntity;
+/** Static type identifier for component registration */
 AppAssetsEntity.type = "AppAssetsEntity";
+/**
+ * Factory function to create a new AppAssetsEntity instance
+ * @param appObj - The AppObject that will host this AppAssetsEntity
+ * @returns A new AppAssetsEntity implementation instance
+ */
 function makeAppAssets(appObj) {
     return new AppAssetsImp(appObj);
 }
+/**
+ * Private implementation of AppAssetsEntity that handles all concrete functionality.
+ *
+ * Key Implementation Details:
+ * - Maintains an array of asset IDs for the application
+ * - Smart observer management for editing asset changes
+ * - Memoized archive visibility flag with change notifications
+ * - Automatic singleton registration ensures global accessibility
+ *
+ * Observer Management Pattern:
+ * The editing asset property automatically manages observer registration to ensure
+ * that UI components are notified when the currently edited asset changes.
+ * When a new asset is set for editing, observers from the previous asset are
+ * properly removed to prevent memory leaks and duplicate notifications.
+ */
 class AppAssetsImp extends AppAssetsEntity {
+    /**
+     * Returns the currently editing asset
+     * @returns The AssetEntity being edited, or undefined if none
+     */
     get editingAsset() {
         return this._editingAsset;
     }
+    /**
+     * Sets the currently editing asset with smart observer management
+     * Automatically handles observer registration/deregistration to prevent memory leaks
+     * @param val - The AssetEntity to edit, or undefined to clear editing state
+     * Side effects:
+     * - Removes observers from previous editing asset
+     * - Adds observers to new editing asset
+     * - Triggers change notifications for UI updates
+     */
     set editingAsset(val) {
         if (val?.id === this._editingAsset?.id)
             return;
@@ -29,9 +111,19 @@ class AppAssetsImp extends AppAssetsEntity {
         }
         this.notifyOnChange();
     }
+    /**
+     * Checks if an asset ID exists in the collection
+     * @param assetID - The asset ID to check for
+     * @returns true if asset exists in collection, false otherwise
+     */
     has(assetID) {
         return this.appAssets.includes(assetID);
     }
+    /**
+     * Removes an asset ID from the collection if present
+     * @param assetID - The asset ID to remove
+     * Side effects: Triggers change notifications if asset was removed
+     */
     remove(assetID) {
         const index = this.appAssets.indexOf(assetID, 0);
         if (index > -1) {
@@ -39,24 +131,55 @@ class AppAssetsImp extends AppAssetsEntity {
             this.notifyOnChange();
         }
     }
+    /**
+     * Returns the current archive visibility setting
+     * @returns true if archived assets should be shown, false to hide them
+     */
     get showArchived() {
         return this.memoizedShowArchived.val;
     }
+    /**
+     * Sets the archive visibility with change notification
+     * @param show - true to show archived assets, false to hide them
+     * Side effects: Triggers change notifications for UI updates
+     */
     set showArchived(show) {
         this.memoizedShowArchived.val = show;
     }
+    /**
+     * Initializes the AppAssetsEntity with singleton registration
+     * @param appObj - The AppObject that will host this entity
+     * Side effects: Registers this instance as a singleton for global access
+     */
     constructor(appObj) {
         super(appObj, AppAssetsEntity.type);
+        /** Internal storage for the collection of asset IDs */
         this.appAssets = [];
+        /**
+         * Retrieves all asset IDs in the collection
+         * Returns a copy to prevent external modification of internal state
+         * @returns Array of asset IDs
+         */
         this.getAll = () => {
             return [...this.appAssets];
         };
+        /**
+         * Adds an asset ID to the collection if not already present
+         * Prevents duplicate entries and maintains collection integrity
+         * @param assetID - The asset ID to add
+         * Side effects: Triggers change notifications if asset was added
+         */
         this.add = (assetID) => {
             if (this.appAssets.includes(assetID))
                 return;
             this.appAssets.push(assetID);
             this.notifyOnChange();
         };
+        /**
+         * Memoized archive visibility flag with change notification
+         * Controls whether archived assets should be shown in UI components
+         * Defaults to false (archived assets hidden)
+         */
         this.memoizedShowArchived = new core_1.MemoizedBoolean(false, this.notifyOnChange);
         this.appObjects.registerSingleton(this);
     }

package/dist/cjs/Assets/Entities/AppAssetsEntity.js.map

@@ -1 +1 @@
-{"version":3,"file":"AppAssetsEntity.js","sourceRoot":"","sources":["../../../../src/Assets/Entities/AppAssetsEntity.ts"],"names":[],"mappings":";;;AA4BA,sCAEC;AA9BD,sCAMqB;AAGrB,MAAsB,eAAgB,SAAQ,sBAAe;IAc3D,MAAM,CAAC,GAAG,CAAC,cAA6B;QACtC,OAAO,IAAA,4BAAqB,EAAC,eAAe,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IACrE,CAAC;;AAhBH,0CAiBC;AAhBQ,oBAAI,GAAG,iBAAiB,CAAC;AAkBlC,SAAgB,aAAa,CAAC,MAAiB;IAC7C,OAAO,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,YAAa,SAAQ,eAAe;IAIxC,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAED,IAAI,YAAY,CAAC,GAA4B;QAC3C,IAAI,GAAG,EAAE,EAAE,KAAK,IAAI,CAAC,aAAa,EAAE,EAAE;YAAE,OAAO;QAE/C,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,IAAI,CAAC,aAAa,CAAC,oBAAoB,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC/D,CAAC;QAED,IAAI,CAAC,aAAa,GAAG,GAAG,CAAC;QAEzB,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,IAAI,CAAC,aAAa,CAAC,iBAAiB,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC5D,CAAC;QAED,IAAI,CAAC,cAAc,EAAE,CAAC;IACxB,CAAC;IAaD,GAAG,CAAC,OAAe;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED,MAAM,CAAC,OAAe;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACjD,IAAI,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;YACf,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YAChC,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,CAAC;IACH,CAAC;IAMD,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC;IACvC,CAAC;IACD,IAAI,YAAY,CAAC,IAAa;QAC5B,IAAI,CAAC,oBAAoB,CAAC,GAAG,GAAG,IAAI,CAAC;IACvC,CAAC;IAED,YAAY,MAAiB;QAC3B,KAAK,CAAC,MAAM,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC;QA1D9B,cAAS,GAAa,EAAE,CAAC;QAuBjC,WAAM,GAAG,GAAa,EAAE;YACtB,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;QAC7B,CAAC,CAAC;QAEF,QAAG,GAAG,CAAC,OAAe,EAAQ,EAAE;YAC9B,IAAI,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAAE,OAAO;YAE7C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC7B,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,CAAC,CAAC;QAcM,yBAAoB,GAAG,IAAI,sBAAe,CAChD,KAAK,EACL,IAAI,CAAC,cAAc,CACpB,CAAC;QAUA,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;CACF","sourcesContent":["import {\r\n  AppObject,\r\n  AppObjectEntity,\r\n  AppObjectRepo,\r\n  getSingletonComponent,\r\n  MemoizedBoolean\r\n} from \"@vived/core\";\r\nimport { AssetEntity } from \"./AssetEntity\";\r\n\r\nexport abstract class AppAssetsEntity extends AppObjectEntity {\r\n  static type = \"AppAssetsEntity\";\r\n\r\n  abstract getAll(): string[];\r\n  abstract add(assetID: string): void;\r\n  abstract has(assetID: string): boolean;\r\n  abstract remove(assetID: string): void;\r\n\r\n  abstract get editingAsset(): AssetEntity | undefined;\r\n  abstract set editingAsset(val: AssetEntity | undefined);\r\n\r\n  abstract get showArchived(): boolean;\r\n  abstract set showArchived(show: boolean);\r\n\r\n  static get(hostAppObjects: AppObjectRepo): AppAssetsEntity | undefined {\r\n    return getSingletonComponent(AppAssetsEntity.type, hostAppObjects);\r\n  }\r\n}\r\n\r\nexport function makeAppAssets(appObj: AppObject): AppAssetsEntity {\r\n  return new AppAssetsImp(appObj);\r\n}\r\n\r\nclass AppAssetsImp extends AppAssetsEntity {\r\n  private appAssets: string[] = [];\r\n\r\n  private _editingAsset: AssetEntity | undefined;\r\n  get editingAsset(): AssetEntity | undefined {\r\n    return this._editingAsset;\r\n  }\r\n\r\n  set editingAsset(val: AssetEntity | undefined) {\r\n    if (val?.id === this._editingAsset?.id) return;\r\n\r\n    if (this._editingAsset) {\r\n      this._editingAsset.removeChangeObserver(this.notifyOnChange);\r\n    }\r\n\r\n    this._editingAsset = val;\r\n\r\n    if (this._editingAsset) {\r\n      this._editingAsset.addChangeObserver(this.notifyOnChange);\r\n    }\r\n\r\n    this.notifyOnChange();\r\n  }\r\n\r\n  getAll = (): string[] => {\r\n    return [...this.appAssets];\r\n  };\r\n\r\n  add = (assetID: string): void => {\r\n    if (this.appAssets.includes(assetID)) return;\r\n\r\n    this.appAssets.push(assetID);\r\n    this.notifyOnChange();\r\n  };\r\n\r\n  has(assetID: string): boolean {\r\n    return this.appAssets.includes(assetID);\r\n  }\r\n\r\n  remove(assetID: string): void {\r\n    const index = this.appAssets.indexOf(assetID, 0);\r\n    if (index > -1) {\r\n      this.appAssets.splice(index, 1);\r\n      this.notifyOnChange();\r\n    }\r\n  }\r\n\r\n  private memoizedShowArchived = new MemoizedBoolean(\r\n    false,\r\n    this.notifyOnChange\r\n  );\r\n  get showArchived(): boolean {\r\n    return this.memoizedShowArchived.val;\r\n  }\r\n  set showArchived(show: boolean) {\r\n    this.memoizedShowArchived.val = show;\r\n  }\r\n\r\n  constructor(appObj: AppObject) {\r\n    super(appObj, AppAssetsEntity.type);\r\n    this.appObjects.registerSingleton(this);\r\n  }\r\n}\r\n"]}
+{"version":3,"file":"AppAssetsEntity.js","sourceRoot":"","sources":["../../../../src/Assets/Entities/AppAssetsEntity.ts"],"names":[],"mappings":"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","sourcesContent":["import {\r\n  AppObject,\r\n  AppObjectEntity,\r\n  AppObjectRepo,\r\n  getSingletonComponent,\r\n  MemoizedBoolean\r\n} from \"@vived/core\";\r\nimport { AssetEntity } from \"./AssetEntity\";\r\n\r\n/**\r\n * AppAssetsEntity manages the collection of assets associated with a specific VIVED application.\r\n *\r\n * This singleton entity handles:\r\n * 1. Asset collection management (add, remove, query operations)\r\n * 2. Editing state management with automatic observer registration\r\n * 3. Archive filtering functionality for showing/hiding archived assets\r\n * 4. Global asset reference tracking for applications\r\n *\r\n * Key Concepts:\r\n * - Singleton pattern ensures only one instance exists per application\r\n * - Observer pattern integration for automatic UI updates when editing state changes\r\n * - Smart observer management prevents memory leaks by properly registering/unregistering\r\n * - Archive filtering support for improved user experience\r\n *\r\n * Usage Patterns:\r\n * ```typescript\r\n * // Get the global app assets entity\r\n * const appAssets = AppAssetsEntity.get(appObjects);\r\n * if (appAssets) {\r\n *   // Manage asset collection\r\n *   appAssets.add(\"asset123\");\r\n *   const allAssets = appAssets.getAll();\r\n *   const hasAsset = appAssets.has(\"asset123\");\r\n *   appAssets.remove(\"asset123\");\r\n *\r\n *   // Manage editing state\r\n *   const assetEntity = AssetEntity.get(someAppObject);\r\n *   appAssets.editingAsset = assetEntity; // Automatically registers observers\r\n *\r\n *   // Control archive visibility\r\n *   appAssets.showArchived = true; // Show archived assets\r\n *   appAssets.showArchived = false; // Hide archived assets\r\n * }\r\n * ```\r\n *\r\n * Integration Points:\r\n * - Works with AssetRepo for asset lifecycle management\r\n * - Integrates with AssetEntity for individual asset operations\r\n * - Used by GetAppAssetsUC for bulk asset operations\r\n * - Supports UI components through observer pattern notifications\r\n */\r\nexport abstract class AppAssetsEntity extends AppObjectEntity {\r\n  /** Static type identifier for component registration */\r\n  static type = \"AppAssetsEntity\";\r\n\r\n  /**\r\n   * Retrieves all asset IDs in this application's collection\r\n   * @returns Array of asset IDs, returned as a copy to prevent external modification\r\n   */\r\n  abstract getAll(): string[];\r\n\r\n  /**\r\n   * Adds an asset ID to the collection if not already present\r\n   * @param assetID - The unique identifier of the asset to add\r\n   * Side effects: Triggers change notifications for UI updates\r\n   */\r\n  abstract add(assetID: string): void;\r\n\r\n  /**\r\n   * Checks if an asset ID exists in the collection\r\n   * @param assetID - The unique identifier to check for\r\n   * @returns true if the asset is in the collection, false otherwise\r\n   */\r\n  abstract has(assetID: string): boolean;\r\n\r\n  /**\r\n   * Removes an asset ID from the collection if present\r\n   * @param assetID - The unique identifier of the asset to remove\r\n   * Side effects: Triggers change notifications for UI updates\r\n   */\r\n  abstract remove(assetID: string): void;\r\n\r\n  /**\r\n   * The asset currently being edited, if any\r\n   * When set, automatically manages observer registration for change notifications\r\n   * Setting to undefined clears the editing state\r\n   */\r\n  abstract get editingAsset(): AssetEntity | undefined;\r\n  abstract set editingAsset(val: AssetEntity | undefined);\r\n\r\n  /**\r\n   * Controls whether archived assets are shown in UI components\r\n   * When true, archived assets are included in queries and displays\r\n   * When false, archived assets are filtered out for better UX\r\n   */\r\n  abstract get showArchived(): boolean;\r\n  abstract set showArchived(show: boolean);\r\n\r\n  /**\r\n   * Retrieves the singleton AppAssetsEntity from the host application objects\r\n   * @param hostAppObjects - The application object repository to search\r\n   * @returns AppAssetsEntity instance or undefined if not found\r\n   * Uses getSingletonComponent to ensure only one instance exists\r\n   */\r\n  static get(hostAppObjects: AppObjectRepo): AppAssetsEntity | undefined {\r\n    return getSingletonComponent(AppAssetsEntity.type, hostAppObjects);\r\n  }\r\n}\r\n\r\n/**\r\n * Factory function to create a new AppAssetsEntity instance\r\n * @param appObj - The AppObject that will host this AppAssetsEntity\r\n * @returns A new AppAssetsEntity implementation instance\r\n */\r\nexport function makeAppAssets(appObj: AppObject): AppAssetsEntity {\r\n  return new AppAssetsImp(appObj);\r\n}\r\n\r\n/**\r\n * Private implementation of AppAssetsEntity that handles all concrete functionality.\r\n *\r\n * Key Implementation Details:\r\n * - Maintains an array of asset IDs for the application\r\n * - Smart observer management for editing asset changes\r\n * - Memoized archive visibility flag with change notifications\r\n * - Automatic singleton registration ensures global accessibility\r\n *\r\n * Observer Management Pattern:\r\n * The editing asset property automatically manages observer registration to ensure\r\n * that UI components are notified when the currently edited asset changes.\r\n * When a new asset is set for editing, observers from the previous asset are\r\n * properly removed to prevent memory leaks and duplicate notifications.\r\n */\r\nclass AppAssetsImp extends AppAssetsEntity {\r\n  /** Internal storage for the collection of asset IDs */\r\n  private appAssets: string[] = [];\r\n\r\n  /** Internal reference to the currently editing asset */\r\n  private _editingAsset: AssetEntity | undefined;\r\n\r\n  /**\r\n   * Returns the currently editing asset\r\n   * @returns The AssetEntity being edited, or undefined if none\r\n   */\r\n  get editingAsset(): AssetEntity | undefined {\r\n    return this._editingAsset;\r\n  }\r\n\r\n  /**\r\n   * Sets the currently editing asset with smart observer management\r\n   * Automatically handles observer registration/deregistration to prevent memory leaks\r\n   * @param val - The AssetEntity to edit, or undefined to clear editing state\r\n   * Side effects:\r\n   * - Removes observers from previous editing asset\r\n   * - Adds observers to new editing asset\r\n   * - Triggers change notifications for UI updates\r\n   */\r\n  set editingAsset(val: AssetEntity | undefined) {\r\n    if (val?.id === this._editingAsset?.id) return;\r\n\r\n    if (this._editingAsset) {\r\n      this._editingAsset.removeChangeObserver(this.notifyOnChange);\r\n    }\r\n\r\n    this._editingAsset = val;\r\n\r\n    if (this._editingAsset) {\r\n      this._editingAsset.addChangeObserver(this.notifyOnChange);\r\n    }\r\n\r\n    this.notifyOnChange();\r\n  }\r\n\r\n  /**\r\n   * Retrieves all asset IDs in the collection\r\n   * Returns a copy to prevent external modification of internal state\r\n   * @returns Array of asset IDs\r\n   */\r\n  getAll = (): string[] => {\r\n    return [...this.appAssets];\r\n  };\r\n\r\n  /**\r\n   * Adds an asset ID to the collection if not already present\r\n   * Prevents duplicate entries and maintains collection integrity\r\n   * @param assetID - The asset ID to add\r\n   * Side effects: Triggers change notifications if asset was added\r\n   */\r\n  add = (assetID: string): void => {\r\n    if (this.appAssets.includes(assetID)) return;\r\n\r\n    this.appAssets.push(assetID);\r\n    this.notifyOnChange();\r\n  };\r\n\r\n  /**\r\n   * Checks if an asset ID exists in the collection\r\n   * @param assetID - The asset ID to check for\r\n   * @returns true if asset exists in collection, false otherwise\r\n   */\r\n  has(assetID: string): boolean {\r\n    return this.appAssets.includes(assetID);\r\n  }\r\n\r\n  /**\r\n   * Removes an asset ID from the collection if present\r\n   * @param assetID - The asset ID to remove\r\n   * Side effects: Triggers change notifications if asset was removed\r\n   */\r\n  remove(assetID: string): void {\r\n    const index = this.appAssets.indexOf(assetID, 0);\r\n    if (index > -1) {\r\n      this.appAssets.splice(index, 1);\r\n      this.notifyOnChange();\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Memoized archive visibility flag with change notification\r\n   * Controls whether archived assets should be shown in UI components\r\n   * Defaults to false (archived assets hidden)\r\n   */\r\n  private memoizedShowArchived = new MemoizedBoolean(\r\n    false,\r\n    this.notifyOnChange\r\n  );\r\n\r\n  /**\r\n   * Returns the current archive visibility setting\r\n   * @returns true if archived assets should be shown, false to hide them\r\n   */\r\n  get showArchived(): boolean {\r\n    return this.memoizedShowArchived.val;\r\n  }\r\n\r\n  /**\r\n   * Sets the archive visibility with change notification\r\n   * @param show - true to show archived assets, false to hide them\r\n   * Side effects: Triggers change notifications for UI updates\r\n   */\r\n  set showArchived(show: boolean) {\r\n    this.memoizedShowArchived.val = show;\r\n  }\r\n\r\n  /**\r\n   * Initializes the AppAssetsEntity with singleton registration\r\n   * @param appObj - The AppObject that will host this entity\r\n   * Side effects: Registers this instance as a singleton for global access\r\n   */\r\n  constructor(appObj: AppObject) {\r\n    super(appObj, AppAssetsEntity.type);\r\n    this.appObjects.registerSingleton(this);\r\n  }\r\n}\r\n"]}

package/dist/cjs/Assets/Entities/AssetEntity.js

@@ -3,7 +3,62 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AssetEntity = void 0;
 exports.makeAssetEntity = makeAssetEntity;
 const core_1 = require("@vived/core");
+/**
+ * AssetEntity manages individual file-based resources in VIVED applications.
+ *
+ * This entity handles:
+ * 1. Asset metadata (name, description, owner, archive status)
+ * 2. File management (filename, fileURL, blob URL creation)
+ * 3. Linked asset relationships for hierarchical asset structures
+ * 4. Fetch state management (loading indicators, error handling)
+ * 5. Observer pattern implementation for UI updates
+ *
+ * Key Concepts:
+ * - Uses memoized properties for efficient change tracking and notifications
+ * - Supports both file URLs (remote) and blob URLs (local) for flexible file access
+ * - Maintains linked asset relationships to support complex asset hierarchies
+ * - Implements observer pattern to notify UI components of changes
+ *
+ * Usage Patterns:
+ * ```typescript
+ * // Get an asset entity from an app object
+ * const asset = AssetEntity.get(appObject);
+ * if (asset) {
+ *   // Set asset metadata
+ *   asset.name = "My Asset";
+ *   asset.description = "A sample asset";
+ *
+ *   // Handle file operations
+ *   asset.setFile(fileObject);
+ *   const blobURL = asset.blobURL; // Access local blob URL
+ *
+ *   // Manage linked assets
+ *   asset.addLinkedAsset("texture", "texture123");
+ *   const textures = asset.getLinkedAssetByType("texture");
+ *
+ *   // Monitor fetch state
+ *   if (asset.isFetchingFile) {
+ *     console.log("File is being downloaded...");
+ *   }
+ *   if (asset.fetchError) {
+ *     console.error("Failed to fetch file:", asset.fetchError.message);
+ *   }
+ * }
+ * ```
+ *
+ * Integration Points:
+ * - Works with AssetRepo for asset lifecycle management
+ * - Integrates with AppAssetsEntity for collection management
+ * - Used by GetAssetBlobURLUC for file retrieval operations
+ * - Supports caching mechanisms for optimized file access
+ */
 class AssetEntity extends core_1.AppObjectEntity {
+    /**
+     * Retrieves an AssetEntity component from an AppObject
+     * @param appObject - The AppObject to search for the AssetEntity component
+     * @returns AssetEntity instance or undefined if not found
+     * Logs warning if component is not found to aid in debugging
+     */
     static get(appObject) {
         const asset = appObject.getComponent(AssetEntity.type);
         if (!asset) {
@@ -13,11 +68,33 @@ class AssetEntity extends core_1.AppObjectEntity {
     }
 }
 exports.AssetEntity = AssetEntity;
+/** Static type identifier for component registration */
 AssetEntity.type = "AssetEntity";
+/**
+ * Factory function to create a new AssetEntity instance
+ * @param appObject - The AppObject that will host this AssetEntity
+ * @returns A new AssetEntity implementation instance
+ */
 function makeAssetEntity(appObject) {
     return new AssetImp(appObject);
 }
+/**
+ * Private implementation of AssetEntity that handles all the concrete functionality.
+ *
+ * Key Implementation Details:
+ * - Uses MemoizedString and MemoizedBoolean for efficient change tracking
+ * - All memoized properties automatically trigger change notifications when modified
+ * - Blob URL management with proper cleanup on disposal
+ * - Linked asset management with duplicate prevention
+ * - File fetch state management for async operations
+ *
+ * Memoization Pattern:
+ * The implementation uses memoized properties that only trigger change notifications
+ * when values actually change, preventing unnecessary UI updates and improving performance.
+ * Each memoized property is initialized with a default value and a change callback.
+ */
 class AssetImp extends AssetEntity {
+    /** Returns the unique ID from the underlying AppObject */
     get id() {
         return this.appObject.id;
     }
@@ -57,15 +134,25 @@ class AssetImp extends AssetEntity {
     set fileURL(name) {
         this._memoizedFileURL.val = name;
     }
+    /** Returns the locally stored file object, if any */
     get file() {
         return this._file;
     }
+    /** Returns the blob URL for local file access, if available */
     get blobURL() {
         return this._blobURL;
     }
+    /**
+     * Indicates whether a file has been successfully fetched and stored locally
+     * Used to determine if file operations can proceed without network requests
+     */
     get fileHasBeenFetched() {
         return this._file !== undefined;
     }
+    /**
+     * Returns a copy of all linked assets to prevent external modification
+     * This ensures the internal state cannot be corrupted by external code
+     */
     get linkedAssets() {
         return [...this._linkedAssets];
     }
@@ -75,9 +162,16 @@ class AssetImp extends AssetEntity {
     set isFetchingFile(archived) {
         this._memoizedIsFetchingFile.val = archived;
     }
+    /** Returns the current fetch error, if any */
     get fetchError() {
         return this._fetchError;
     }
+    /**
+     * Sets the fetch error with smart change detection
+     * Only triggers change notifications if the error actually changes
+     * This prevents unnecessary UI updates when the same error is set multiple times
+     * @param fetchError - The error that occurred, or undefined to clear the error
+     */
     set fetchError(fetchError) {
         if (fetchError === undefined && this.fetchError === undefined)
             return;
@@ -88,22 +182,68 @@ class AssetImp extends AssetEntity {
         this._fetchError = fetchError;
         this.notifyOnChange();
     }
+    /**
+     * Initializes the AssetEntity with proper component registration
+     * @param appObject - The AppObject that will host this entity
+     */
     constructor(appObject) {
         super(appObject, AssetEntity.type);
+        /**
+         * Memoized asset name with change notification
+         * Initialized to empty string, triggers notifyOnChange when modified
+         */
         this._memoizedName = new core_1.MemoizedString("", this.notifyOnChange);
+        /**
+         * Memoized asset owner with change notification
+         * Stores the ID of the user/entity that owns this asset
+         */
         this._memoizedOwner = new core_1.MemoizedString("", this.notifyOnChange);
+        /**
+         * Memoized asset description with change notification
+         * Stores detailed information about the asset's purpose or content
+         */
         this._memoizedDescription = new core_1.MemoizedString("", this.notifyOnChange);
+        /**
+         * Memoized archive status with change notification
+         * Used for soft deletion and filtering of assets
+         */
         this._memoizedArchived = new core_1.MemoizedBoolean(false, this.notifyOnChange);
+        /**
+         * Memoized file URL for remote asset access
+         * Points to where the actual file can be downloaded from
+         */
         this._memoizedFileURL = new core_1.MemoizedString("", this.notifyOnChange);
+        /**
+         * Memoized filename for display and download purposes
+         * Preserves the original name of the uploaded file
+         */
         this._memoizedFilename = new core_1.MemoizedString("", this.notifyOnChange);
+        /** Local file object storage */
         this._file = undefined;
+        /** Local blob URL for immediate file access */
         this._blobURL = undefined;
+        /**
+         * Sets a local file and creates a blob URL for immediate access
+         * This is typically called after successfully downloading a file
+         * @param file - The file object to store locally
+         * Side effects: Creates blob URL, triggers change notifications to update UI
+         */
         this.setFile = (file) => {
             this._file = file;
             this._blobURL = URL.createObjectURL(file);
             this.notifyOnChange();
         };
+        /**
+         * Storage for linked asset relationships
+         * Supports hierarchical asset structures where assets depend on other assets
+         */
         this._linkedAssets = [];
+        /**
+         * Adds a linked asset relationship if it doesn't already exist
+         * Prevents duplicate relationships and maintains data integrity
+         * @param type - Category of the linked asset (e.g., "texture", "sound", "model")
+         * @param id - Unique identifier of the linked asset
+         */
         this.addLinkedAsset = (type, id) => {
             const existingAsset = this._linkedAssets.find((asset) => {
                 return asset.id === id;
@@ -116,6 +256,12 @@ class AssetImp extends AssetEntity {
                 this.notifyOnChange();
             }
         };
+        /**
+         * Removes a linked asset relationship if it exists
+         * Maintains referential integrity by only removing exact matches
+         * @param type - Category of the linked asset to remove
+         * @param id - Unique identifier of the linked asset to remove
+         */
         this.removeLinkedAsset = (type, id) => {
             let foundAsset = false;
             this._linkedAssets.forEach((asset) => {
@@ -128,6 +274,12 @@ class AssetImp extends AssetEntity {
                 this.notifyOnChange();
             }
         };
+        /**
+         * Retrieves all linked asset IDs of a specific type
+         * Useful for finding all assets of a particular category (e.g., all textures)
+         * @param type - The asset type to filter by
+         * @returns Array of asset IDs matching the specified type
+         */
         this.getLinkedAssetByType = (type) => {
             const rVal = [];
             this._linkedAssets.forEach((asset) => {
@@ -137,8 +289,22 @@ class AssetImp extends AssetEntity {
             });
             return rVal;
         };
+        /**
+         * Memoized fetch state indicator with change notification
+         * Used to show loading states in UI during file download operations
+         */
         this._memoizedIsFetchingFile = new core_1.MemoizedBoolean(false, this.notifyOnChange);
+        /**
+         * Storage for the most recent fetch error
+         * Helps with error handling and user feedback in UI components
+         */
         this._fetchError = undefined;
+        /**
+         * Cleanup method that properly releases blob URL resources
+         * Important: Blob URLs must be revoked to prevent memory leaks
+         * This is automatically called when the entity is disposed
+         * Side effects: Revokes blob URL, triggers change notification, calls parent dispose
+         */
         this.dispose = () => {
             if (this._blobURL !== undefined) {
                 URL.revokeObjectURL(this._blobURL);