@preference-sl/pref-viewer 2.11.0-beta.0 → 2.11.0-beta.2

package/src/file-storage.js

@@ -1,12 +1,119 @@
-/**
- * FileStore class to manage file storage in IndexedDB using a promise-based wrapper around the IndexedDB API.
- * @see {@link https://github.com/jakearchibald/idb|GitHub - jakearchibald/idb: IndexedDB, but with promises}
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API|IndexedDB API - MDN}
- * @see {@link https://www.npmjs.com/package/idb|idb - npm}
- */
-
 import { openDB } from "idb";
 
+/**
+ * FileStorage - Class for managing file storage in IndexedDB with server synchronization.
+ *
+ * Overview:
+ *  - Provides a promise-based wrapper around the IndexedDB API for file caching.
+ *  - Automatically manages cache versioning by comparing server and cached file timestamps.
+ *  - Falls back to direct server access when IndexedDB is unavailable.
+ *  - Supports file blob retrieval, timestamp checking, and size queries.
+ *  - Uses the idb library for simplified IndexedDB operations.
+ *
+ * Dependencies:
+ *  - idb (IndexedDB wrapper library)
+ *  - Modern browser with IndexedDB support
+ *
+ * Constructor:
+ *  - FileStorage(dbName, osName): Creates a new FileStorage instance.
+ *    Parameters:
+ *      - dbName: Name of the IndexedDB database (default: "FilesDB")
+ *      - osName: Name of the object store (default: "FilesObjectStore")
+ *
+ * Private Methods:
+ *  - #createObjectStore(db, osName): Creates the object store if it doesn't exist.
+ *  - #openDB(): Opens or creates the IndexedDB database.
+ *  - #getServerFile(uri): Downloads file blob and timestamp from server.
+ *  - #getServerFileTimeStamp(uri): Retrieves Last-Modified timestamp via HEAD request.
+ *  - #getServerFileSize(uri): Retrieves Content-Length via HEAD request.
+ *  - #putFile(file, uri): Stores file record in IndexedDB.
+ *  - #getFile(uri): Retrieves file record from IndexedDB.
+ *
+ * Public Methods:
+ *  - getURL(uri): Gets an object URL for cached blob or original URI.
+ *  - getTimeStamp(uri): Retrieves cached or server Last-Modified timestamp.
+ *  - getSize(uri): Gets cached or server file size in bytes.
+ *  - getBlob(uri): Retrieves file blob from cache or server.
+ *  - get(uri): Gets file from cache with automatic server sync and cache versioning.
+ *  - put(uri): Stores file from server in IndexedDB cache.
+ *
+ * Features:
+ *  - Automatic Cache Versioning: Compares server and cached timestamps to update cache.
+ *  - Fallback Support: Uses direct server access when IndexedDB is unavailable.
+ *  - Object URL Generation: Creates efficient object URLs for cached blobs.
+ *  - HEAD Request Optimization: Uses HEAD requests to check metadata without downloading full files.
+ *  - Promise-Based API: All operations return promises for async/await usage.
+ *
+ * Usage Example:
+ *  const storage = new FileStorage("MyFilesDB", "CachedFiles");
+ *  
+ *  // Get file blob with automatic caching
+ *  const file = await storage.get("https://example.com/model.glb");
+ *  
+ *  // Get object URL for cached file
+ *  const url = await storage.getURL("https://example.com/model.glb");
+ *  
+ *  // Check file timestamp
+ *  const timestamp = await storage.getTimeStamp("https://example.com/model.glb");
+ *  
+ *  // Get file size
+ *  const size = await storage.getSize("https://example.com/model.glb");
+ *  
+ *  // Manually cache a file
+ *  await storage.put("https://example.com/model.glb");
+ *
+ * Cache Behavior:
+ *  - First call: Downloads from server and caches in IndexedDB
+ *  - Subsequent calls: Returns cached version if timestamp matches
+ *  - Updated file: Detects timestamp change and re-downloads automatically
+ *  - No server access: Returns cached version if available
+ *  - IndexedDB unavailable: Falls back to direct server access
+ *
+ * Return Values:
+ *  - get(uri): Blob | undefined | false
+ *    - Blob: File successfully retrieved
+ *    - undefined: Download failed but no cached copy exists
+ *    - false: URI is falsy
+ *  
+ *  - getURL(uri): string | boolean
+ *    - string: Object URL or original URI
+ *    - false: File not available
+ *  
+ *  - getTimeStamp(uri): string | null
+ *    - string: ISO 8601 timestamp
+ *    - null: Timestamp unavailable
+ *  
+ *  - getSize(uri): number | null
+ *    - number: File size in bytes
+ *    - null: Size unavailable
+ *  
+ *  - put(uri): boolean
+ *    - true: Successfully cached
+ *    - false: Failed to cache
+ *
+ * Storage Limits:
+ *  - Chrome/Edge: ~50GB per origin
+ *  - Firefox: ~1GB per origin
+ *  - Safari: ~1GB per origin
+ *
+ * Notes:
+ *  - Requires CORS headers for cross-origin file access
+ *  - Uses XMLHttpRequest for file downloads and HEAD requests
+ *  - Supports both HTTPS and HTTP (HTTP not recommended for production)
+ *  - Object URLs should be revoked after use to free memory
+ *  - IndexedDB quota management should be implemented for long-term storage
+ *
+ * Error Handling:
+ *  - Network failures: Returns undefined (get) or false (other methods)
+ *  - IndexedDB errors: Falls back to server access or returns false
+ *  - CORS errors: Treated as download failures
+ *  - Invalid URIs: Returns false or undefined
+ *
+ * References:
+ *  - MDN IndexedDB API: https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API
+ *  - idb Library: https://github.com/jakearchibald/idb
+ *  - npm idb: https://www.npmjs.com/package/idb
+ */
 export class FileStorage {
     #supported = "indexedDB" in window && openDB; // true if IndexedDB is available in the browser and the idb helper is loaded
     #dbVersion = 1; // single DB version; cache is managed per-file
@@ -19,19 +126,22 @@ export class FileStorage {
 
     /**
      * Create the object store if it does not exist.
+     * @private
      * @param {IDBDatabase} db IndexedDB database instance
+     * @param {String} osName Object store name
      */
-    #createObjectStore = (db, osName) => {
+    #createObjectStore(db, osName) {
         if (!db.objectStoreNames.contains(osName)) {
             db.createObjectStore(osName);
         }
-    };
+    }
 
     /**
      * Open the IndexedDB database (creating it if needed) and ensure the object store for files exists.
+     * @private
      * @returns {Promise<IDBDatabase|null>} Resolves with the opened database or null if IndexedDB is not supported or opening fails.
      */
