@preference-sl/pref-viewer 2.13.0-beta.6 → 2.13.0-beta.7

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "2.13.0-beta.6",
+    "version": "2.13.0-beta.7",
     "description": "Web Component to preview GLTF models with Babylon.js",
     "author": "Alex Moreno Palacio <amoreno@preference.es>",
     "scripts": {

package/src/babylonjs-controller.js

@@ -56,6 +56,9 @@ import { translate } from "./localization/i18n.js";
  *  - `show-model`/`show-scene` DOM attributes reflect container visibility; there are no direct `showModel()/hideModel()` APIs.
  *  - IBL shadows require `iblEnabled` plus `options.ibl.shadows` and a loaded HDR texture; otherwise fallback directional
  *    lights and environment-contributed lights supply classic shadow generators.
+ *  - IBL lifecycle: when `options.ibl.cachedUrl` is present, a new `HDRCubeTexture` is created and cloned into `#hdrTexture`;
+ *    then `options.ibl.consumeCachedUrl(true)` clears/revokes the temporary URL. Subsequent reloads reuse `#hdrTexture.clone()`
+ *    while `options.ibl.valid` remains true.
  *  - Browser-only features guard `window`, localStorage, and XR APIs before use so the controller is safe to construct
  *    in SSR/Node contexts (though functionality activates only in browsers).
  */
@@ -90,6 +93,7 @@ export default class BabylonJSController {
     #shadowGen = [];
     #XRExperience = null;
     #canvasResizeObserver = null;
+    #hdrTexture = null; // reusable in-memory HDR source cloned into scene.environmentTexture across reloads
     
     #containers = {};
     #options = {};
@@ -376,6 +380,10 @@ export default class BabylonJSController {
      * Sets light intensities and shadow properties for realistic rendering.
      * @private
      * @returns {Promise<boolean>} Returns true if lights were changed, false otherwise.
+     * @description
+     * IBL path is considered available when either:
+     *  - `options.ibl.cachedUrl` is present (new pending URL), or
+     *  - `options.ibl.valid === true` (reusable in-memory `#hdrTexture` exists).
      */
     async #createLights() {
         const hemiLightName = "PrefViewerHemiLight";
@@ -388,7 +396,7 @@ export default class BabylonJSController {
 
         let lightsChanged = false;
 
-        const iblEnabled = this.#settings.iblEnabled && this.#options.ibl?.cachedUrl !== null;
+        const iblEnabled = this.#settings.iblEnabled && (this.#options.ibl?.valid === true || !!this.#options.ibl?.cachedUrl);
 
         if (iblEnabled) {
             if (hemiLight) {
@@ -409,6 +417,10 @@ export default class BabylonJSController {
                 this.#scene.environmentTexture = null;
                 lightsChanged = true;
             }
+            if (this.#hdrTexture) {
+                this.#hdrTexture.dispose();
+                this.#hdrTexture = null;
+            }
 
             // Add a hemispheric light for basic ambient illumination
             if (!this.#hemiLight) {
@@ -647,19 +659,43 @@ export default class BabylonJSController {
 
     /**
      * Initializes the environment texture for the Babylon.js scene.
-     * Loads an HDR texture from a predefined URI and assigns it to the scene's environmentTexture property.
-     * Configures gamma space, mipmaps, and intensity level for realistic lighting.
+     * Resolves the active HDR environment texture using either a fresh `cachedUrl`
+     * or the reusable in-memory clone (`#hdrTexture`), then assigns it to `scene.environmentTexture`.
      * @private
      * @returns {Promise<boolean>} Returns true if the environment texture was changed, false if it was already up to date or failed to load.
+     * @description
+     * Lifecycle implemented here:
+     * 1. If `options.ibl.cachedUrl` exists, create `HDRCubeTexture` from it.
+     * 2. Wait for readiness, clone it into `#hdrTexture` for reuse.
+     * 3. Call `options.ibl.consumeCachedUrl(true)` to revoke temporary object URLs and clear `cachedUrl`.
+     * 4. On following reloads, if `options.ibl.valid === true` and no `cachedUrl` is present, use `#hdrTexture.clone()`.
      */
     async #initializeEnvironmentTexture() {
         if (this.#scene.environmentTexture) {
             this.#scene.environmentTexture.dispose();
             this.#scene.environmentTexture = null;
         }
-        const hdrTextureURI = this.#options.ibl.cachedUrl;
-        const hdrTexture = new HDRCubeTexture(hdrTextureURI, this.#scene, 1024, false, false, false, true, undefined, undefined, false, true, true);
+
+        let hdrTexture = null;
+        if (this.#options.ibl?.cachedUrl) {
+            const hdrTextureURI = this.#options.ibl.cachedUrl;
+            hdrTexture = new HDRCubeTexture(hdrTextureURI, this.#scene, 1024, false, false, false, true, undefined, undefined, false, true, true);
+        } else if (this.#hdrTexture && this.#options.ibl?.valid === true) {
+            hdrTexture = this.#hdrTexture.clone();
+        } else {
+            return false;
+        }
+
         await WhenTextureReadyAsync(hdrTexture);
+
+        if (this.#options.ibl?.cachedUrl) {
+            if (this.#hdrTexture) {
+                this.#hdrTexture.dispose();
+            }
+            this.#hdrTexture = hdrTexture.clone();
+            this.#options.ibl?.consumeCachedUrl?.(true);
+        }
+
         hdrTexture.level = this.#options.ibl.intensity;
         this.#scene.environmentTexture = hdrTexture;
         this.#scene.markAllMaterialsAsDirty(Material.TextureDirtyFlag);
@@ -715,20 +751,13 @@ export default class BabylonJSController {
      * @private
      * @returns {Promise<void|boolean>} Returns false if no environment texture is set; otherwise void.
      */
-    async #initializeIBLShadows() {
-
-        await this.#scene.whenReadyAsync();
-
+    async #initializeIBLShadows() {      
         const pipelineManager = this.#scene?.postProcessRenderPipelineManager;
-
-        if (!this.#scene || !pipelineManager || this.#scene?.activeCamera === null) {
-            return false;
-        }
         
-        if (!this.#scene.environmentTexture) {
+        if (!this.#scene || !this.#scene?.activeCamera || !this.#scene?.environmentTexture || !pipelineManager) {
             return false;
         }
-
+        
         if (!this.#scene.environmentTexture.isReady()) {
             const self = this;
             this.#scene.environmentTexture.onLoadObservable.addOnce(() => {
@@ -736,13 +765,41 @@ export default class BabylonJSController {
             });
             return false;
         }
-        
+
+        const meshesForCastingShadows = this.#scene.meshes.filter((mesh) => {
+            const isRootMesh = mesh.id.startsWith("__root__");
+            if (isRootMesh) {
+                return false;
+            }
+            
+            const isHDRIMesh = mesh.name?.toLowerCase() === "hdri";
+            const extrasCastShadows = mesh.metadata?.gltf?.extras?.castShadows;
+            const meshGenerateShadows = typeof extrasCastShadows === "boolean" ? extrasCastShadows : isHDRIMesh ? false : true;
+            
+            if (meshGenerateShadows) {
+                return true;
+            }
+            return false;
+        });
+        const materialsForReceivingShadows = this.#scene.materials.filter((material) => {
+            if (material instanceof PBRMaterial) {
+                material.enableSpecularAntiAliasing = false;
+            }
+            return true;
+        });
+
+        if (meshesForCastingShadows.length === 0 || materialsForReceivingShadows.length === 0) {
+            return false;
+        }
+
         const supportedPipelines = pipelineManager.supportedPipelines;
         
         if (!supportedPipelines) {
             return false;
         }
 
+        await this.#scene.whenReadyAsync();
+
         const pipelineName = "PrefViewerIblShadowsRenderPipeline";
 
         const pipelineOptions = {
@@ -775,30 +832,11 @@ export default class BabylonJSController {
             };
 
             Object.assign(iblShadowsPipeline, pipelineProps);
-            
-            this.#scene.meshes.forEach((mesh) => {
-                const isRootMesh = mesh.id.startsWith("__root__");
-                if (isRootMesh) {
-                    return false;
-                }
-                
-                const isHDRIMesh = mesh.name?.toLowerCase() === "hdri";
-                const extrasCastShadows = mesh.metadata?.gltf?.extras?.castShadows;
-                const meshGenerateShadows = typeof extrasCastShadows === "boolean" ? extrasCastShadows : isHDRIMesh ? false : true;
-                
-                if (meshGenerateShadows) {
-                    iblShadowsPipeline.addShadowCastingMesh(mesh);
-                    iblShadowsPipeline.updateSceneBounds();
-                }
-            });
-            
-            this.#scene.materials.forEach((material) => {
-                if (material instanceof PBRMaterial) {
-                    material.enableSpecularAntiAliasing = false;
-                }
-                iblShadowsPipeline.addShadowReceivingMaterial(material);
-            });
-            
+
+            meshesForCastingShadows.forEach((mesh) => iblShadowsPipeline.addShadowCastingMesh(mesh));
+            materialsForReceivingShadows.forEach((material) => iblShadowsPipeline.addShadowReceivingMaterial(material));
+                 
+            iblShadowsPipeline.updateSceneBounds();
             iblShadowsPipeline.toggleShadow(true);
             iblShadowsPipeline.updateVoxelization();
             this.#renderPipelines.iblShadows = iblShadowsPipeline;
@@ -935,7 +973,7 @@ export default class BabylonJSController {
 
         this.#ensureMeshesReceiveShadows();
 
-        const iblEnabled = this.#settings.iblEnabled && this.#options.ibl?.cachedUrl !== null;
+        const iblEnabled = this.#settings.iblEnabled && (this.#options.ibl?.valid === true || !!this.#options.ibl?.cachedUrl);
         const iblShadowsEnabled = iblEnabled && this.#options.ibl.shadows;
 
         if (iblShadowsEnabled) {
@@ -1058,6 +1096,10 @@ export default class BabylonJSController {
         if (!this.#engine) {
             return;
         }
+        if (this.#hdrTexture) {
+            this.#hdrTexture.dispose();
+            this.#hdrTexture = null;
+        }
         this.#engine.dispose();
         this.#engine = this.#scene = this.#camera = null;
         this.#hemiLight = this.#dirLight = this.#cameraLight = null;
@@ -1275,6 +1317,9 @@ export default class BabylonJSController {
      * Marks the IBL state as successful, recreates lights so the new environment takes effect, and reports whether anything changed.
      * @private
      * @returns {boolean} True when lights were refreshed due to pending IBL changes, otherwise false.
+     * @description
+     * Delegates to `#createLights()`, which executes the full IBL URL-to-texture lifecycle:
+     * `cachedUrl -> HDRCubeTexture -> #hdrTexture clone -> consumeCachedUrl(true)`.
      */
     async #setOptions_IBL() {
         return await this.#createLights();
@@ -1546,6 +1591,8 @@ export default class BabylonJSController {
             return [container, assetContainer];
         } catch (error) {
             return [container, assetContainer];
+        } finally {
+            this.#gltfResolver.revokeObjectURLs(sourceData.objectURLs);
         }
     }
 

package/src/file-storage.js

@@ -42,6 +42,9 @@ import { openDB } from "idb";
  *  - 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.
+ *  - TTL per entry: Expired records are removed automatically.
+ *  - Maximum entry limit: Old records are evicted with an LRU strategy when limit is exceeded.
+ *  - Quota-aware cleanup: Proactively frees space and retries writes on quota errors.
  *  - Promise-Based API: All operations return promises for async/await usage.
  *
  * Usage Example:
@@ -101,7 +104,7 @@ import { openDB } from "idb";
  *  - 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
+ *  - IndexedDB cache is auto-maintained (TTL, max entries, quota cleanup)
  *
  * Error Handling:
  *  - Network failures: Returns undefined (get) or false (other methods)
@@ -114,16 +117,329 @@ import { openDB } from "idb";
  *  - idb Library: https://github.com/jakearchibald/idb
  *  - npm idb: https://www.npmjs.com/package/idb
  */
-export class FileStorage {
+export default 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
+    #maxEntries = 300; // hard cap for cache records; oldest entries are evicted first
+    #entryTTLms = 7 * 24 * 60 * 60 * 1000; // 7 days
+    #cleanupIntervalMs = 5 * 60 * 1000; // run background cleanup at most every 5 minutes
+    #minimumFreeSpaceRatio = 0.05; // try to keep at least 5% of quota free
+    #maxQuotaEvictionRetries = 5; // max retries after quota error
+    #lastCleanupAt = 0; // timestamp of last automatic cleanup run
 
     constructor(dbName = "FilesDB", osName = "FilesObjectStore") {
         this.dbName = dbName; // database name
         this.osName = osName; // object store name used for file cache
     }
 
+    /**
+     * Returns the current timestamp in milliseconds.
+     * @private
+     * @returns {number} Epoch time in milliseconds.
+     */
+    #now() {
+        return Date.now();
+    }
+
+    /**
+     * Determines whether a cached record is expired.
+     * @private
+     * @param {Object|null|undefined} record Cached record with `expiresAt`.
+     * @param {number} [now=this.#now()] Current timestamp used for comparison.
+     * @returns {boolean} True when the record has expired; false otherwise.
+     */
+    #isExpired(record, now = this.#now()) {
+        return !!record && typeof record.expiresAt === "number" && record.expiresAt <= now;
+    }
+
+    /**
+     * Normalizes a raw cache record into the internal shape expected by the storage layer.
+     * Fills missing metadata (`size`, `createdAt`, `lastAccess`, `expiresAt`) using defaults.
+     * @private
+     * @param {Object|null|undefined} record Raw record from IndexedDB or network conversion.
+     * @returns {{blob: Blob, timeStamp: string|null, size: number, createdAt: number, lastAccess: number, expiresAt: number}|null}
+     * Normalized record, or null if the input is invalid.
+     */
+    #normalizeRecord(record) {
+        if (!record || !record.blob) {
+            return null;
+        }
+        const now = this.#now();
+        const createdAt = typeof record.createdAt === "number" ? record.createdAt : now;
+        const expiresAt = typeof record.expiresAt === "number" ? record.expiresAt : createdAt + this.#entryTTLms;
+        return {
+            blob: record.blob,
+            timeStamp: record.timeStamp ?? null,
+            size: typeof record.size === "number" ? record.size : record.blob.size,
+            createdAt: createdAt,
+            lastAccess: typeof record.lastAccess === "number" ? record.lastAccess : now,
+            expiresAt: expiresAt,
+        };
+    }
+
+    /**
+     * Converts an incoming file payload into a normalized cache record.
+     * @private
+     * @param {Object|Blob} file Incoming payload ({ blob, timeStamp } or raw Blob).
+     * @returns {{blob: Blob, timeStamp: string|null, size: number, createdAt: number, lastAccess: number, expiresAt: number}|null}
+     * Normalized record ready to persist, or null when payload is invalid.
+     */
+    #createRecordFromFile(file) {
+        if (!file) {
+            return null;
+        }
+        const now = this.#now();
+        const record = file instanceof Blob ? { blob: file, timeStamp: null } : file;
+        if (!record?.blob) {
+            return null;
+        }
+        return this.#normalizeRecord({
+            ...record,
+            createdAt: now,
+            lastAccess: now,
+            expiresAt: now + this.#entryTTLms,
+            size: record.blob.size,
+        });
+    }
+
+    /**
+     * Checks whether an IndexedDB error corresponds to quota exhaustion.
+     * @private
+     * @param {any} error Error thrown by IndexedDB operations.
+     * @returns {boolean} True when the error indicates storage quota was exceeded.
+     */
+    #isQuotaExceededError(error) {
+        if (!error) {
+            return false;
+        }
+        return error.name === "QuotaExceededError" || error.name === "NS_ERROR_DOM_QUOTA_REACHED" || error.code === 22 || error.code === 1014;
+    }
+
+    /**
+     * Loads all records from the object store with their keys.
+     * Invalid rows are ignored.
+     * @private
+     * @returns {Promise<Array<{key: IDBValidKey, record: {blob: Blob, timeStamp: string|null, size: number, createdAt: number, lastAccess: number, expiresAt: number}}>>}
+     * Array of key-record pairs.
+     */
+    async #getAllRecords() {
+        if (this.#db === undefined) {
+            this.#db = await this.#openDB();
+        }
+        if (this.#db === null) {
+            return [];
+        }
+        const transaction = this.#db.transaction(this.osName, "readonly");
+        const store = transaction.objectStore(this.osName);
+        const [keys, values] = await Promise.all([store.getAllKeys(), store.getAll()]);
+        return keys.map((key, index) => ({ key: key, record: this.#normalizeRecord(values[index]) })).filter((entry) => entry.record !== null);
+    }
+
+    /**
+     * Deletes a list of keys from the object store.
+     * @private
+     * @param {IDBValidKey[]} [keys=[]] Keys to delete.
+     * @returns {Promise<number>} Number of requested deletions.
+     */
+    async #deleteKeys(keys = []) {
+        if (!keys.length) {
+            return 0;
+        }
+        if (this.#db === undefined) {
+            this.#db = await this.#openDB();
+        }
+        if (this.#db === null) {
+            return 0;
+        }
+        const transaction = this.#db.transaction(this.osName, "readwrite");
+        const store = transaction.objectStore(this.osName);
+        keys.forEach((key) => {
+            store.delete(key);
+        });
+        await transaction.done;
+        return keys.length;
+    }
+
+    /**
+     * Removes expired entries based on their `expiresAt` field.
+     * @private
+     * @returns {Promise<number>} Number of deleted expired entries.
+     */
+    async #deleteExpiredEntries() {
+        const now = this.#now();
+        const records = await this.#getAllRecords();
+        const expiredKeys = records.filter((entry) => this.#isExpired(entry.record, now)).map((entry) => entry.key);
+        return this.#deleteKeys(expiredKeys);
+    }
+
+    /**
+     * Evicts least-recently-used records, excluding protected keys.
+     * @private
+     * @param {number} [maxToDelete=1] Maximum number of entries to delete.
+     * @param {IDBValidKey[]} [protectedKeys=[]] Keys that must not be evicted.
+     * @returns {Promise<number>} Number of deleted entries.
+     */
+    async #evictLeastRecentlyUsed(maxToDelete = 1, protectedKeys = []) {
+        if (maxToDelete <= 0) {
+            return 0;
+        }
+        const protectedSet = new Set(protectedKeys);
+        const records = await this.#getAllRecords();
+        const candidates = records
+            .filter((entry) => !protectedSet.has(entry.key))
+            .sort((a, b) => {
+                const aAccess = typeof a.record.lastAccess === "number" ? a.record.lastAccess : 0;
+                const bAccess = typeof b.record.lastAccess === "number" ? b.record.lastAccess : 0;
+                if (aAccess !== bAccess) {
+                    return aAccess - bAccess;
+                }
+                return a.record.createdAt - b.record.createdAt;
+            })
+            .slice(0, maxToDelete);
+        const keys = candidates.map((entry) => entry.key);
+        return this.#deleteKeys(keys);
+    }
+
+    /**
+     * Enforces the maximum number of cache entries by evicting LRU records.
+     * @private
+     * @param {IDBValidKey[]} [protectedKeys=[]] Keys excluded from eviction.
+     * @returns {Promise<number>} Number of removed entries.
+     */
+    async #enforceMaxEntries(protectedKeys = []) {
+        const protectedSet = new Set(protectedKeys);
+        const records = await this.#getAllRecords();
+        const count = records.length;
+        if (count <= this.#maxEntries) {
+            return 0;
+        }
+        const overflow = count - this.#maxEntries;
+        const candidates = records
+            .filter((entry) => !protectedSet.has(entry.key))
+            .sort((a, b) => {
+                const aAccess = typeof a.record.lastAccess === "number" ? a.record.lastAccess : 0;
+                const bAccess = typeof b.record.lastAccess === "number" ? b.record.lastAccess : 0;
+                if (aAccess !== bAccess) {
+                    return aAccess - bAccess;
+                }
+                return a.record.createdAt - b.record.createdAt;
+            })
+            .slice(0, overflow)
+            .map((entry) => entry.key);
+        return this.#deleteKeys(candidates);
+    }
+
+    /**
+     * Frees cache space when estimated free quota is below threshold.
+     * Uses LRU eviction and can reserve bytes for an upcoming write.
+     * @private
+     * @param {number} [requiredBytes=0] Extra free bytes desired for the next write.
+     * @param {IDBValidKey[]} [protectedKeys=[]] Keys excluded from eviction.
+     * @returns {Promise<number>} Number of removed entries.
+     */
+    async #freeSpaceForQuota(requiredBytes = 0, protectedKeys = []) {
+        if (typeof navigator === "undefined" || !navigator.storage?.estimate) {
+            return 0;
+        }
+        let estimate = null;
+        try {
+            estimate = await navigator.storage.estimate();
+        } catch (error) {
+            return 0;
+        }
+        const quota = Number(estimate?.quota || 0);
+        const usage = Number(estimate?.usage || 0);
+        if (quota <= 0) {
+            return 0;
+        }
+        const minimumFreeBytes = Math.max(requiredBytes, Math.floor(quota * this.#minimumFreeSpaceRatio));
+        const freeBytes = Math.max(0, quota - usage);
+        if (freeBytes >= minimumFreeBytes) {
+            return 0;
+        }
+        const bytesToFree = minimumFreeBytes - freeBytes;
+
+        const protectedSet = new Set(protectedKeys);
+        const records = await this.#getAllRecords();
+        const candidates = records
+            .filter((entry) => !protectedSet.has(entry.key))
+            .sort((a, b) => {
+                const aAccess = typeof a.record.lastAccess === "number" ? a.record.lastAccess : 0;
+                const bAccess = typeof b.record.lastAccess === "number" ? b.record.lastAccess : 0;
+                if (aAccess !== bAccess) {
+                    return aAccess - bAccess;
+                }
+                return a.record.createdAt - b.record.createdAt;
+            });
+
+        let accumulated = 0;
+        const keysToDelete = [];
+        for (const candidate of candidates) {
+            keysToDelete.push(candidate.key);
+            accumulated += Number(candidate.record.size || 0);
+            if (accumulated >= bytesToFree) {
+                break;
+            }
+        }
+        return this.#deleteKeys(keysToDelete);
+    }
+
+    /**
+     * Runs full maintenance: delete expired entries, enforce max entries, and free quota.
+     * @private
+     * @param {Object} [options={}] Cleanup options.
+     * @param {number} [options.requiredBytes=0] Extra bytes to reserve for a pending write.
+     * @param {IDBValidKey[]} [options.protectedKeys=[]] Keys excluded from eviction.
+     * @returns {Promise<void>}
+     */
+    async #runCleanup({ requiredBytes = 0, protectedKeys = [] } = {}) {
+        await this.#deleteExpiredEntries();
+        await this.#enforceMaxEntries(protectedKeys);
+        await this.#freeSpaceForQuota(requiredBytes, protectedKeys);
+    }
+
+    /**
+     * Runs maintenance only when the cleanup interval has elapsed.
+     * @private
+     * @returns {Promise<void>}
+     */
+    async #runCleanupIfDue() {
+        const now = this.#now();
+        if (now - this.#lastCleanupAt < this.#cleanupIntervalMs) {
+            return;
+        }
+        this.#lastCleanupAt = now;
+        await this.#runCleanup();
+    }
+
+    /**
+     * Updates `lastAccess` for a record to keep LRU ordering current.
+     * @private
+     * @param {String} uri Record key.
+     * @param {Object} record Existing normalized record.
+     * @returns {Promise<void>}
+     */
+    async #touchFile(uri, record) {
+        const normalized = this.#normalizeRecord(record);
+        if (!normalized) {
+            return;
+        }
+        normalized.lastAccess = this.#now();
+        if (this.#db === undefined) {
+            this.#db = await this.#openDB();
+        }
+        if (this.#db === null) {
+            return;
+        }
+        try {
+            const transaction = this.#db.transaction(this.osName, "readwrite");
+            const store = transaction.objectStore(this.osName);
+            store.put(normalized, uri);
+            await transaction.done;
+        } catch (error) {}
+    }
+
     /**
      * Create the object store if it does not exist.
      * @private
@@ -260,10 +576,11 @@ export class FileStorage {
      * @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)
-     *   - resolves to the put result on success
-     *   - resolves to undefined if the database could not be opened
-     *   - rejects if the underlying put operation throws
+     * @returns {Promise<any|undefined>} Resolves with idb store.put result on success,
+     * or undefined when the database is unavailable, input is invalid, or write fails after quota retries.
+     * @description
+     * Runs maintenance before write (TTL, max entries, and quota-aware cleanup), then retries quota errors
+     * by evicting least-recently-used entries.
      */
     async #putFile(file, uri) {
         if (this.#db === undefined) {
@@ -272,30 +589,71 @@ export class FileStorage {
         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);
+        const record = this.#createRecordFromFile(file);
+        if (!record) {
+            return undefined;
+        }
+
+        const currentRecord = await this.#getFile(uri, { touch: false, allowExpired: true });
+        const currentSize = currentRecord ? Number(currentRecord.size || currentRecord.blob?.size || 0) : 0;
+        const requiredBytes = Math.max(0, record.size - currentSize);
+
+        await this.#runCleanup({ requiredBytes: requiredBytes, protectedKeys: [uri] });
+
+        for (let attempt = 0; attempt <= this.#maxQuotaEvictionRetries; attempt++) {
+            try {
+                const transaction = this.#db.transaction(this.osName, "readwrite");
+                const store = transaction.objectStore(this.osName);
+                const result = await store.put(record, uri);
+                await transaction.done;
+                return result;
+            } catch (error) {
+                if (!this.#isQuotaExceededError(error) || attempt === this.#maxQuotaEvictionRetries) {
+                    return undefined;
+                }
+                const deleted = await this.#evictLeastRecentlyUsed(1, [uri]);
+                if (!deleted) {
+                    return undefined;
+                }
+            }
+        }
+        return undefined;
     }
 
     /**
      * 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
+     * @param {{touch?: boolean, allowExpired?: boolean}} [options] Read options.
+     * @param {boolean} [options.touch=true] Update lastAccess when the record is found.
+     * @param {boolean} [options.allowExpired=false] Return expired records instead of deleting them.
+     * @returns {Promise<{blob: Blob, timeStamp: string|null, size: number, createdAt: number, lastAccess: number, expiresAt: number}|undefined|false>} Resolves with:
+     *   - normalized cache record when found
      *   - undefined: if there is no stored entry for that URI
      *   - false: if the database could not be opened (IndexedDB unsupported or open failure)
      */
