@preference-sl/pref-viewer 3.1.0-beta.3 → 3.1.0-beta.4

package/README.md

@@ -591,7 +591,7 @@ The model's transmissive glass (`KHR_materials_transmission`, as authored by the
 | `.env` | Prefiltered Babylon environment (`CubeTexture.CreateFromPrefilteredData`) | No prefiltering in the browser; a 4K environment is typically under 1 MB. |
 | anything else | Radiance HDR (`HDRCubeTexture`) | Prefiltered on load, which costs time and memory for large files. |
 
-Either file is downloaded once, cached in IndexedDB, and reused across reloads. The cached bytes reach Babylon as an in-memory file, never as a `blob:` URL: iOS WebKit answers requests to such URLs with status 0, and the environment then never became ready, so the 3D load never finished. A cached record that is empty or cannot be read within 5 s is purged and the server URL is used for that load.
+Either file is downloaded once, cached in IndexedDB, and reused across reloads. The cached bytes reach Babylon as an in-memory file, never as a `blob:` URL: iOS WebKit answers requests to such URLs with status 0, and the environment then never became ready, so the 3D load never finished. A cached record that is empty or cannot be read within 5 s is purged and the server URL is used for that load; a first download that does not answer within 5 s also falls back to the server URL instead of leaving the scene without an environment. File names are reduced to a URL-safe alphabet, so spaces, `%` and accents in the original name are harmless.
 
 Directional and spot lights that come with the scene glTF (`KHR_lights_punctual`) cast shadows when `render.shadowsEnabled` is `true` and `ibl.shadows` is off, alongside the built-in light's. Every scene and model mesh casts unless its node sets `extras.castShadows: false`, and receives unless it sets `extras.receiveShadows: false`. A light's shadow darkness comes from its node's `extras.shadowDarkness`, from `0` (black) to `1` (no shadow), and is `0.5` when absent:
 

package/package.json

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

package/src/babylonjs-ar-glass.js