-    #openDB = async () => {
+    async #openDB() {
         if (!this.#supported) {
             return null;
         }
@@ -45,16 +155,17 @@ export class FileStorage {
         } catch (error) {
             return null;
         }
-    };
+    }
 
     /**
      * Download the file from the server (forced download).
+     * @private
      * @param {String} uri File URI
      * @returns {Promise<{blob: Blob, timeStamp: string}|undefined>} Resolves with:
      *   - { blob, timeStamp }: object with the downloaded Blob and the Last-Modified timestamp (ISO string) on success
      *   - undefined: if the download fails (non-200 status or network error)
      */
-    #getServerFile = async (uri) => {
+    async #getServerFile(uri) {
         let file = undefined;
         return new Promise((resolve) => {
             const xhr = new XMLHttpRequest();
@@ -75,16 +186,17 @@ export class FileStorage {
             };
             xhr.send();
         });
-    };
+    }
 
     /**
      * Get the Last-Modified timestamp of the file on the server without downloading its content.
+     * @private
      * @param {String} uri File URI
      * @returns {Promise<string|null>} Resolves with:
      *   - ISO 8601 string from the Last-Modified header if available
      *   - null if the header is not present or on error
      */
-    #getServerFileTimeStamp = async (uri) => {
+    async #getServerFileTimeStamp(uri) {
         let timeStamp = null;
         return new Promise((resolve) => {
             const xhr = new XMLHttpRequest();
@@ -103,16 +215,17 @@ export class FileStorage {
             };
             xhr.send();
         });