-    async #getFile(uri) {
+    async #getFile(uri, { touch = true, allowExpired = false } = {}) {
         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);
+        const transaction = this.#db.transaction(this.osName, "readonly");
+        const store = transaction.objectStore(this.osName);
+        const record = this.#normalizeRecord(await store.get(uri));
+        if (!record) {
+            return undefined;
+        }
+        if (!allowExpired && this.#isExpired(record)) {
+            await this.#deleteKeys([uri]);
+            return undefined;
+        }
+        if (touch) {
+            await this.#touchFile(uri, record);
+            record.lastAccess = this.#now();
+        }
+        return record;
     }
 
     /**
@@ -309,7 +667,7 @@ export class FileStorage {
      * @public
      * @param {String} uri - File URI
      * @returns {Promise<string|boolean>} Resolves with:
-     *   - object URL string for the cached Blob
+     *   - object URL string for the cached Blob (caller must revoke it when done)
      *   - original URI string if IndexedDB unsupported but server file exists
      *   - false if the file is not available on the server
      */
@@ -317,6 +675,7 @@ export class FileStorage {
         if (!this.#supported) {
             return (await this.#getServerFileTimeStamp(uri)) ? uri : false;
         }
+        await this.#runCleanupIfDue();
         const storedFile = await this.get(uri);
         return storedFile ? URL.createObjectURL(storedFile.blob) : (await this.#getServerFileTimeStamp(uri)) ? uri : false;
     }
@@ -326,7 +685,7 @@ export class FileStorage {
      * @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
+     *   - ISO 8601 string from the cached record (when using IndexedDB) or from the server HEAD response
      *   - null: when no timestamp is available or on error
      */
     async getTimeStamp(uri) {
@@ -343,7 +702,7 @@ export class FileStorage {
      * @public
      * @param {String} uri - File URI
      * @returns {Promise<number|null>} Resolves with:
-     *   - number: size in bytes when available (from cache or server)
+     *   - number: size in bytes when available (from cache metadata/blob or server HEAD)
      *   - null: when size is not available or on error
      */
     async getSize(uri) {
@@ -376,8 +735,8 @@ export class FileStorage {
      * Get the file Blob from IndexedDB if stored; otherwise download and store it, then return the Blob.
      * @public
      * @param {String} uri - File URI
-     * @returns {Promise<Blob|undefined|false>} Resolves with:
-     *   - Blob of the stored file
+     * @returns {Promise<{blob: Blob, timeStamp: string|null, size?: number, createdAt?: number, lastAccess?: number, expiresAt?: number}|undefined|false>} Resolves with:
+     *   - cached/server record containing at least `{ blob, timeStamp }`
      *   - undefined if the download fails
      *   - false if uri is falsy
      * @description
@@ -392,6 +751,7 @@ export class FileStorage {
         if (!this.#supported) {
             return await this.#getServerFile(uri);
         }
+        await this.#runCleanupIfDue();
         let storedFile = await this.#getFile(uri);
         const serverFileTimeStamp = storedFile ? await this.#getServerFileTimeStamp(uri) : 0;
         const storedFileTimeStamp = storedFile ? storedFile.timeStamp : 0;
@@ -412,12 +772,13 @@ export class FileStorage {
      * @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
+     *   - false if IndexedDB is not supported, download failed, or storing failed after cleanup/retries
      */
     async put(uri) {
         if (!this.#supported) {
             return false;
         }
+        await this.#runCleanupIfDue();
         const fileToStore = await this.#getServerFile(uri);
         return fileToStore ? !!(await this.#putFile(fileToStore, uri)) : false;
     }

package/src/gltf-resolver.js

@@ -1,4 +1,4 @@
-import { FileStorage } from "./file-storage.js";
+import FileStorage from "./file-storage.js";
 import { initDb, loadModel } from "./gltf-storage.js";
 
 /**
@@ -9,6 +9,7 @@ import { initDb, loadModel } from "./gltf-storage.js";
  *  - 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.
+ *  - Tracks generated object URLs so callers can revoke them after Babylon finishes loading.
  *  - Provides methods for initializing storage, decoding assets, and preparing sources for viewer components.
  *
  * Usage:
@@ -17,11 +18,13 @@ import { initDb, loadModel } from "./gltf-storage.js";
  *
  * Public Methods:
  *  - getSource(storage, currentSize, currentTimeStamp): Resolves and prepares a glTF/GLB source for loading.
+ *  - revokeObjectURLs(objectURLs): Releases temporary blob URLs generated during source resolution.
  *
  * 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.
+ *  - #isBlobURL(url): Checks if a URL is a blob object URL.
  *  - #saveAssetData(asset, index, parent, assetArray): Collects asset entries with external URIs.
  *  - #replaceSceneURIAsync(assetContainerJSON, assetContainerURL): Replaces internal URIs in glTF JSON with resolved URLs.
  *
@@ -124,6 +127,16 @@ export default class GLTFResolver {
         }
     }
 
+    /**
+     * Check whether a URL is a browser object URL.
+     * @private
+     * @param {string} url - Value to test.
+     * @returns {boolean} True when `url` is a blob object URL.
+     */
+    #isBlobURL(url) {
+        return typeof url === "string" && url.startsWith("blob:");
+    }
+
     /**
      * Collects asset entries that have an external URI (non-data URI) and stores a normalized absolute or relative-resolved URI for later replacement.
      * @private
@@ -154,6 +167,7 @@ export default class GLTFResolver {
      * @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.
+     * @param {string[]} [objectURLs=[]] - Collector array where generated blob URLs are appended for later cleanup.
      * @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).
@@ -162,11 +176,12 @@ export default class GLTFResolver {
      * - 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).
+     * - Any generated blob URL is appended to `objectURLs` so the caller can revoke it later.
      * - 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) {
+    async #replaceSceneURIAsync(assetContainerJSON, assetContainerURL, objectURLs = []) {
         if (!assetContainerJSON) {
             return;
         }
@@ -193,11 +208,29 @@ export default class GLTFResolver {
             const uri = await this.#fileStorage.getURL(asset.uri);
             if (uri) {
                 asset.parent[asset.index].uri = uri;
+                if (this.#isBlobURL(uri)) {
+                    objectURLs.push(uri);
+                }
             }
         });
         await Promise.all(promisesArray);
     }
 
+    /**
+     * Revoke browser object URLs and clear the provided list.
+     * @public
+     * @param {string[]} objectURLs - URLs previously created via URL.createObjectURL.
+     * @returns {void}
+     */
+    revokeObjectURLs(objectURLs = []) {
+        objectURLs.forEach((url) => {
+            if (this.#isBlobURL(url)) {
+                URL.revokeObjectURL(url);
+            }
+        });
+        objectURLs.length = 0;
+    }
+
     /**
      * Resolves and prepares a glTF/GLB source from various storage backends.
      * Supports IndexedDB, direct URLs, and base64-encoded data.
@@ -206,21 +239,22 @@ export default class GLTFResolver {
      * @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}>}
+     * @returns {Promise<false|{source: File|string, size: number, timeStamp: string|null, extension: string, metadata: object, objectURLs: 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.
+     *   - Resolves to an object containing source, cache metadata, and tracked object URLs 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.
+     *   - Returns the prepared source, size, timestamp, extension, metadata, and objectURLs for further processing.
      */
     async getSource(storage, currentSize, currentTimeStamp) {
         let source = storage.url || null;
         let newSize, newTimeStamp;
         let pending = false;
         let metadata = {};
+        const objectURLs = [];
 
         if (storage.db && storage.table && storage.id) {
             await this.#initializeStorage(storage.db, storage.table);
@@ -249,7 +283,7 @@ export default class GLTFResolver {
         if (blob && extension) {
             if (extension === ".gltf") {
                 const assetContainerJSON = JSON.parse(await blob.text());
-                await this.#replaceSceneURIAsync(assetContainerJSON, source);
+                await this.#replaceSceneURIAsync(assetContainerJSON, source, objectURLs);
                 source = `data:${JSON.stringify(assetContainerJSON)}`;
             } else {
                 file = new File([blob], `file${extension}`, {
@@ -278,13 +312,23 @@ export default class GLTFResolver {
                 if (extension === ".gltf") {
                     const assetContainerBlob = await this.#fileStorage.getBlob(source);
                     const assetContainerJSON = JSON.parse(await assetContainerBlob.text());
-                    await this.#replaceSceneURIAsync(assetContainerJSON, source);
+                    await this.#replaceSceneURIAsync(assetContainerJSON, source, objectURLs);
                     source = `data:${JSON.stringify(assetContainerJSON)}`;
                 } else {
                     source = await this.#fileStorage.getURL(source);
+                    if (this.#isBlobURL(source)) {
+                        objectURLs.push(source);
+                    }
                 }
             }
         }
-        return { source: file || source, size: newSize, timeStamp: newTimeStamp, extension: extension, metadata: metadata, };
+        return {
+            source: file || source,
+            size: newSize,
+            timeStamp: newTimeStamp,
+            extension: extension,
+            metadata: metadata,
+            objectURLs: objectURLs,
+        };
     }
 }

package/src/pref-viewer-3d-data.js

@@ -219,36 +219,94 @@ export class CameraData {
  *
  * Responsibilities:
  *  - Stores source and cache references (`url`, `cachedUrl`) for the HDR environment map.
+ *  - Tracks whether the HDR texture is already valid and reusable without needing `cachedUrl` (`valid`).
  *  - Stores runtime tuning values (`intensity`, `shadows`) and cache identity (`timeStamp`).
  *  - Provides helpers to fully reset IBL state (`reset`) or partially update known fields (`setValues`).
+ *  - Provides a helper to consume and clear temporary cached URLs after texture creation (`consumeCachedUrl`).
  *
  * Usage:
  *  - Instantiate with defaults: `const ibl = new IBLData();`.
- *  - Call `setValues(...)` with only the fields you want to update (undefined preserves current values).
+ *  - Call `setValues(...)` with only the fields you want to update (`undefined` preserves current values).
+ *  - Lifecycle: set a fresh `cachedUrl` via `setValues(...)`, create/clone the Babylon HDR texture, then call
+ *    `consumeCachedUrl(true)` to revoke temporary blob URLs, set `cachedUrl` to null, and keep `valid=true`.
  *  - Call `reset()` to clear the current IBL environment and restore default intensity/shadows.
  */
 export class IBLData {
     defaultIntensity = 1.0;
     defaultShadows = false;
-    constructor(url = null, cachedUrl = null, intensity = this.defaultIntensity, shadows = this.defaultShadows, timeStamp = null) {
+    constructor(url = null, cachedUrl = null, intensity = this.defaultIntensity, shadows = this.defaultShadows, timeStamp = null, valid = false) {
         this.url = url;
         this.cachedUrl = cachedUrl;
         this.intensity = intensity;
         this.shadows = shadows;
         this.timeStamp = timeStamp;
+        this.valid = valid;
     }
+
+    /**
+     * Revokes object URLs (`blob:`) to release browser memory.
+     * @private
+     * @param {string|null|undefined} url URL to revoke when applicable.
+     * @returns {void}
+     */
+    #revokeIfBlobURL(url) {
+        if (typeof url === "string" && url.startsWith("blob:")) {
+            URL.revokeObjectURL(url);
+        }
+    }
+
+    /**
+     * Resets IBL state and revokes any temporary cached object URL.
+     * @public
+     * @returns {void}
+     */
     reset() {
+        this.#revokeIfBlobURL(this.cachedUrl);
         this.url = null
         this.cachedUrl = null;
         this.intensity = this.defaultIntensity;
         this.shadows = this.defaultShadows;
         this.timeStamp = null;
+        this.valid = false;
+    }
+
+    /**
+     * Consumes the temporary cached URL after Babylon texture creation.
+     * Revokes the URL when it is a `blob:` object URL, clears `cachedUrl`,
+     * and marks whether a reusable in-memory texture is available.
+     * @public
+     * @param {boolean} [valid=true] Whether the corresponding HDR texture has been validated and cached in memory.
+     * @returns {void}
+     */
+    consumeCachedUrl(valid = true) {
+        this.#revokeIfBlobURL(this.cachedUrl);
+        this.cachedUrl = null;
+        this.valid = !!valid;
     }
+
+    /**
+     * Updates selected IBL fields while preserving unspecified values.
+     * When a new non-empty `cachedUrl` is supplied, `valid` is reset to `false`
+     * until the URL is consumed into a Babylon texture.
+     * @public
+     * @param {string|null|undefined} url Source URL identifier.
+     * @param {string|null|undefined} cachedUrl Resolved URL (including possible `blob:` URL).
+     * @param {number|undefined} intensity IBL intensity.
+     * @param {boolean|undefined} shadows Shadow toggle for IBL path.
+     * @param {string|null|undefined} timeStamp Last-modified marker.
+     * @returns {void}
+     */
     setValues(url, cachedUrl, intensity, shadows, timeStamp) {
+        if (cachedUrl !== undefined && cachedUrl !== this.cachedUrl) {
+            this.#revokeIfBlobURL(this.cachedUrl);
+        }
         this.url = url !== undefined ? url : this.url;
         this.cachedUrl = cachedUrl !== undefined ? cachedUrl : this.cachedUrl;
         this.intensity = intensity !== undefined ? intensity : this.intensity;
         this.shadows = shadows !== undefined ? shadows : this.shadows;
         this.timeStamp = timeStamp !== undefined ? timeStamp : this.timeStamp;
+        if (cachedUrl !== undefined) {
+            this.valid = typeof cachedUrl === "string" && cachedUrl.length > 0 ? false : this.valid;
+        }
     }
 }

package/src/pref-viewer-3d.js

@@ -1,7 +1,7 @@
 import { CameraData, ContainerData, MaterialData, IBLData } from "./pref-viewer-3d-data.js";
 import BabylonJSController from "./babylonjs-controller.js";
 import { PrefViewer3DStyles } from "./styles.js";
-import { FileStorage } from "./file-storage.js";
+import FileStorage from "./file-storage.js";
 
 /**
  * PrefViewer3D - Custom Web Component for interactive 3D visualization and configuration.
@@ -771,12 +771,19 @@ export default class PrefViewer3D extends HTMLElement {
     }
 
     /**
-     * Reports whether an IBL environment map is currently available (cached URL present).
+     * Reports whether an IBL environment map is currently available.
      * @public
-     * @returns {boolean} True when `options.ibl.cachedUrl` exists and is non-empty.
+     * @returns {boolean} True when a validated IBL texture exists or a pending cached URL is available.
      */
     isIBLAvailable() {
-        const cachedUrl = this.#data?.options?.ibl?.cachedUrl;
+        const ibl = this.#data?.options?.ibl;
+        if (!ibl) {
+            return false;
+        }
+        if (ibl.valid === true) {
+            return true;
+        }
+        const cachedUrl = ibl.cachedUrl;
         return typeof cachedUrl === "string" ? cachedUrl.length > 0 : Boolean(cachedUrl);
     }