@@ -69,7 +69,7 @@ export default class BabylonJSARGlass {
         sub.isRefractionEnabled = false;
         sub.isTranslucencyEnabled = false;
         const authored = linked ? null : MaterialUtils.authoredGlassAlpha(material);
-        material.alpha = authored !== null && authored < 1
+        material.alpha = authored !== null && authored > 0 && authored < 1
             ? authored
             : (linked ? 1 : alpha) * Math.max(BabylonJSARGlass.#MIN_GLASS_OPACITY,
                 1 - transmission * BabylonJSARGlass.#TRANSMISSION_REDUCTION);

package/src/babylonjs-controller.js

@@ -1651,7 +1651,7 @@ export default class BabylonJSController {
      * Lifecycle implemented here:
      * 1. If `options.ibl.cachedUrl` exists, create `HDRCubeTexture` from it (a prefiltered `CubeTexture` when `options.ibl.url` is a `.env`).
      * 2. Wait for readiness, clone it into `#hdrTexture` for reuse.
-     * 3. Call `options.ibl.consumeCachedUrl(true)` to revoke temporary object URLs and clear `cachedUrl`.
+     * 3. Call `options.ibl.consumeCachedUrl(true)` to release the temporary `file:` source and clear `cachedUrl`.
      * 4. On following reloads, if `options.ibl.valid === true` and no `cachedUrl` is present, use `#hdrTexture.clone()`.
      */
     async #initializeEnvironmentTexture() {
@@ -1664,7 +1664,7 @@ export default class BabylonJSController {
         if (this.#options.ibl?.cachedUrl) {
             const hdrTextureURI = this.#options.ibl.cachedUrl;
             if (/\.env$/i.test(String(this.#options.ibl.url ?? "").split(/[?#]/)[0])) {
-                // The cached file is a blob: URL with no extension, so the loader is told it is a .env.
+                // The cached file is a file: URL whose name may not end in .env, so the loader is told it is a .env.
                 hdrTexture = CubeTexture.CreateFromPrefilteredData(hdrTextureURI, this.#scene, ".env");
             } else {
                 const envTextureSize = BabylonJSController.config.quality.environmentTextureSize || 1024;

package/src/ibl-source-resolver.js

@@ -9,6 +9,11 @@ import FileStorage from "./file-storage.js";
  * 3D load never finished. Like `GLTFResolver` does for `.glb` files, the cached bytes are read here into memory and
  * handed to Babylon as a `File` through its `file:` scheme (`FilesInputStore`), so no XHR touches a blob. A record
  * that is empty or cannot be read in time is purged and the server URL is used instead, so the load always completes.
+ * The same goes for a cache read-through that does not answer in time (a slow first download): Babylon then loads
+ * the server URL itself instead of the scene being left without an environment.
+ *
+ * File names are reduced to a URL-safe alphabet, because Babylon runs `decodeURIComponent` on the `file:` URL before
+ * looking the name up and a space, `%` or accent in the original file name would otherwise miss the store.
  *
  * Every resolution registers its own file name; the owner releases it with `release` once Babylon has consumed it.
  */
@@ -26,6 +31,8 @@ export default class IBLSourceResolver {
     static CACHE_READ_TIMEOUT_MS = 5000;
 
     /**
+     * Creates a resolver bound to one cache.
+     * @public
      * @param {FileStorage} [fileStorage] - Cache to read from; defaults to the viewer's shared store.
      */
     constructor(fileStorage = new FileStorage("PrefViewer", "Files")) {
@@ -37,15 +44,16 @@ export default class IBLSourceResolver {
      * @public
      * @param {string} url - Server URL of the `.env` or `.hdr` file.
      * @returns {Promise<{cachedUrl: string, timeStamp: string|null}|false>} The `file:` source of the in-memory copy
-     *   (or the server URL when the cache cannot serve it) with the record's time stamp, or false when the file is
-     *   unavailable both in the cache and on the server.
+     *   (or the server URL when the cache cannot serve it in time) with the record's time stamp, or false when the
+     *   file is unavailable both in the cache and on the server. Every `file:` source returned must reach `release`.
      */
     async resolve(url) {
         let record;
         try {
             record = await IBLSourceResolver.#withTimeout(this.#fileStorage.get(url), IBLSourceResolver.CACHE_READ_TIMEOUT_MS);
-        } catch {
-            return false;
+        } catch (error) {
+            // A slow read-through is not a missing file: let Babylon download the server URL itself.
+            return error?.timedOut === true ? { cachedUrl: url, timeStamp: null } : false;
         }
         if (!record || !record.blob) {
             return false;
@@ -64,8 +72,7 @@ export default class IBLSourceResolver {
             void Promise.resolve(this.#fileStorage.remove(url)).catch(() => {});
             return { cachedUrl: url, timeStamp };
         }
-        const baseName = url.split(/[?#]/)[0].split("/").pop() || "environment";
-        const name = `${IBLSourceResolver.#FILE_PREFIX}${++IBLSourceResolver.#sequence}-${baseName}`;
+        const name = `${IBLSourceResolver.#FILE_PREFIX}${++IBLSourceResolver.#sequence}-${IBLSourceResolver.#safeBaseName(url)}`;
         FilesInputStore.FilesToLoad[name.toLowerCase()] = new File([bytes], name, { type: record.blob.type || "" });
         return { cachedUrl: `file:${name}`, timeStamp };
     }
@@ -83,24 +90,51 @@ export default class IBLSourceResolver {
             return;
         }
         if (cachedUrl.startsWith("file:")) {
-            delete FilesInputStore.FilesToLoad[decodeURIComponent(cachedUrl.slice("file:".length)).toLowerCase()];
+            const name = cachedUrl.slice("file:".length);
+            let decoded = name;
+            try {
+                decoded = decodeURIComponent(name);
+            } catch {
+                // Not percent-encoded: the raw name is the key.
+            }
+            delete FilesInputStore.FilesToLoad[decoded.toLowerCase()];
         } else if (cachedUrl.startsWith("blob:")) {
             URL.revokeObjectURL(cachedUrl);
         }
     }
 
+    /**
+     * Reduces the last path segment of a URL to letters, digits, dot, underscore and dash, so the name survives
+     * Babylon's `decodeURIComponent` of `file:` URLs unchanged.
+     * @private
+     * @static
+     * @param {string} url - Server URL of the environment file.
+     * @returns {string} Safe, non-empty base name.
+     */
+    static #safeBaseName(url) {
+        const segment = url.split(/[?#]/)[0].split("/").pop() || "";
+        let decoded = segment;
+        try {
+            decoded = decodeURIComponent(segment);
+        } catch {
+            // Keep the raw segment; the replacement below removes the stray percent sign.
+        }
+        const safe = decoded.normalize("NFD").replace(/[\u0300-\u036f]/g, "").replace(/[^A-Za-z0-9._-]+/g, "_");
+        return safe.replace(/^_+|_+$/g, "") || "environment";
+    }
+
     /**
      * Bounds a cache read so an IndexedDB transaction that never settles cannot block the load.
      * @private
      * @static
      * @param {Promise<any>} promise - Read to bound.
      * @param {number} ms - Time allowed before rejecting.
-     * @returns {Promise<any>} The read's result, or a rejection after `ms`.
+     * @returns {Promise<any>} The read's result, or a rejection after `ms` whose error has `timedOut === true`.
      */
     static #withTimeout(promise, ms) {
         let timer = null;
         const timeout = new Promise((resolve, reject) => {
-            timer = setTimeout(() => reject(new Error(`Cache read timed out after ${ms}ms`)), ms);
+            timer = setTimeout(() => reject(Object.assign(new Error(`Cache read timed out after ${ms}ms`), { timedOut: true })), ms);
         });
         return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
     }

package/src/material-utils.js

@@ -58,6 +58,9 @@ export default class MaterialUtils {
      * 1, raising the dielectric F0 and re-enabling the over-alpha reflections lets the environment
      * show up on the glass while transmission keeps it see-through.
      *
+     * Before raising the alpha, the alpha the SDK authored is stored once in the material metadata so the
+     * AR adapter can restore the authored see-through look in Quick Look / WebXR (see `authoredGlassAlpha`).
+     *
      * Only physical glass (see `isPrefViewerPhysicalGlassMaterial`) is touched; `transparencyMode`
      * and `subSurface` are left as authored so the glass stays in the transparent pass.
      * @public

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

@@ -386,7 +386,7 @@ export class CameraData {
  *  - 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`.
+ *    `consumeCachedUrl(true)` to release the temporary `file:` source, set `cachedUrl` to null, and keep `valid=true`.
  *  - Call `reset()` to clear the current IBL environment and restore default intensity/shadows.
  */
 export class IBLData {
@@ -418,7 +418,7 @@ export class IBLData {
      * @param {string|null|undefined} url Cached source to release when applicable.
      * @returns {void}
      */
-    #revokeIfBlobURL(url) {
+    #releaseSource(url) {
         IBLSourceResolver.release(url);
     }
 
@@ -428,7 +428,7 @@ export class IBLData {
      * @returns {void}
      */
     reset() {
-        this.#revokeIfBlobURL(this.cachedUrl);
+        this.#releaseSource(this.cachedUrl);
         this.url = null
         this.cachedUrl = null;
         this.intensity = this.defaultIntensity;
@@ -439,14 +439,14 @@ export class IBLData {
 
     /**
      * Consumes the temporary cached URL after Babylon texture creation.
-     * Revokes the URL when it is a `blob:` object URL, clears `cachedUrl`,
+     * Releases the source (a `file:` entry or a legacy `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.#releaseSource(this.cachedUrl);
         this.cachedUrl = null;
         this.valid = !!valid;
     }
@@ -457,7 +457,7 @@ export class IBLData {
      * 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 {string|null|undefined} cachedUrl Loadable source from `IBLSourceResolver` (a `file:` source or the server URL; a legacy `blob:` URL is also released).
      * @param {number|undefined} intensity IBL intensity.
      * @param {boolean|undefined} shadows Shadow toggle for IBL path.
      * @param {string|null|undefined} timeStamp Last-modified marker.
@@ -465,7 +465,7 @@ export class IBLData {
      */
     setValues(url, cachedUrl, intensity, shadows, timeStamp) {
         if (cachedUrl !== undefined && cachedUrl !== this.cachedUrl) {
-            this.#revokeIfBlobURL(this.cachedUrl);
+            this.#releaseSource(this.cachedUrl);
         }
         this.url = url !== undefined ? url : this.url;
         this.cachedUrl = cachedUrl !== undefined ? cachedUrl : this.cachedUrl;
@@ -476,4 +476,35 @@ export class IBLData {
             this.valid = typeof cachedUrl === "string" && cachedUrl.length > 0 ? false : this.valid;
         }
     }
+
+    /**
+     * Applies freshly resolved IBL options and tells whether the environment must be reloaded.
+     * A `null` `url` or `cachedUrl` clears the environment. When nothing differs from the current state, the
+     * `cachedUrl` the caller just resolved is released here, so an in-memory copy registered for nothing never
+     * outlives the call. Otherwise ownership of `cachedUrl` passes to this state until it is consumed or replaced.
+     * @public
+     * @param {object} [resolved] Resolved IBL options; `undefined` fields keep the current value.
+     * @param {string|null} [resolved.url] Source URL identifier, or `null` to clear the environment.
+     * @param {string|null} [resolved.cachedUrl] Loadable source produced by `IBLSourceResolver`, or `null`.
+     * @param {string|null} [resolved.timeStamp] Source modification marker.
+     * @param {boolean} [resolved.shadows] IBL shadow toggle.
+     * @param {number} [resolved.intensity] IBL intensity.
+     * @returns {boolean} True when the state changed and the environment must be reloaded.
+     */
+    applyResolved({ url, cachedUrl, timeStamp, shadows, intensity } = {}) {
+        const needUpdate = url !== undefined && url !== this.url ||
+            timeStamp !== undefined && timeStamp !== this.timeStamp ||
+            shadows !== undefined && shadows !== this.shadows ||
+            shadows === undefined && this.shadows !== this.defaultShadows ||
+            intensity !== undefined && intensity !== this.intensity ||
+            intensity === undefined && this.intensity !== this.defaultIntensity;
+        if (!needUpdate) {
+            this.#releaseSource(cachedUrl);
+        } else if (url === null || cachedUrl === null) {
+            this.reset();
+        } else {
+            this.setValues(url, cachedUrl, intensity, shadows, timeStamp);
+        }
+        return needUpdate;
+    }
 }

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

@@ -429,6 +429,8 @@ export default class PrefViewer3D extends HTMLElement {
      * This allows updating other IBL properties (such as intensity or shadows) without requiring a new URL.
      * If `options.ibl.url` is explicitly provided as `null` (or resolves to an unavailable URL), it is treated as a request to
      * clear the current IBL environment, and the IBL state is reset so Babylon can remove the environment map.
+     * The cached environment is resolved by `IBLSourceResolver` into a `file:` source; the comparison and the release of a
+     * source that turned out not to be needed are delegated to `IBLData.applyResolved`, so repeated identical options leave nothing behind.
      * @private
      * @param {object} options - Options payload that may contain an `ibl` block with url, intensity, or shadow flags.
      * @returns {Promise<boolean>} Resolves to true when any IBL property differs from the cached state, otherwise false.
@@ -467,21 +469,7 @@ export default class PrefViewer3D extends HTMLElement {
             intensity = options.ibl.intensity;
         }
 
-        const needUpdate = url !== undefined && url !== iblState.url ||
-            timeStamp !== undefined && timeStamp !== iblState.timeStamp ||
-            shadows !== undefined && shadows !== iblState.shadows ||
-            shadows === undefined && iblState.shadows !== iblState.defaultShadows ||
-            intensity !== undefined && intensity !== iblState.intensity ||
-            intensity === undefined && iblState.intensity !== iblState.defaultIntensity;
-        if (needUpdate) {
-            if (url === null || cachedUrl === null) {
-                iblState.reset();
-            } else {
-                iblState.setValues(url, cachedUrl, intensity, shadows, timeStamp);
-            }
-        }
-
-        return needUpdate;
+        return iblState.applyResolved({ url, cachedUrl, timeStamp, shadows, intensity });
     }
 
     /**