-    };
+    }
 
     /**
      * Get the size of the file on the server without downloading its content.
+     * @private
      * @param {String} uri File URI
      * @returns {Promise<number>} Promise that resolves with:
      *   - number: Content-Length in bytes when the HEAD request succeeds and the header is present
      *   - 0: when the header is missing or the request fails
      */
-    #getServerFileSize = async (uri) => {
+    async #getServerFileSize(uri) {
         let size = 0;
         return new Promise((resolve) => {
             const xhr = new XMLHttpRequest();
@@ -131,10 +244,11 @@ export class FileStorage {
             };
             xhr.send();
         });
-    };
+    }
 
     /**
      * Stores a file record in IndexedDB under the provided key (uri).
+     * @private
      * @param {Object|Blob} file The value to store (for example an object {blob, timeStamp} or a Blob).
      * @param {String} uri Key to use for storage (the original URI).
      * @returns {Promise<any|undefined>} Resolves with the value returned by the underlying idb store.put (usually the record key — string or number)
@@ -142,7 +256,7 @@ export class FileStorage {
      *   - resolves to undefined if the database could not be opened
      *   - rejects if the underlying put operation throws
      */
-    #putFile = async (file, uri) => {
+    async #putFile(file, uri) {
         if (this.#db === undefined) {
             this.#db = await this.#openDB();
         }
@@ -152,17 +266,18 @@ export class FileStorage {
         const transation = this.#db.transaction(this.osName, "readwrite");
         const store = transation.objectStore(this.osName);
         return store.put(file, uri);
-    };
+    }
 
     /**
      * Retrieve a file record from IndexedDB.
+     * @private
      * @param {String} uri File URI
      * @returns {Promise<{blob: Blob, timeStamp: string}|undefined|false>} Resolves with:
      *   - {blob, timeStamp}: object with the Blob and ISO timestamp if the entry exists in IndexedDB
      *   - undefined: if there is no stored entry for that URI
      *   - false: if the database could not be opened (IndexedDB unsupported or open failure)
      */
-    #getFile = async (uri) => {
+    async #getFile(uri) {
         if (this.#db === undefined) {
             this.#db = await this.#openDB();
         }
@@ -172,75 +287,86 @@ export class FileStorage {
         const transation = this.#db.transaction(this.osName, "readonly");
         const store = transation.objectStore(this.osName);
         return store.get(uri);
-    };
+    }
+
+    /**
+     * ---------------------------
+     * Public methods
+     * ---------------------------
+     */
 
     /**
      * Get a URL to the file: either an object URL for the cached Blob, or the original URI if the server copy is available and IndexedDB isn't supported.
-     * @param {String} uri File URI
+     * @public
+     * @param {String} uri - File URI
      * @returns {Promise<string|boolean>} Resolves with:
      *   - object URL string for the cached Blob
      *   - original URI string if IndexedDB unsupported but server file exists
      *   - false if the file is not available on the server
      */
