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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preference-sl/pref-viewer",
-  "version": "2.10.0",
+  "version": "2.11.0-beta.0",
   "description": "Web Component to preview GLTF models with Babylon.js",
   "author": "Alex Moreno Palacio <amoreno@preference.es>",
   "scripts": {
@@ -37,7 +37,8 @@
     "@babylonjs/core": "^8.31.3",
     "@babylonjs/loaders": "^8.31.3",
     "@babylonjs/serializers": "^8.31.3",
-    "babylonjs-gltf2interface": "^8.31.3"
+    "babylonjs-gltf2interface": "^8.31.3",
+    "idb": "^8.0.3"
   },
   "devDependencies": {
     "esbuild": "^0.25.10",

package/src/file-storage.js

@@ -0,0 +1,288 @@
+/**
+ * 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";
+
+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
+    #db = undefined; // IndexedDB database handle
+
+    constructor(dbName = "FilesDB", osName = "FilesObjectStore") {
+        this.dbName = dbName; // database name
+        this.osName = osName; // object store name used for file cache
+    }
+
+    /**
+     * Create the object store if it does not exist.
+     * @param {IDBDatabase} db IndexedDB database instance
+     */
+    #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.
+     * @returns {Promise<IDBDatabase|null>} Resolves with the opened database or null if IndexedDB is not supported or opening fails.
+     */
+    #openDB = async () => {
+        if (!this.#supported) {
+            return null;
+        }
+        const self = this;
+        try {
+            return await openDB(this.dbName, this.#dbVersion, {
+                upgrade(db) {
+                    self.#createObjectStore(db, self.osName);
+                },
+            });
+        } catch (error) {
+            return null;
+        }
+    };
+
+    /**
+     * Download the file from the server (forced download).
+     * @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) => {
+        let file = undefined;
+        return new Promise((resolve) => {
+            const xhr = new XMLHttpRequest();
+            xhr.open("GET", uri, true);
+            xhr.responseType = "blob";
+            xhr.onload = () => {
+                if (xhr.status === 200) {
+                    const blob = xhr.response;
+                    const timeStamp = new Date(xhr.getResponseHeader("Last-Modified")).toISOString();
+                    file = { blob: blob, timeStamp: timeStamp };
+                    resolve(file);
+                } else {
+                    resolve(file);
+                }
+            };
+            xhr.onerror = () => {
+                resolve(file);
+            };
+            xhr.send();
+        });
+    };
+
+    /**
+     * Get the Last-Modified timestamp of the file on the server without downloading its content.
+     * @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) => {
+        let timeStamp = null;
+        return new Promise((resolve) => {
+            const xhr = new XMLHttpRequest();
+            xhr.open("HEAD", uri, true);
+            xhr.responseType = "blob";
+            xhr.onload = () => {
+                if (xhr.status === 200) {
+                    timeStamp = new Date(xhr.getResponseHeader("Last-Modified")).toISOString();
+                    resolve(timeStamp);
+                } else {
+                    resolve(timeStamp);
+                }
+            };
+            xhr.onerror = () => {
+                resolve(timeStamp);
+            };
+            xhr.send();
+        });
+    };
+
+    /**
+     * Get the size of the file on the server without downloading its content.
+     * @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) => {
+        let size = 0;
+        return new Promise((resolve) => {
+            const xhr = new XMLHttpRequest();
+            xhr.open("HEAD", uri, true);
+            xhr.responseType = "blob";
+            xhr.onload = () => {
+                if (xhr.status === 200) {
+                    size = parseInt(xhr.getResponseHeader("Content-Length"));
+                    resolve(size);
+                } else {
+                    resolve(size);
+                }
+            };
+            xhr.onerror = () => {
+                resolve(size);
+            };
+            xhr.send();
+        });
+    };
+
+    /**
+     * Stores a file record in IndexedDB under the provided key (uri).
+     * @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)
+     *   - resolves to the put result on success
+     *   - resolves to undefined if the database could not be opened
+     *   - rejects if the underlying put operation throws
+     */
+    #putFile = async (file, uri) => {
+        if (this.#db === undefined) {
+            this.#db = await this.#openDB();
+        }
+        if (this.#db === null) {
+            return undefined;
+        }
+        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.
+     * @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) => {
+        if (this.#db === undefined) {
+            this.#db = await this.#openDB();
+        }
+        if (this.#db === null) {
+            return false;
+        }
+        const transation = this.#db.transaction(this.osName, "readonly");
+        const store = transation.objectStore(this.osName);
+        return store.get(uri);
+    };
+
+    /**
+     * 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
+     * @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) => {
+        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
+     * @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) => {
+        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
+     * @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) => {
+        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
+     * @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) => {
+        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
+     * @returns {Promise<Blob|undefined|false>} Resolves with:
+     *   - Blob of the stored file
+     *   - undefined if the download fails
+     *   - false if uri is falsy
+     * @description
+     * The method controls the cache version of the file. If the server copy has a different timestamp than the stored one,
+     * 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) => {
+        if (!uri) {
+            return false;
+        }
+        if (!this.#supported) {
+            return await this.#getServerFile(uri);
+        }
+        let storedFile = await this.#getFile(uri);
+        const serverFileTimeStamp = storedFile ? await this.#getServerFileTimeStamp(uri) : 0;
+        const storedFileTimeStamp = storedFile ? storedFile.timeStamp : 0;
+        if (!storedFile || (storedFile && serverFileTimeStamp !== null && serverFileTimeStamp !== storedFileTimeStamp)) {
+            const fileToStore = await this.#getServerFile(uri);
+            if (fileToStore && !!(await this.#putFile(fileToStore, uri))) {
+                storedFile = await this.#getFile(uri);
+            } else {
+                storedFile = fileToStore;
+            }
+        }
+        return storedFile;
+    };
+
+    /**
+     * Store the file in IndexedDB.
+     * @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) => {
+        if (!this.#supported) {
+            return false;
+        }
+        const fileToStore = await this.#getServerFile(uri);
+        return fileToStore ? !!(await this.#putFile(fileToStore, uri)) : false;
+    };
+}

package/src/index.js

@@ -45,6 +45,7 @@ import { USDZExportAsync, GLTF2Export } from "@babylonjs/serializers";
 import "@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression";
 import { DracoCompression } from "@babylonjs/core/Meshes/Compression/dracoCompression";
 import { initDb, loadModel } from "./gltf-storage.js";
+import { FileStorage } from "./file-storage.js";
 
 class PrefViewerTask {
     static Types = Object.freeze({
@@ -65,9 +66,7 @@ class PrefViewerTask {
         const t = typeof type === "string" ? type.toLowerCase() : String(type).toLowerCase();
         const allowed = Object.values(PrefViewerTask.Types);
         if (!allowed.includes(t)) {
-            throw new TypeError(
-                `PrefViewerTask: invalid type "${type}". Allowed types: ${allowed.join(", ")}`
-            );
+            throw new TypeError(`PrefViewerTask: invalid type "${type}". Allowed types: ${allowed.join(", ")}`);
         }
         this.type = t;
 
@@ -80,6 +79,7 @@ class PrefViewer extends HTMLElement {
     loaded = false;
     loading = false;
     #taskQueue = [];
+    #fileStorage = new FileStorage("PrefViewer", "Files");
 
     #data = {
         containers: {
@@ -306,7 +306,7 @@ class PrefViewer extends HTMLElement {
             tried: toLoadDetail,
             success: loadedDetail,
         };
-        
+
         this.dispatchEvent(
             new CustomEvent("scene-loaded", {
                 bubbles: true,
@@ -318,7 +318,7 @@ class PrefViewer extends HTMLElement {
 
         await this.#scene.whenReadyAsync();
         this.#engine.runRenderLoop(this.#renderLoop);
-        
+
         this.#resetChangedFlags();
 
         if (this.hasAttribute("loading")) {
@@ -803,6 +803,94 @@ class PrefViewer extends HTMLElement {
         return true;
     }
 
+    /**
+     * Replace internal URIs in a glTF AssetContainer JSON with URLs pointing to files stored in IndexedDB.
+     * @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 = [];
+
+        /**
+         * Check whether a value is a syntactically absolute URL.
+         * @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.
+         */
+        var isURLAbsolute = function (url) {
+            if (typeof url !== "string") {
+                return false;
+            }
+            try {
+                new URL(url);
+                return true;
+            } catch {
+                return false;
+            }
+        };
+
+        /**
+         * Collect asset entries that have an external URI (non-data URI) and store a normalized absolute/relative-resolved URI for later replacement.
+         * @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}  array Reference to the parent array (buffers or images).
+         * @returns {void} Side-effect: pushes a record into arrayOfAssetsWithURI when applicable { parent: <array>, index: <number>, uri: <string> }.
+         */
+        var saveAssetData = function (asset, index, array) {
+            if (asset.uri && !asset.uri.startsWith("data:")) {
+                const assetData = {
+                    parent: array,
+                    index: index,
+                    uri: `${!isURLAbsolute(asset.uri) && sceneURLBase ? sceneURLBase : ""}${asset.uri}`.replace(/\\\\|\\|\/\\/g, "/"),
+                };
+                arrayOfAssetsWithURI.push(assetData);
+            }
+        };
+
+        if (assetContainerJSON.buffers) {
+            assetContainerJSON.buffers.forEach((asset, index, array) => saveAssetData(asset, index, array));
+        }
+        if (assetContainerJSON.images) {
+            assetContainerJSON.images.forEach((asset, index, array) => saveAssetData(asset, index, array));
+        }
+
+        // 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);
+    }
+
     async #loadAssetContainer(container) {
         let storage = container?.storage;
 
