@preference-sl/pref-viewer 2.13.0-beta.0 → 2.13.0-beta.10

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,14 @@ 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.
+ *  - dispose(): Releases resolver resources and closes the internal FileStorage DB handle.
  *
  * 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 +128,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 +168,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 +177,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 +209,39 @@ 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;
+    }
+
+    /**
+     * Disposes resolver-owned resources.
+     * @public
+     * @returns {void}
+     */
+    dispose() {
+        this.#fileStorage?.dispose?.();
+        this.#fileStorage = null;
+    }
+
     /**
      * Resolves and prepares a glTF/GLB source from various storage backends.
      * Supports IndexedDB, direct URLs, and base64-encoded data.
@@ -206,21 +250,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 +294,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 +323,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/index.js

@@ -3,11 +3,13 @@ import PrefViewer from "./pref-viewer.js";
 import PrefViewer2D from "./pref-viewer-2d.js";
 import PrefViewer3D from "./pref-viewer-3d.js";
 import PrefViewerDialog from "./pref-viewer-dialog.js";
+import PrefViewerMenu3D from "./pref-viewer-menu-3d.js";
 
 // Defines custom elements for use as HTML tags in the application.
 customElements.define("pref-viewer-2d", PrefViewer2D);
 customElements.define("pref-viewer-3d", PrefViewer3D);
 customElements.define("pref-viewer-dialog", PrefViewerDialog);
+customElements.define("pref-viewer-menu-3d", PrefViewerMenu3D);
 customElements.define("pref-viewer", PrefViewer);
 
 // Exposes selected PrefViewer classes globally for external JavaScript use.

package/src/localization/i18n.js

@@ -0,0 +1,94 @@
+import translations from "./translations.js";
+
+export const DEFAULT_LOCALE = "en-EN";
+
+export const SUPPORTED_LOCALES = Object.keys(translations);
+const listeners = new Set();
+let currentLocale = DEFAULT_LOCALE;
+
+const findLocaleKey = (localeId) => {
+    if (typeof localeId !== "string") {
+        return DEFAULT_LOCALE;
+    }
+    const normalized = localeId.trim().toLowerCase();
+    const match = SUPPORTED_LOCALES.find((locale) => locale.toLowerCase() === normalized);
+    return match ?? DEFAULT_LOCALE;
+};
+
+const getBundle = (localeId = currentLocale) => {
+    const key = findLocaleKey(localeId);
+    return translations[key] ?? translations[DEFAULT_LOCALE];
+};
+
+const resolveValue = (bundle, parts) => parts.reduce((acc, part) => (
+    acc && Object.prototype.hasOwnProperty.call(acc, part) ? acc[part] : undefined
+), bundle);
+
+export const availableLocales = () => [...SUPPORTED_LOCALES];
+
+export const getLocale = () => currentLocale;
+
+export const resolveLocale = (localeId) => findLocaleKey(localeId);
+
+export const setLocale = (localeId) => {
+    const resolved = findLocaleKey(localeId);
+    if (resolved === currentLocale) {
+        return currentLocale;
+    }
+    currentLocale = resolved;
+    listeners.forEach((listener) => {
+        try {
+            listener(currentLocale);
+        } catch (error) {
+            console.warn("PrefViewer i18n listener failed", error);
+        }
+    });
+    return currentLocale;
+};
+
+export const onLocaleChange = (listener) => {
+    if (typeof listener !== "function") {
+        return () => {};
+    }
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+};
+
+export const translate = (key, options = {}) => {
+    if (!key) {
+        return "";
+    }
+    const { locale, fallback } = options;
+    const parts = Array.isArray(key) ? key : key.split(".");
+    const bundle = getBundle(locale);
+    let value = resolveValue(bundle, parts);
+    if (value !== undefined) {
+        return value;
+    }
+    if (bundle !== translations[DEFAULT_LOCALE]) {
+        value = resolveValue(translations[DEFAULT_LOCALE], parts);
+        if (value !== undefined) {
+            return value;
+        }
+    }
+    return fallback ?? "";
+};
+
+export const getNamespace = (namespace, options = {}) => {
+    if (!namespace) {
+        return getBundle(options.locale);
+    }
+    return translate(namespace, options);
+};
+
+export default {
+    availableLocales,
+    DEFAULT_LOCALE,
+    getLocale,
+    getNamespace,
+    onLocaleChange,
+    resolveLocale,
+    setLocale,
+    SUPPORTED_LOCALES,
+    translate,
+};

package/src/localization/translations.js

@@ -0,0 +1,104 @@
+export const translations = {
+    "en-EN": {
+        prefViewer: {
+            menu3d: {
+                title: "3D render settings",
+                subtitle: "Toggle visual effects on or off.",
+                pendingLabel: "Pending changes",
+                actions: {
+                    apply: "Apply",
+                    applying: "Applying...",
+                },
+                status: {
+                    error: "Couldn't apply the changes.",
+                },
+                switches: {
+                    antiAliasingEnabled: {
+                        label: "Antialiasing",
+                        helper: "Softens jagged edges and lines.",
+                    },
+                    ambientOcclusionEnabled: {
+                        label: "Ambient Occlusion",
+                        helper: "Reduction of ambient light in corners and areas close to surfaces.",
+                    },
+                    iblEnabled: {
+                        label: "Image Based Lighting (IBL)",
+                        helper: "Uses the HDR environment to light the scene.",
+                    },
+                    shadowsEnabled: {
+                        label: "Shadows",
+                        helper: "Enables shadows.",
+                    },
+                },
+            },
+            downloadDialog: {
+                title: "Download 3D Scene",
+                sections: {
+                    content: "Content",
+                    format: "Format",
+                },
+                options: {
+                    model: "Model",
+                    scene: "Scene",
+                    both: "Both",
+                },
+                buttons: {
+                    download: "Download",
+                    cancel: "Cancel",
+                },
+            },
+        },
+    },
+    "es-ES": {
+        prefViewer: {
+            menu3d: {
+                title: "Ajustes de render 3D",
+                subtitle: "Activa o desactiva los efectos visuales.",
+                pendingLabel: "Pendiente de aplicar",
+                actions: {
+                    apply: "Aplicar",
+                    applying: "Aplicando...",
+                },
+                status: {
+                    error: "No se pudo aplicar los cambios.",
+                },
+                switches: {
+                    antiAliasingEnabled: {
+                        label: "Antialiasing",
+                        helper: "Suaviza aristas y líneas.",
+                    },
+                    ambientOcclusionEnabled: {
+                        label: "Oclusión ambiental",
+                        helper: "Atenuación de la luz ambiental en rincones y zonas cercanas entre superficies.",
+                    },
+                    iblEnabled: {
+                        label: "Iluminación basada en imagen (IBL)",
+                        helper: "Usa la imagen HDR de entorno para iluminar la escena.",
+                    },
+                    shadowsEnabled: {
+                        label: "Sombras",
+                        helper: "Activa sombras.",
+                    },
+                },
+            },
+            downloadDialog: {
+                title: "Descargar escena 3D",
+                sections: {
+                    content: "Contenido",
+                    format: "Formato",
+                },
+                options: {
+                    model: "Modelo",
+                    scene: "Escena",
+                    both: "Ambos",
+                },
+                buttons: {
+                    download: "Descargar",
+                    cancel: "Cancelar",
+                },
+            },
+        },
+    },
+};
+
+export default translations;

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

@@ -1,15 +1,18 @@
 /**
- * ContainerData - Represents the state and metadata of a asset container in the 3D viewer (e.g., model, environment, materials).
+ * ContainerData - Represents state, cache metadata, and update lifecycle for a 3D asset container
+ * (for example: model, environment, or materials).
  *
  * Responsibilities:
- *  - Tracks container name, show (if must be visible), visibility (if currently visible), size, and timestamp.
- *  - Manages update state for asynchronous operations (pending, success, etc.).
- *  - Provides methods to reset, set pending, and set success states.
+ *  - Tracks persistent container fields (`storage`, `show`, `size`, `timeStamp`, `metadata`, `visible`).
+ *  - Tracks staged update data in `update` (`pending`, `success`, staged storage/show/cache info).
+ *  - Provides helpers to stage updates (`setPending`, `setPendingCacheData`, `setPendingWithCurrentStorage`)
+ *    and commit them (`setSuccess(true)`).
  *
  * Usage:
- *  - Instantiate with a name: new ContainerData("model")
- *  - Use setPending(), setSuccess(), and reset() to manage update state.
- *  - Access status via isPending, isSuccess, isVisible getters.
+ *  - Instantiate with a name: `new ContainerData("model")`.
+ *  - Stage a reload with `setPending(...)`, optionally seed cache metadata, then finalize with `setSuccess(true)`.
+ *  - Use `setPendingWithCurrentStorage()` to request a reload from the currently stored source.
+ *  - Inspect flags via `isPending`, `isSuccess`, `isVisible`, and `mustBeShown`.
  */
 export class ContainerData {
     constructor(name = "") {
@@ -18,6 +21,7 @@ export class ContainerData {
         this.show = true;
         this.size = 0;
         this.timeStamp = null;
+        this.storage = null;
         this.visible = false;
         // Set initial information about ongoing update
         this.reset();
@@ -40,6 +44,9 @@ export class ContainerData {
             this.size = this.update.size;
             this.timeStamp = this.update.timeStamp;
             this.metadata = { ...(this.update.metadata ?? {}) };
+            if (this.update.storage !== undefined && this.update.storage !== null) {
+                this.storage = this.update.storage;
+            }
         } else {
             this.update.success = false;
         }
@@ -50,12 +57,25 @@ export class ContainerData {
         this.update.storage = storage;
         this.update.success = false;
         this.update.show = show !== undefined ? show : this.update.show !== null ? this.update.show : this.show;
+        if (storage !== undefined && storage !== null) {
+            this.storage = storage;
+        }
     }
     setPendingCacheData(size = 0, timeStamp = null, metadata = {}) {
         this.update.size = size;
         this.update.timeStamp = timeStamp;
         this.update.metadata = { ...(metadata ?? {}) };
     }
+    setPendingWithCurrentStorage() {
+        const storedSource = this.storage ?? null;
+        if (!storedSource) {
+            return false;
+        }
+        const targetShow = this.update.show !== null ? this.update.show : this.show;
+        this.setPending(storedSource, targetShow);
+        this.setPendingCacheData(this.size, this.timeStamp, this.metadata);
+        return true;
+    }
     get isPending() {
         return this.update.pending === true;
     }
@@ -71,17 +91,18 @@ export class ContainerData {
 }
 
 /**
- * MaterialData - Represents the state and metadata of a material in the 3D viewer.
+ * MaterialData - Represents a material option plus its update lifecycle in the 3D viewer.
  *
  * Responsibilities:
- *  - Tracks material name, value, node names, and node prefixes.
- *  - Manages update state for asynchronous operations (pending, success, etc.).
- *  - Provides methods to reset, set pending, and set success states.
+ *  - Stores material identity and targeting info (`name`, `nodeNames`, `nodePrefixes`).
+ *  - Stores current applied material value (`value`).
+ *  - Tracks staged material changes in `update` (`pending`, `success`, `value`).
  *
  * Usage:
- *  - Instantiate with a name and optional value: new MaterialData("innerWall", value, nodeNames, nodePrefixes)
- *  - Use setPending(), setSuccess(), and reset() to manage update state.
- *  - Access status via isPending, isSuccess getters.
+ *  - Instantiate with initial values: `new MaterialData("innerWall", value, nodeNames, nodePrefixes)`.
+ *  - Stage a change with `setPending(...)`, then commit with `setSuccess(true)`.
+ *  - Use `setPendingWithCurrent()` to reapply the currently stored material value.
+ *  - Inspect flags via `isPending` and `isSuccess`.
  */
 export class MaterialData {
     constructor(name = "", value = null, nodeNames = [], nodePrefixes = []) {
@@ -114,7 +135,11 @@ export class MaterialData {
         this.update.value = value;
     }
     setPendingWithCurrent() {
+        if (this.value === undefined) {
+            return false;
+        }
         this.setPending(this.value);
+        return true;
     }
     get isPending() {
         return this.update.pending === true;
@@ -125,17 +150,18 @@ export class MaterialData {
 }
 
 /**
- * CameraData - Represents the state and metadata of a camera in the 3D viewer.
+ * CameraData - Represents camera selection state and camera-lock behavior for the 3D viewer.
  *
  * Responsibilities:
- *  - Tracks camera name, value, and locked status.
- *  - Manages update state for asynchronous operations (pending, success, etc.).
- *  - Provides methods to reset, set pending, and set success states.
+ *  - Stores current camera selection (`value`) and lock state (`locked`).
+ *  - Tracks staged camera updates in `update` (`pending`, `success`, `value`, `locked`).
+ *  - Provides helpers to stage (`setPending`, `setPendingWithCurrent`) and commit (`setSuccess(true)`) updates.
  *
  * Usage:
- *  - Instantiate with a name and optional value: new CameraData("camera", value, locked)
- *  - Use setPending(), setSuccess(), and reset() to manage update state.
- *  - Access status via isPending, isSuccess getters.
+ *  - Instantiate with a name and optional value: `new CameraData("camera", value, locked)`.
+ *  - Stage a camera update with `setPending(value, locked)`.
+ *  - Pass `null` as value to request an unlocked/default camera behavior.
+ *  - Inspect flags via `isPending` and `isSuccess`.
  */
 export class CameraData {
     defaultLocked = true;
@@ -175,6 +201,11 @@ export class CameraData {
         this.update.value = value;
         this.update.locked = locked;
     }
+    setPendingWithCurrent() {
+        const currentValue = this.value !== undefined ? this.value : null;
+        this.setPending(currentValue, this.locked);
+        return true;
+    }
     get isPending() {
         return this.update.pending === true;
     }
@@ -184,51 +215,98 @@ export class CameraData {
 }
 
 /**
- * IBLData - Tracks configurable settings for image-based lighting assets (IBL/HDR environments).
+ * IBLData - Stores image-based lighting configuration for HDR environment rendering.
  *
  * Responsibilities:
- *  - Stores the HDR url, intensity scalar, whether environment-provided shadows should render, and cache timestamp.
- *  - Exposes a lightweight pending/success state machine so UI flows know when a new IBL selection is being fetched.
- *  - Provides helpers to update values atomically via `setValues`, toggle pending state, and mark completion.
+ *  - 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 `setPending()` before kicking off an async download, `setValues()` as metadata streams in, and `setSuccess(true)` once loading finishes.
- *  - Inspect `isPending`/`isSuccess` to drive UI or re-render logic.
+ *  - Instantiate with defaults: `const ibl = new IBLData();`.
+ *  - 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 {
-    constructor(url = null, intensity = 1.0, shadows = false, timeStamp = null) {
+    defaultIntensity = 1.0;
+    defaultShadows = false;
+    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.reset();
+        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.pending = false;
-        this.success = false;
+        this.#revokeIfBlobURL(this.cachedUrl);
+        this.url = null
+        this.cachedUrl = null;
+        this.intensity = this.defaultIntensity;
+        this.shadows = this.defaultShadows;
+        this.timeStamp = null;
+        this.valid = false;
     }
-    setValues(url, intensity, shadows, timeStamp) {
+
+    /**
+     * 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;
-    }
-    setSuccess(success = false) {
-        if (success) {
-            this.success = true;
-        } else {
-            this.success = false;
+        if (cachedUrl !== undefined) {
+            this.valid = typeof cachedUrl === "string" && cachedUrl.length > 0 ? false : this.valid;
         }
     }
-    setPending() {
-        this.pending = true;
-        this.success = false;
-    }
-    get isPending() {
-        return this.pending === true;
-    }
-    get isSuccess() {
-        return this.success === true;
-    }
 }