@zephyr3d/scene 0.9.2 → 0.9.3

package/dist/utility/serialization/manager.js

@@ -111,29 +111,29 @@ const defaultValues = {
     ],
     command: null
 };
-/**
- * Manages serialization and deserialization of engine objects to/from JSON,
- * including asset resolution via a virtual file system (VFS) and asset manager.
- *
- * @remarks
- * - Keeps a registry of serializable classes and their properties.
- * - Converts object graphs to JSON using per-class metadata and property accessors.
- * - Supports async asset embedding/export and lazy deserialization via phases.
- * - Maps loaded assets/objects back to their source IDs for caching and deduplication.
- *
- * Typical workflow:
- * 1. Construct with a `VFS`.
- * 2. Optionally `registerClass` for custom types.
- * 3. Use `serializeObject` and `deserializeObject` to convert between runtime objects and JSON.
- * 4. Use `saveScene` / `loadScene` for scene I/O.
- *
- * Caching:
- * - `getAssetId` returns the known source ID for an allocated asset when available.
- *
- * Threading:
- * - Methods returning Promises perform async I/O using the provided `VFS`/AssetManager.
- *
- * @public
+/**
+ * Manages serialization and deserialization of engine objects to/from JSON,
+ * including asset resolution via a virtual file system (VFS) and asset manager.
+ *
+ * @remarks
+ * - Keeps a registry of serializable classes and their properties.
+ * - Converts object graphs to JSON using per-class metadata and property accessors.
+ * - Supports async asset embedding/export and lazy deserialization via phases.
+ * - Maps loaded assets/objects back to their source IDs for caching and deduplication.
+ *
+ * Typical workflow:
+ * 1. Construct with a `VFS`.
+ * 2. Optionally `registerClass` for custom types.
+ * 3. Use `serializeObject` and `deserializeObject` to convert between runtime objects and JSON.
+ * 4. Use `saveScene` / `loadScene` for scene I/O.
+ *
+ * Caching:
+ * - `getAssetId` returns the known source ID for an allocated asset when available.
+ *
+ * Threading:
+ * - Methods returning Promises perform async I/O using the provided `VFS`/AssetManager.
+ *
+ * @public
  */ class ResourceManager {
     _classMap;
     _vfs;
@@ -143,10 +143,10 @@ const defaultValues = {
     _assetManager;
     _editorMode;
     _allocated;
-    /**
-   * Create a ResourceManager bound to a virtual file system.
-   *
-   * @param vfs - Virtual file system used for reading/writing assets and scenes.
+    /**
+   * Create a ResourceManager bound to a virtual file system.
+   *
+   * @param vfs - Virtual file system used for reading/writing assets and scenes.
    */ constructor(vfs, editorMode = false){
         this._vfs = vfs;
         this._editorMode = editorMode;
@@ -330,49 +330,49 @@ const defaultValues = {
             this.registerProps(k[1]);
         }
     }
-    /**
-   * The virtual file system used by this manager.
-   *
-   * @remarks
-   * Used by asset fetchers and scene save/load operations.
+    /**
+   * The virtual file system used by this manager.
+   *
+   * @remarks
+   * Used by asset fetchers and scene save/load operations.
    */ get VFS() {
         return this._vfs;
     }
     set VFS(vfs) {
         this._vfs = vfs;
     }
-    /**
-   * Wethether editor mode is enabled
-   *
-   * @remarks
-   * In editor mode, some properties will be disabled
+    /**
+   * Wethether editor mode is enabled
+   *
+   * @remarks
+   * In editor mode, some properties will be disabled
    */ get editorMode() {
         return this._editorMode;
     }
-    /**
-   * AssetManager
+    /**
+   * AssetManager
    */ get assetManager() {
         return this._assetManager;
     }
-    /**
-   * Get the list of all registered serializable classes.
-   *
-   * @remarks
-   * Includes built-in classes registered during construction and any custom classes
-   * registered via `registerClass`.
-   *
-   * @returns An array of `SerializableClass` metadata.
+    /**
+   * Get the list of all registered serializable classes.
+   *
+   * @remarks
+   * Includes built-in classes registered during construction and any custom classes
+   * registered via `registerClass`.
+   *
+   * @returns An array of `SerializableClass` metadata.
    */ getClasses() {
         return [
             ...this._classMap.values()
         ];
     }
-    /**
-   * Get serialization metadata by a constructor function.
-   *
-   * @param ctor - The class constructor to look up.
-   *
-   * @returns The `SerializableClass` metadata, or `null` if not found.
+    /**
+   * Get serialization metadata by a constructor function.
+   *
+   * @param ctor - The class constructor to look up.
+   *
+   * @returns The `SerializableClass` metadata, or `null` if not found.
    */ getClassByConstructor(ctor) {
         let current = ctor;
         while(typeof current === 'function' && current !== Function.prototype){
@@ -384,21 +384,21 @@ const defaultValues = {
         }
         return null;
     }
-    /**
-   * Get serialization metadata by an object instance.
-   *
-   * @param obj - The object whose constructor will be used for the lookup.
-   *
-   * @returns The `SerializableClass` metadata, or `null` if not found.
+    /**
+   * Get serialization metadata by an object instance.
+   *
+   * @param obj - The object whose constructor will be used for the lookup.
+   *
+   * @returns The `SerializableClass` metadata, or `null` if not found.
    */ getClassByObject(obj) {
         return this.getClassByConstructor(obj.constructor);
     }
-    /**
-   * Get serialization metadata by class name.
-   *
-   * @param className - Fully qualified class name as stored in JSON.
-   *
-   * @returns The `SerializableClass` metadata, or `null` if not found.
+    /**
+   * Get serialization metadata by class name.
+   *
+   * @param className - Fully qualified class name as stored in JSON.
+   *
+   * @returns The `SerializableClass` metadata, or `null` if not found.
    */ getClassByName(className) {
         for (const val of this._classMap){
             if (val[0].name === className) {
@@ -407,12 +407,12 @@ const defaultValues = {
         }
         return null;
     }
-    /**
-   * Find the class that owns a given property accessor.
-   *
-   * @param prop - Property accessor to search for.
-   *
-   * @returns The `SerializableClass` that declares the property, or `null` if unknown.
+    /**
+   * Find the class that owns a given property accessor.
+   *
+   * @param prop - Property accessor to search for.
+   *
+   * @returns The `SerializableClass` that declares the property, or `null` if unknown.
    */ getClassByProperty(prop) {
         for (const k of this._clsPropMap){
             if (k[1].indexOf(prop) >= 0) {
@@ -421,21 +421,21 @@ const defaultValues = {
         }
         return null;
     }
-    /**
-   * Get the properties declared on a given class.
-   *
-   * @param cls - Serializable class metadata.
-   *
-   * @returns An array of `PropertyAccessor` entries, or `null` if none.
+    /**
+   * Get the properties declared on a given class.
+   *
+   * @param cls - Serializable class metadata.
+   *
+   * @returns An array of `PropertyAccessor` entries, or `null` if none.
    */ getPropertiesByClass(cls) {
         return this._clsPropMap.get(cls) ?? null;
     }
-    /**
-   * Get all properties declared on a given class and its ancestors.
-   *
-   * @param cls - Serializable class metadata.
-   *
-   * @returns An array of `PropertyAccessor` entries, or `null` if none.
+    /**
+   * Get all properties declared on a given class and its ancestors.
+   *
+   * @param cls - Serializable class metadata.
+   *
+   * @returns An array of `PropertyAccessor` entries, or `null` if none.
    */ getAllPropertiesByClass(cls) {
         const props = new Map();
         while(cls){
@@ -453,72 +453,72 @@ const defaultValues = {
             ...props.values()
         ];
     }
-    /**
-   * Get a property accessor by class and property name.
-   *
-   * @param cls - Serializable class metadata.
-   * @param name - Property name to search for.
-   *
-   * @returns The `PropertyAccessor`, or `null` if not found.
+    /**
+   * Get a property accessor by class and property name.
+   *
+   * @param cls - Serializable class metadata.
+   * @param name - Property name to search for.
+   *
+   * @returns The `PropertyAccessor`, or `null` if not found.
    */ getPropertyByClass(cls, name) {
         return this.getPropertiesByClass(cls)?.find((value)=>value.name === name) ?? null;
     }
-    /**
-   * Get a property accessor by its canonical path.
-   *
-   * @remarks
-   * The canonical path format is `/ClassName/propName`.
-   *
-   * @param name - Canonical property path.
-   *
-   * @returns The `PropertyAccessor`, or `null` if not found.
+    /**
+   * Get a property accessor by its canonical path.
+   *
+   * @remarks
+   * The canonical path format is `/ClassName/propName`.
+   *
+   * @param name - Canonical property path.
+   *
+   * @returns The `PropertyAccessor`, or `null` if not found.
    */ getPropertyByName(name) {
         return this._propMap[name] ?? null;
     }
-    /**
-   * Get the canonical path for a property accessor.
-   *
-   * @remarks
-   * Returns a string like `/ClassName/propName` if the property is registered.
-   *
-   * @param prop - Property accessor.
-   *
-   * @returns The canonical path, or `null` if unknown.
+    /**
+   * Get the canonical path for a property accessor.
+   *
+   * @remarks
+   * Returns a string like `/ClassName/propName` if the property is registered.
+   *
+   * @param prop - Property accessor.
+   *
+   * @returns The canonical path, or `null` if unknown.
    */ getPropertyName(prop) {
         return this._propNameMap.get(prop) ?? null;
     }
-    /**
-   * Register a serializable class and its properties.
-   *
-   * @remarks
-   * - No effect if the class is already registered.
-   * - Also registers the class's properties with canonical paths.
-   *
-   * @param cls - Serializable class metadata to register.
+    /**
+   * Register a serializable class and its properties.
+   *
+   * @remarks
+   * - No effect if the class is already registered.
+   * - Also registers the class's properties with canonical paths.
+   *
+   * @param cls - Serializable class metadata to register.
    */ registerClass(cls) {
         if (!this._classMap.has(cls.ctor)) {
             this._classMap.set(cls.ctor, cls);
             this.registerProps(cls);
         }
     }
-    /**
-   * Get the known asset ID previously associated with a loaded/allocated asset.
-   *
-   * @remarks
-   * Returns `null` if the asset was not loaded or tracked by this manager.
-   *
-   * @param asset - Asset instance (e.g., texture, model group) to look up.
-   *
-   * @returns The asset ID string, or `null` if unknown.
+    /**
+   * Get the known asset ID previously associated with a loaded/allocated asset.
+   *
+   * @remarks
+   * Returns `null` if the asset was not loaded or tracked by this manager.
+   *
+   * @param asset - Asset instance (e.g., texture, model group) to look up.
+   *
+   * @returns The asset ID string, or `null` if unknown.
    */ getAssetId(asset) {
         return this._allocated.get(asset) ?? null;
     }
-    /**
-   * Associate an asset ID to a loaded/allocated asset.
-   *
-   * @param asset - Asset instance (e.g., texture, model group) to set Id.
-   * @param id - Asset ID to associated to this asset.
-   *
+    /**
+   * Associate an asset ID to a loaded/allocated asset.
+   *
+   * @param asset - Asset instance (e.g., texture, model group) to set Id.
+   * @param id - Asset ID to associated to this asset.
+   *
    */ setAssetId(asset, id) {
         if (asset) {
             if (id) {
@@ -528,16 +528,16 @@ const defaultValues = {
             }
         }
     }
-    /**
-   * Fetch a binary asset by ID via the asset manager.
-   *
-   * @remarks
-   * - Associates the returned data with the given ID for future reverse lookup.
-   * - The ID is typically a VFS path or locator.
-   *
-   * @param id - Asset identifier or path.
-   *
-   * @returns A Promise that resolves to the binary content, or `null` if not found.
+    /**
+   * Fetch a binary asset by ID via the asset manager.
+   *
+   * @remarks
+   * - Associates the returned data with the given ID for future reverse lookup.
+   * - The ID is typically a VFS path or locator.
+   *
+   * @param id - Asset identifier or path.
+   *
+   * @returns A Promise that resolves to the binary content, or `null` if not found.
    */ async fetchBinary(id) {
         const data = await this._assetManager.fetchBinaryData(id);
         if (data) {
@@ -545,18 +545,18 @@ const defaultValues = {
         }
         return data;
     }
-    /**
-   * Serialize an object to a JSON structure using registered class metadata.
-   *
-   * @remarks
-   * - Throws if the object's class is not registered.
-   * - Populates `asyncTasks` with pending I/O tasks for embedded resources.
-   *
-   * @param obj - The object to serialize.
-   * @param json - Optional existing JSON object to fill.
-   * @param asyncTasks - Optional list to collect async tasks for embedded asset export.
-   *
-   * @returns The serialized JSON structure.
+    /**
+   * Serialize an object to a JSON structure using registered class metadata.
+   *
+   * @remarks
+   * - Throws if the object's class is not registered.
+   * - Populates `asyncTasks` with pending I/O tasks for embedded resources.
+   *
+   * @param obj - The object to serialize.
+   * @param json - Optional existing JSON object to fill.
+   * @param asyncTasks - Optional list to collect async tasks for embedded asset export.
+   *
+   * @returns The serialized JSON structure.
    */ async serializeObject(obj, json, asyncTasks) {
         if (obj === null || obj === undefined) {
             return obj;
@@ -582,14 +582,14 @@ const defaultValues = {
         }
         return json;
     }
-    /**
-   * Serialize object properties into a JSON structure.
-   *
-   * @param obj - The target object to serialize.
-   * @param json - The JSON structure to populate.
-   * @param asyncTasks - Optional list to collect async tasks for embedded asset export.
-   * @param info - Optional serialization metadata for the object's class.
-   * @returns A Promise that resolves when serialization is complete.
+    /**
+   * Serialize object properties into a JSON structure.
+   *
+   * @param obj - The target object to serialize.
+   * @param json - The JSON structure to populate.
+   * @param asyncTasks - Optional list to collect async tasks for embedded asset export.
+   * @param info - Optional serialization metadata for the object's class.
+   * @returns A Promise that resolves when serialization is complete.
    */ async serializeObjectProps(obj, json, asyncTasks, info) {
         if (!info) {
             const cls = this.getClasses();
@@ -606,17 +606,17 @@ const defaultValues = {
         }
         return json;
     }
-    /**
-   * Deserialize a JSON structure into an object instance.
-   *
-   * @remarks
-   * - Uses the `ClassName` field to locate the registered class.
-   * - Supports custom `createFunc` and phased property loading.
-   *
-   * @param ctx - Context object passed to custom constructors/resolvers.
-   * @param json - The serialized JSON structure.
-   *
-   * @returns A Promise resolving to the reconstructed object instance, or `null` on failure.
+    /**
+   * Deserialize a JSON structure into an object instance.
+   *
+   * @remarks
+   * - Uses the `ClassName` field to locate the registered class.
+   * - Supports custom `createFunc` and phased property loading.
+   *
+   * @param ctx - Context object passed to custom constructors/resolvers.
+   * @param json - The serialized JSON structure.
+   *
+   * @returns A Promise resolving to the reconstructed object instance, or `null` on failure.
    */ async deserializeObject(ctx, json) {
         const cls = this.getClasses();
         const className = json['ClassName'];
@@ -649,12 +649,12 @@ const defaultValues = {
         }
         return obj;
     }
-    /**
-   * Deserialize object properties from JSON into an existing object instance.
-   *
-   * @param obj - The target object to populate.
-   * @param json - The JSON structure containing serialized properties.
-   * @param info - Optional serialization metadata for the object's class.
+    /**
+   * Deserialize object properties from JSON into an existing object instance.
+   *
+   * @param obj - The target object to populate.
+   * @param json - The JSON structure containing serialized properties.
+   * @param info - Optional serialization metadata for the object's class.
    */ async deserializeObjectProps(obj, json, info) {
         if (!info) {
             const cls = this.getClasses();
@@ -669,14 +669,14 @@ const defaultValues = {
             info = this.getClassByConstructor(info.parent);
         }
     }
-    /**
-   * Load a model by ID and track the allocation for reverse lookup.
-   *
-   * @param id - Model identifier or path.
-   * @param scene - Scene into which the model is loaded.
-   * @param options - Optional model fetch options.
-   *
-   * @returns A Promise resolving to the loaded model object, or `null` if failed.
+    /**
+   * Load a model by ID and track the allocation for reverse lookup.
+   *
+   * @param id - Model identifier or path.
+   * @param scene - Scene into which the model is loaded.
+   * @param options - Optional model fetch options.
+   *
+   * @returns A Promise resolving to the loaded model object, or `null` if failed.
    */ async fetchModel(id, scene, options) {
         const model = await this._assetManager.fetchModel(scene, id, options);
         if (model) {
@@ -684,29 +684,29 @@ const defaultValues = {
         }
         return model;
     }
-    /**
-   * Load a texture directly from an ArrayBuffer or typed array.
-   *
-   * - Chooses an appropriate loader based on the provided MIME type.
-   * - Can upload into an existing texture if `texture` is specified.
-   *
-   * @typeParam T - Expected concrete texture type.
-   * @param arrayBuffer - Raw texture data buffer.
-   * @param mimeType - MIME type of the texture (must be supported by a registered loader).
-   * @param srgb - If true, treat image as sRGB; otherwise linear.
-   * @param samplerOptions - Optional sampler options passed to the loader path.
-   * @param texture - Optional destination texture to populate.
-   * @returns A promise that resolves to the created or populated texture.
+    /**
+   * Load a texture directly from an ArrayBuffer or typed array.
+   *
+   * - Chooses an appropriate loader based on the provided MIME type.
+   * - Can upload into an existing texture if `texture` is specified.
+   *
+   * @typeParam T - Expected concrete texture type.
+   * @param arrayBuffer - Raw texture data buffer.
+   * @param mimeType - MIME type of the texture (must be supported by a registered loader).
+   * @param srgb - If true, treat image as sRGB; otherwise linear.
+   * @param samplerOptions - Optional sampler options passed to the loader path.
+   * @param texture - Optional destination texture to populate.
+   * @returns A promise that resolves to the created or populated texture.
    */ async loadTextureFromBuffer(arrayBuffer, mimeType, srgb, samplerOptions, texture) {
         return this._assetManager.loadTextureFromBuffer(arrayBuffer, mimeType, srgb, samplerOptions, texture);
     }
-    /**
-   * Load a texture by ID and track the allocation for reverse lookup.
-   *
-   * @param id - Texture identifier or path.
-   * @param options - Optional texture fetch options.
-   *
-   * @returns A Promise resolving to the loaded texture, or `null` if failed.
+    /**
+   * Load a texture by ID and track the allocation for reverse lookup.
+   *
+   * @param id - Texture identifier or path.
+   * @param options - Optional texture fetch options.
+   *
+   * @returns A Promise resolving to the loaded texture, or `null` if failed.
    */ async fetchTexture(id, options) {
         const texture = await this._assetManager.fetchTexture(id, options);
         if (texture) {
@@ -714,12 +714,12 @@ const defaultValues = {
         }
         return texture;
     }
-    /**
-   * Load a material by ID and track the allocation for reverse lookup.
-   *
-   * @param id - Material identifier or path.
-   *
-   * @returns A Promise resolving to the loaded material, or `null` if failed.
+    /**
+   * Load a material by ID and track the allocation for reverse lookup.
+   *
+   * @param id - Material identifier or path.
+   *
+   * @returns A Promise resolving to the loaded material, or `null` if failed.
    */ async fetchMaterial(id) {
         const material = await this._assetManager.fetchMaterial(id);
         if (material) {
@@ -727,26 +727,26 @@ const defaultValues = {
         }
         return material;
     }
-    /**
-   * Reload specific blue print materials
-   *
-   * @param filter - Determine whether a blue print material should reload.
-   *
+    /**
+   * Reload specific blue print materials
+   *
+   * @param filter - Determine whether a blue print material should reload.
+   *
    */ async reloadBluePrintMaterials(filter) {
         await this._assetManager.reloadBluePrintMaterials(filter);
     }
-    /**
-   * Mark specific blue print as changed
-   * @param path - BluePrint file path
+    /**
+   * Mark specific blue print as changed
+   * @param path - BluePrint file path
    */ invalidateBluePrint(path) {
         this._assetManager.invalidateBluePrint(path);
     }
-    /**
-   * Load a primitive by ID and track the allocation for reverse lookup.
-   *
-   * @param id - Primitive identifier or path.
-   *
-   * @returns A Promise resolving to the loaded primitive, or `null` if failed.
+    /**
+   * Load a primitive by ID and track the allocation for reverse lookup.
+   *
+   * @param id - Primitive identifier or path.
+   *
+   * @returns A Promise resolving to the loaded primitive, or `null` if failed.
    */ async fetchPrimitive(id) {
         const primitive = await this._assetManager.fetchPrimitive(id);
         if (primitive) {
@@ -754,10 +754,10 @@ const defaultValues = {
         }
         return primitive;
     }
-    /**
-   * Load a prefab content.
-   * @param path - Path to the prefab JSON file in VFS.
-   * @returns A Promise resolving to the prefab json object, or `null` on failure.
+    /**
+   * Load a prefab content.
+   * @param path - Path to the prefab JSON file in VFS.
+   * @returns A Promise resolving to the prefab json object, or `null` on failure.
    */ async loadPrefabContent(path) {
         try {
             const content = await this._vfs.readFile(path, {
@@ -770,11 +770,11 @@ const defaultValues = {
             return null;
         }
     }
-    /**
-   * Instantiate a prefab from a JSON file via VFS.
-   * @param parent - Parent node to attach the instantiated prefab to.
-   * @param path - Path to the prefab JSON file in VFS.
-   * @returns A Promise resolving to the instantiated `SceneNode`, or `null` on failure.
+    /**
+   * Instantiate a prefab from a JSON file via VFS.
+   * @param parent - Parent node to attach the instantiated prefab to.
+   * @param path - Path to the prefab JSON file in VFS.
+   * @returns A Promise resolving to the instantiated `SceneNode`, or `null` on failure.
    */ async instantiatePrefab(parent, path) {
         try {
             const json = await this.loadPrefabContent(path);
@@ -793,16 +793,16 @@ const defaultValues = {
             return null;
         }
     }
-    /**
-   * Load a scene from a JSON file via VFS.
-   *
-   * @remarks
-   * - Deserializes the scene graph.
-   * - Attaches scripts referenced by nodes after load (asynchronous).
-   *
-   * @param filename - Path to the scene JSON file in VFS.
-   *
-   * @returns A Promise resolving to the loaded `Scene`.
+    /**
+   * Load a scene from a JSON file via VFS.
+   *
+   * @remarks
+   * - Deserializes the scene graph.
+   * - Attaches scripts referenced by nodes after load (asynchronous).
+   *
+   * @param filename - Path to the scene JSON file in VFS.
+   *
+   * @returns A Promise resolving to the loaded `Scene`.
    */ async loadScene(filename) {
         const content = await this._vfs.readFile(filename, {
             encoding: 'utf8'
@@ -810,15 +810,15 @@ const defaultValues = {
         const json = JSON.parse(content);
         return await this.deserializeObject(null, json);
     }
-    /**
-   * Save a scene to a JSON file via VFS.
-   *
-   * @remarks
-   * - Collects async export tasks for embedded resources and awaits them.
-   * - Writes a UTF-8 JSON representation to VFS.
-   *
-   * @param scene - Scene to serialize and save.
-   * @param filename - Destination path in VFS.
+    /**
+   * Save a scene to a JSON file via VFS.
+   *
+   * @remarks
+   * - Collects async export tasks for embedded resources and awaits them.
+   * - Writes a UTF-8 JSON representation to VFS.
+   *
+   * @param scene - Scene to serialize and save.
+   * @param filename - Destination path in VFS.
    */ async saveScene(scene, filename) {
         const asyncTasks = [];
         const content = await this.serializeObject(scene, null, asyncTasks);
@@ -950,11 +950,11 @@ const defaultValues = {
     async loadBluePrint(path) {
         return this._assetManager.loadBluePrint(path);
     }
-    /**
-   * Clear cached allocations and asset-manager caches.
-   *
-   * @remarks
-   * Useful when reloading content or changing VFS mounts.
+    /**
+   * Clear cached allocations and asset-manager caches.
+   *
+   * @remarks
+   * Useful when reloading content or changing VFS mounts.
    */ clearCache() {
         this._allocated = new WeakMap();
         this._assetManager.clearCache();
@@ -973,18 +973,18 @@ const defaultValues = {
         }
         return null;
     }
-    /**
-   * Find the object targeted by an animation track starting from a node.
-   *
-   * @remarks
-   * - Parses a target path like `prop/subprop[0]/child` where indexed entries
-   *   require `object_array` type and non-indexed entries require `object` type.
-   * - Returns `null` if any segment cannot be resolved through registered metadata.
-   *
-   * @param node - Root node used as the starting point.
-   * @param track - Property track containing a target path.
-   *
-   * @returns The resolved target object, or `null` if not found.
+    /**
+   * Find the object targeted by an animation track starting from a node.
+   *
+   * @remarks
+   * - Parses a target path like `prop/subprop[0]/child` where indexed entries
+   *   require `object_array` type and non-indexed entries require `object` type.
+   * - Returns `null` if any segment cannot be resolved through registered metadata.
+   *
+   * @param node - Root node used as the starting point.
+   * @param track - Property track containing a target path.
+   *
+   * @returns The resolved target object, or `null` if not found.
    */ findAnimationTarget(node, track) {
         const target = track.target ?? '';
         const value = {