@@ -832,9 +920,15 @@ class PrefViewer extends HTMLElement {
 
         let { blob, extension, size } = this.#decodeBase64(source);
         if (blob && extension) {
-            file = new File([blob], `${container.name}${extension}`, {
-                type: blob.type,
-            });
+            if ((container.name === "model" || container.name === "materials") && extension === ".gltf") {
+                const assetContainerJSON = JSON.parse(await blob.text());
+                await this.#replaceSceneURIAsync(assetContainerJSON, source);
+                source = `data:${JSON.stringify(assetContainerJSON)}`;
+            } else {
+                file = new File([blob], `${container.name}${extension}`, {
+                    type: blob.type,
+                });
+            }
             if (!container.changed.pending) {
                 if (container.timeStamp === null && container.size === size) {
                     container.changed = { pending: false, success: false };
@@ -846,12 +940,20 @@ class PrefViewer extends HTMLElement {
         } else {
             const extMatch = source.match(/\.(gltf|glb)(\?|#|$)/i);
             extension = extMatch ? `.${extMatch[1].toLowerCase()}` : ".gltf";
-            const [fileSize, fileTimeStamp] = await this.#getServerFileDataHeader(source);
+            let [fileSize, fileTimeStamp] = [await this.#fileStorage.getSize(source), await this.#fileStorage.getTimeStamp(source)];
             if (container.size === fileSize && container.timeStamp === fileTimeStamp) {
                 container.changed = { pending: false, success: false };
                 return false;
             } else {
                 container.changed = { pending: true, size: fileSize, success: false, timeStamp: 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);
+                }
             }
         }
 
@@ -863,7 +965,7 @@ class PrefViewer extends HTMLElement {
                     compileMaterials: true,
                     loadAllMaterials: true,
                     loadOnlyMaterials: container.name === "materials",
-                    preprocessUrlAsync: this.#transformUrl,
+                    //preprocessUrlAsync: this.#transformUrl,
                 },
             },
         };
@@ -1050,7 +1152,7 @@ class PrefViewer extends HTMLElement {
         if (this.#checkMaterialsChanged(options)) {
             someSetted = someSetted || this.#setOptionsMaterials();
         }
-        
+
         await this.#setStatusLoaded();
 
         return someSetted;