-    getURL = async (uri) => {
+    async getURL(uri) {
         if (!this.#supported) {
             return (await this.#getServerFileTimeStamp(uri)) ? uri : false;
         }
         const storedFile = await this.get(uri);
         return storedFile ? URL.createObjectURL(storedFile.blob) : (await this.#getServerFileTimeStamp(uri)) ? uri : false;
-    };
+    }
 
     /**
      * Get the cached or server Last-Modified timestamp for a file.
-     * @param {String} uri File URI
+     * @public
+     * @param {String} uri - File URI
      * @returns {Promise<string|null>} Resolves with:
      *   - ISO 8601 string: Last-Modified timestamp from the cached record (when using IndexedDB) or from the server HEAD response
      *   - null: when no timestamp is available or on error
      */
-    getTimeStamp = async (uri) => {
+    async getTimeStamp(uri) {
         if (!this.#supported) {
             const serverFileTimeStamp = await this.#getServerFileTimeStamp(uri);
             return serverFileTimeStamp ? serverFileTimeStamp : null;
         }
         const storedFile = await this.get(uri);
         return storedFile ? storedFile.timeStamp : null;
-    };
+    }
 
     /**
      * Get the cached or server size of a file in bytes.
-     * @param {String} uri File URI
+     * @public
+     * @param {String} uri - File URI
      * @returns {Promise<number|null>} Resolves with:
      *   - number: size in bytes when available (from cache or server)
      *   - null: when size is not available or on error
      */
-    getSize = async (uri) => {
+    async getSize(uri) {
         if (!this.#supported) {
             const serverFileSize = await this.#getServerFileSize(uri);
             return serverFileSize ? serverFileSize : null;
         }
         const storedFile = await this.get(uri);
         return storedFile ? storedFile.blob.size : null;
-    };
+    }
 
     /**
      * Retrieve the Blob for a file from cache or server.
-     * @param {String} uri File URI
+     * @public
+     * @param {String} uri - File URI
      * @returns {Promise<Blob|false>} Resolves with:
      *   - Blob: the file blob when available (from cache or server)
      *   - false: when the file cannot be retrieved
      */
-    getBlob = async (uri) => {
+    async getBlob(uri) {
         if (!this.#supported) {
             const serverFile = await this.#getServerFile(uri);
             return serverFile ? serverFile.blob : false;
         }
         const storedFile = await this.get(uri);
         return storedFile ? storedFile.blob : false;
-    };
+    }
 
     /**
      * Get the file Blob from IndexedDB if stored; otherwise download and store it, then return the Blob.
-     * @param {String} uri File URI
+     * @public
+     * @param {String} uri - File URI
      * @returns {Promise<Blob|undefined|false>} Resolves with:
      *   - Blob of the stored file
      *   - undefined if the download fails
@@ -250,7 +376,7 @@ export class FileStorage {
      * the file is re-downloaded from the server and stored again in IndexedDB.
      * If the server file is not available at that time to check its age but is stored, the stored file is returned.
      */
-    get = async (uri) => {
+    async get(uri) {
         if (!uri) {
             return false;
         }
@@ -269,20 +395,21 @@ export class FileStorage {
             }
         }
         return storedFile;
-    };
+    }
 
     /**
      * Store the file in IndexedDB.
-     * @param {String} uri File URI
+     * @public
+     * @param {String} uri - File URI
      * @returns {Promise<boolean>} Resolves with:
      *   - true if the file was stored successfully
      *   - false if IndexedDB is not supported or storing failed
      */
-    put = async (uri) => {
+    async put(uri) {
         if (!this.#supported) {
             return false;
         }
         const fileToStore = await this.#getServerFile(uri);
         return fileToStore ? !!(await this.#putFile(fileToStore, uri)) : false;
-    };
+    }
 }

package/src/gltf-resolver.js

@@ -0,0 +1,288 @@
+import { FileStorage } from "./file-storage.js";
+import { initDb, loadModel } from "./gltf-storage.js";
+
+/**
+ * GLTFResolver - Utility class for resolving, decoding, and preparing glTF/GLB assets from various sources.
+ *
+ * Responsibilities:
+ *  - Loads glTF/GLB assets from IndexedDB, direct URLs, or base64-encoded data.
+ *  - Decodes base64 data and determines file type (.gltf or .glb).
+ *  - Normalizes and replaces asset URIs with resolved URLs from FileStorage.
+ *  - Handles cache validation using asset size and timestamp to avoid unnecessary reloads.
+ *  - Provides methods for initializing storage, decoding assets, and preparing sources for viewer components.
+ *
+ * Usage:
+ *  - Instantiate: const resolver = new GLTFResolver();
+ *  - Prepare asset: await resolver.getSource(storage, currentSize, currentTimeStamp);
+ *
+ * Public Methods:
+ *  - getSource(storage, currentSize, currentTimeStamp): Resolves and prepares a glTF/GLB source for loading.
+ *
+ * Private Methods:
+ *  - #initializeStorage(db, table): Ensures IndexedDB store is initialized.
+ *  - #decodeBase64(base64): Decodes base64 data and determines file type.
+ *  - #isURLAbsolute(url): Checks if a URL is syntactically absolute.
+ *  - #saveAssetData(asset, index, parent, assetArray): Collects asset entries with external URIs.
+ *  - #replaceSceneURIAsync(assetContainerJSON, assetContainerURL): Replaces internal URIs in glTF JSON with resolved URLs.
+ *
+ * Notes:
+ *  - Designed for integration with PrefViewer and FileStorage.
+ *  - Follows the glTF 2.0 specification for asset structure and URI handling.
+ *  - All asset preparation is performed asynchronously to support large files and remote sources.
+ *  - See: https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html
+ */
+export default class GLTFResolver {
+    #fileStorage = null;
+
+    /**
+     * Creates a new GLTFResolver instance and initializes the FileStorage for asset management.
+     * @public
+     * @constructor
+     * @returns {GLTFResolver}
+     * @description
+     *   - Initializes an internal FileStorage instance with the database "PrefViewer" and object store "Files".
+     *   - Prepares the resolver for loading, decoding, and managing glTF/GLB assets from various sources.
+     */
+    constructor() {
+        this.#fileStorage = new FileStorage("PrefViewer", "Files");
+    }
+
+    /**
+     * Ensure the IndexedDB object store for GLTF/SVG storage is initialized.
+     * @private
+     * @param {string} db - Database name.
+     * @param {string} table - Object store name.
+     * @returns {Promise<void>}
+     * @description
+     * If a global PrefConfigurator.db already references the requested DB and table, no action is taken. Otherwise delegates to initDb to create/open the store.
+     */
+    async #initializeStorage(db, table) {
+        if (typeof window !== "undefined" && window.PrefConfigurator.db && window.PrefConfigurator.db.name === db && window.PrefConfigurator.db.objectStoreNames.contains(table)) {
+            return;
+        }
+        await initDb(db, table);
+    }
+
+    /**
+     * Decodes a base64-encoded glTF or GLB data URI or string into a Blob and determines its extension.
+     * If the decoded content is valid JSON, assumes it is a .gltf file; otherwise, treats it as .glb binary.
+     * @private
+     * @param {string} base64 - The base64-encoded data URI or string to decode.
+     * @returns {{blob: Blob|null, extension: string|null, size: number}}
+     *   - blob: The decoded Blob object, or null if decoding fails.
+     *   - extension: ".gltf" for JSON content, ".glb" for binary, or null if decoding fails.
+     *   - size: The length of the raw base64 payload.
+     * @description
+     *   - Attempts to decode the base64 payload and parse it as JSON.
+     *   - If parsing succeeds, returns a Blob with MIME type "model/gltf+json" and extension ".gltf".
+     *   - If parsing fails, returns a Blob with MIME type "model/gltf-binary" and extension ".glb".
+     *   - If decoding fails, returns nulls for blob and extension.
+     */
+    #decodeBase64(base64) {
+        const [, payload] = base64.split(",");
+        const raw = payload || base64;
+        let decoded = "";
+        let blob = null;
+        let extension = null;
+        let size = raw.length;
+        try {
+            decoded = atob(raw);
+        } catch {
+            return { blob, extension, size };
+        }
+        let isJson = false;
+        try {
+            JSON.parse(decoded);
+            isJson = true;
+        } catch {}
+        extension = isJson ? ".gltf" : ".glb";
+        const type = isJson ? "model/gltf+json" : "model/gltf-binary";
+        const array = Uint8Array.from(decoded, (c) => c.charCodeAt(0));
+        blob = new Blob([array], { type });
+        return { blob, extension, size };
+    }
+
+    /**
+     * Check whether a value is a syntactically absolute URL.
+     * @private
+     * @param {string} url - Value to test.
+     * @returns {boolean} True when `url` is a string that can be parsed by the global URL constructor (i.e. a syntactically absolute URL); false otherwise.
+     * @description
+     *  - Returns false for non-string inputs.
+     *  - Uses the browser's URL parser, so protocol-relative URLs ("//host/...") and relative paths are considered non-absolute.
+     *  - This is a syntactic check only — it does not perform network requests or validate reachability/CORS.
+     */
+    #isURLAbsolute(url) {
+        if (typeof url !== "string") {
+            return false;
+        }
+        try {
+            new URL(url);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * Collects asset entries that have an external URI (non-data URI) and stores a normalized absolute or relative-resolved URI for later replacement.
+     * @private
+     * @param {Object} asset - glTF asset entry (an element of buffers[] or images[]).
+     * @param {number} index - Index of the asset within its parent array.
+     * @param {Array} parent - Reference to the parent array (buffers or images).
+     * @param {string} sceneURLBase - Base path used to resolve relative URIs.
+     * @param {Array} assetArray - Array to collect asset records for later URI replacement.
+     * @returns {void}
+     * @description
+     *   - Only assets with a non-data URI are collected.
+     *   - The pushed record has the shape: { parent: <array>, index: <number>, uri: <string> }.
+     *   - The URI is normalized (backslashes converted to forward slashes) and, if relative, is prefixed with sceneURLBase if available.
+     */
+    #saveAssetData(asset, index, parent, sceneURLBase, assetArray) {
+        if (asset.uri && !asset.uri.startsWith("data:")) {
+            const assetData = {
+                parent: parent,
+                index: index,
+                uri: `${!this.#isURLAbsolute(asset.uri) && sceneURLBase ? sceneURLBase : ""}${asset.uri}`.replace(/\\\\|\\|\/\\/g, "/"),
+            };
+            assetArray.push(assetData);
+        }
+    }
+
+    /**
+     * Replace internal URIs in a glTF AssetContainer JSON with URLs pointing to files stored in IndexedDB.
+     * @private
+     * @param {JSON} assetContainerJSON - AssetContainer in glTF (JSON) (modified in-place).
+     * @param {URL} [assetContainerURL] - Optional URL of the AssetContainer. Used as the base path to resolve relative URIs.
+     * @returns {Promise<void>} Resolves when all applicable URIs have been resolved/replaced.
+     * @description
+     * - When provided, assetContainerURL is used as the base path for other scene files (binary buffers and all images).
+     *   If not provided (null/undefined), it is because it is the assetContainer of the model or materials whose URIs are absolute.
+     * - According to the glTF 2.0 spec, only items inside the "buffers" and "images" arrays may have a "uri" property.
+     * - Data URIs (embedded base64) are ignored and left unchanged.
+     * - Matching asset URIs are normalized (backslashes converted to forward slashes) and passed to the FileStorage layer
+     *   to obtain a usable URL (object URL or cached URL).
+     * - The function performs replacements in parallel and waits for all lookups to complete.
+     * - The JSON is updated in-place with the resolved URLs.
+     * @see {@link https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#uris|glTF™ 2.0 Specification - URIs}
+     */
+    async #replaceSceneURIAsync(assetContainerJSON, assetContainerURL) {
+        if (!assetContainerJSON) {
+            return;
+        }
+
+        let sceneURLBase = assetContainerURL;
+
+        if (typeof assetContainerURL === "string") {
+            const lastIndexOfSlash = assetContainerURL.lastIndexOf("/");
+            if (lastIndexOfSlash !== -1) {
+                sceneURLBase = assetContainerURL.substring(0, lastIndexOfSlash + 1);
+            }
+        }
+
+        const arrayOfAssetsWithURI = [];
+        if (assetContainerJSON.buffers) {
+            assetContainerJSON.buffers.forEach((asset, index, array) => this.#saveAssetData(asset, index, array, sceneURLBase, arrayOfAssetsWithURI));
+        }
+        if (assetContainerJSON.images) {
+            assetContainerJSON.images.forEach((asset, index, array) => this.#saveAssetData(asset, index, array, sceneURLBase, arrayOfAssetsWithURI));
+        }
+
+        // Replace parallel URIs so that if files are not stored yet, they are downloaded in parallel
+        const promisesArray = arrayOfAssetsWithURI.map(async (asset) => {
+            const uri = await this.#fileStorage.getURL(asset.uri);
+            if (uri) {
+                asset.parent[asset.index].uri = uri;
+            }
+        });
+        await Promise.all(promisesArray);
+    }
+
+    /**
+     * Resolves and prepares a glTF/GLB source from various storage backends.
+     * Supports IndexedDB, direct URLs, and base64-encoded data.
+     * Handles cache validation using asset size and timestamp, and updates URIs for .gltf files as needed.
+     * @public
+     * @param {object} storage - Storage descriptor containing url, db, table, and id properties.
+     * @param {number|null} currentSize - The current cached size of the asset, or null if not cached.
+     * @param {string|null} currentTimeStamp - The current cached timestamp of the asset, or null if not cached.
+     * @returns {Promise<false|{source: File|string, size: number, timeStamp: string|null, extension: string}>}
+     *   - Resolves to false if no update is needed or on error.
+     *   - Resolves to an object containing the resolved source (File or data URI), size, timestamp, and extension if an update is required.
+     * @description
+     *   - If storage specifies IndexedDB (db, table, id), loads the asset from IndexedDB and checks for updates.
+     *   - If storage specifies a direct URL or base64 data, decodes and validates the asset.
+     *   - For .gltf files, replaces internal URIs with resolved URLs from FileStorage.
+     *   - Performs cache validation using size and timestamp to avoid unnecessary reloads.
+     *   - Returns the prepared source, size, timestamp, and extension for further processing.
+     */
+    async getSource(storage, currentSize, currentTimeStamp) {
+        let source = storage.url || null;
+        let newSize, newTimeStamp;
+        let pending = false;
+
+        if (storage.db && storage.table && storage.id) {
+            await this.#initializeStorage(storage.db, storage.table);
+            const object = await loadModel(storage.id, storage.table);
+            if (!object || !object.data || !object.timeStamp || !object.size) {
+                return false;
+            }
+            source = object.data;
+            if (object.timeStamp === currentTimeStamp) {
+                return false;
+            } else {
+                pending = true;
+                newSize = object.size;
+                newTimeStamp = object.timeStamp;
+            }
+        }
+
+        if (!source) {
+            return false;
+        }
+
+        let file = null;
+        let { blob, extension, size } = this.#decodeBase64(source);
+
+        if (blob && extension) {
+            if (extension === ".gltf") {
+                const assetContainerJSON = JSON.parse(await blob.text());
+                await this.#replaceSceneURIAsync(assetContainerJSON, source);
+                source = `data:${JSON.stringify(assetContainerJSON)}`;
+            } else {
+                file = new File([blob], `file${extension}`, {
+                    type: blob.type,
+                });
+            }
+            if (!pending) {
+                if (currentTimeStamp === null && currentSize === size) {
+                    return false;
+                } else {
+                    pending = true;
+                    newSize = size;
+                    newTimeStamp = null;
+                }
+            }
+        } else {
+            const extMatch = source.match(/\.(gltf|glb)(\?|#|$)/i);
+            extension = extMatch ? `.${extMatch[1].toLowerCase()}` : ".gltf";
+            let [fileSize, fileTimeStamp] = [await this.#fileStorage.getSize(source), await this.#fileStorage.getTimeStamp(source)];
+            if (currentSize === fileSize && currentTimeStamp === fileTimeStamp) {
+                return false;
+            } else {
+                pending = true;
+                newSize = fileSize;
+                newTimeStamp = fileTimeStamp;
+                if (extension === ".gltf") {
+                    const assetContainerBlob = await this.#fileStorage.getBlob(source);
+                    const assetContainerJSON = JSON.parse(await assetContainerBlob.text());
+                    await this.#replaceSceneURIAsync(assetContainerJSON, source);
+                    source = `data:${JSON.stringify(assetContainerJSON)}`;
+                } else {
+                    source = await this.#fileStorage.getURL(source);
+                }
+            }
+        }
+        return { source: file || source, size: newSize, timeStamp: newTimeStamp, extension: extension };
+    }
+}