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

package/README.md

@@ -38,7 +38,7 @@ VR uses the `local-floor` reference space without teleportation, controller sele
 
 Android WebXR preserves the glTF's authored metre dimensions, including existing unit-conversion transforms. It never fits the model to the screen or permits pinch scaling. Assets must encode their dimensions in metres and orient their interior toward the viewer's existing Inner (+Z) direction; the viewer cannot infer an interior face or correct arbitrary source units. The upstream exporter owns those asset conventions.
 
-During Android WebXR AR, model materials using physical transmission/refraction or translucency temporarily use alpha blending so the camera background can show through the glass. This is a scalar approximation: full transmission uses 0.35 opacity, combined with existing geometric opacity; linked-refraction alpha is interpreted as transmission rather than geometric opacity. Colors, textures and reflection parameters remain unchanged, but physical camera refraction, blur and transmission texture masks are not reproduced. Opaque and existing ordinary alpha-transparent materials are left alone. Original glass values are restored on exit/cancellation, model or material replacement and teardown; normal 3D and Quick Look preparation outside WebXR retain their original materials. The fallback also applies to the no-floor preview. Shared material objects are adapted once and restored together. Real Android glass appearance still requires a device check.
+During Android WebXR AR, model materials using physical transmission/refraction or translucency temporarily use alpha blending so the camera background can show through the glass. This is a scalar approximation: glass the viewer tuned for the web look keeps its authored base color alpha as the AR opacity (the SDK's window glass, `0.15`), so it reads like the 3D view; other physical glass uses 0.35 opacity for full transmission, combined with existing geometric opacity; linked-refraction alpha is interpreted as transmission rather than geometric opacity. The same conversion is applied to the USDZ prepared for iOS Quick Look. Colors, textures and reflection parameters remain unchanged, but physical camera refraction, blur and transmission texture masks are not reproduced. Opaque and existing ordinary alpha-transparent materials are left alone. Original glass values are restored on exit/cancellation, model or material replacement and teardown; normal 3D and Quick Look preparation outside WebXR retain their original materials. The fallback also applies to the no-floor preview. Shared material objects are adapted once and restored together. Real Android glass appearance still requires a device check.
 
 On AR entry, the virtual environment is hidden. If no qualifying floor is available, the first finite native camera pose centres the preview two metres along its view ray, retaining the authored dimensions, with Inner facing the phone horizontally. The preview retains its initial world position and yaw instead of following the phone, and cannot be dragged. It is not a verified physical anchor or calibrated 1:1 measurement; erroneous native camera motion can still change its apparent size and position. Pending, failed or empty hit tests do not prevent this preview. A missing native camera pose still prevents initial placement. When a native horizontal-plane hit below the phone becomes available and the phone has a usable horizontal heading, the preview transitions to floor placement: its bottom centre is placed on that height, with its phone-facing orientation corrected by the minimum yaw to align model axis lines with the detected floor axes (nearest multiple of 90 degrees, at most 45 degrees correction). The preferred initial distance is three horizontal metres ahead. Optional native plane detection supplies a floor contour; the viewer checks the full horizontal bounding footprint at its authored scale and initial yaw. If it cannot fit at three metres, it uses the farthest fitting centre on the same forward segment up to three metres. If contours are unavailable/unusable or no full fit exists, it provisionally places the model at three metres without a fit guarantee. Later contour changes never reposition an already placed model. This transition can move the model visibly. It stays in world space as the user moves. The detected horizontal plane pose supplies the grid axes independently of contour-fit availability: a contour containing the accepted hit takes priority, otherwise the horizontal pose below the camera nearest in height to that hit is used (horizontal proximity breaks ties). Without a usable native pose, the X/Z axes of the WebXR tracking reference space provide the reported fallback. Pose-only orientation never changes the retained floor height or guarantees that the footprint fits. Diagnostics report `floorAlignmentSource`, `floorAlignmentStatus`, `floorAlignmentYaw` and `floorAlignmentHeightDifference`. The grid is frozen for model initial placement and gesture feedback; later camera/contour changes do not re-snap the model. Touch the model and drag with one finger to translate it on the retained floor plane, keeping the grab offset. A short tap outside the model places its bottom centre at the tapped point on that plane. Placement commits on release; moving the finger by more than one degree of ray direction cancels an off-model tap, even if it returns to its starting point. Adding a second tracked finger cancels translation or a pending floor tap and starts two-finger rotation around the vertical bottom-centre axis. Rotate the two fingers to change yaw (the rotation sense is inverted from the preceding implementation); pinching never changes scale. The bottom anchor stays fixed. Lifting either finger, a third finger or lost input cancels rotation; lift all fingers before starting another translation. This requires the Android runtime to expose both screen input sources. Fresh surface hits are not required after floor detection: other-height surfaces do not change the retained height. Missing/invalid input tracking, rays parallel to the floor or intersections behind the camera retain the last placement. This uses the mathematical plane at the observed height and does not verify its physical extent or rule out obstacles. WebXR does not universally distinguish a floor from a table. A contour fit checks the reported approximate surface, not obstacles or physical room boundaries; provisional placement provides no contour-fit guarantee. Leaving AR restores the authored model transforms and environment. `getDebugInfo().ar` reports placement state, metre units, initial distance, position and drag state. The diagnostic state `preview` distinguishes the camera-based fallback from `placed` on a detected floor; the fallback does not claim a detected floor or solve native calibration/tracking failures. Large models may extend beyond the viewport because their authored scale is preserved. The no-floor preview remains centred two metres along the initial camera ray.
 
@@ -580,7 +580,7 @@ Render settings are persisted in `localStorage` under the `pref-viewer/render-se
 
 The showroom daylight background uses a shared linear HDR color calibrated with exposure and ACES tone mapping for the current light studio gray target, `#d9d9d9`, in a scene-less view. Both the static look and time-of-day cycle use this same daylight value; the cycle retains its dark night endpoint. Scene geometry can cover the background. The internal `BabylonJSController.config.look.showroom.backgroundDay` value is not a public background-color option and must be recalibrated if tone mapping or exposure changes.
 
-The model's transmissive glass (`KHR_materials_transmission`, as authored by the SDK) also carries a base color alpha of `0.15`, which would multiply its reflection away and leave it flat grey. The viewer sets that alpha to `1` and `metallicF0Factor` to `3` (`BabylonJSController.config.look.glass`, internal like the showroom look) so the environment reflection reads while the glass stays see-through through transmission. Glass in the environment glTF is unaffected: it is simplified to alpha blending instead.
+The model's transmissive glass (`KHR_materials_transmission`, as authored by the SDK) also carries a base color alpha of `0.15`, which would multiply its reflection away and leave it flat grey. The viewer sets that alpha to `1` and `metallicF0Factor` to `3` (`BabylonJSController.config.look.glass`, internal like the showroom look) so the environment reflection reads while the glass stays see-through through transmission. The authored alpha is remembered and becomes the glass opacity in native AR (Android WebXR and the iOS Quick Look USDZ), where there is no physical transmission. Glass in the environment glTF is unaffected: it is simplified to alpha blending instead.
 
 ## Environment map and scene lights
 
@@ -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.
+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.
 
 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:
 
@@ -771,7 +771,7 @@ Both ViewCubes use the palette defined once by `PrefViewerViewCubePalette` in `s
 
 Public customization uses the unified [Runtime styles](#runtime-styles) schema. The CSS tokens in `PrefViewerViewCubePalette` and `PrefViewerViewCubeTypography` are internal implementation details projected inside the shadow boundary. Palette defaults are centralized; Canvas resolves the computed internal values and falls back for invalid colors. The optional internal dark palette is not automatically selected or a package-root export.
 
-Keep these rules when changing the renderer: the cube scene stays virtual and its engine stays out of `EngineStore.Instances` while it is alive (otherwise the viewer can create resources on the cube's WebGL context); Babylon input stays detached from the cube canvas (otherwise the cursor and keyboard focus are disturbed); and the engine keeps `loseContextOnDispose` so its WebGL context is released.
+Keep these rules when changing the renderer: the cube scene stays virtual and its engine stays out of `EngineStore.Instances` while it is alive (otherwise the viewer can create resources on the cube's WebGL context); Babylon input stays detached from the cube canvas (otherwise the cursor and keyboard focus are disturbed); and the engine keeps `loseContextOnDispose` so its WebGL context is released. Both the viewer engine and the cube engine request their WebGL context with an explicit `powerPreference: "default"`: Babylon fills in `"high-performance"` when the option is absent, and iOS 18.7 / Safari 26.6.1 on iPhone returns a context that is already lost for that preference, which left the 3D view blank.
 
 ViewCube listener registration, drag handling and hover updates are private instance methods. Region construction, colour parsing and extent interpolation are private static helpers; interpolation progress is passed explicitly. The render menu also encapsulates hue-channel calculation and lighting playback as private methods. Playback uses one callback bound to the menu instance and cancels its scheduled frame on stop or disconnection.
 

package/package.json

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

package/src/babylonjs-ar-glass.js

@@ -42,7 +42,11 @@ export default class BabylonJSARGlass {
 
     /**
      * Snapshots physical glass and switches it to alpha blending without depth occlusion.
-     * Linked refraction uses alpha as inverse transmission, so it is not reused as geometric opacity.
+     * Glass the viewer tuned for the web look (`MaterialUtils.tunePhysicalGlassMaterial`) takes its authored
+     * base alpha as the AR opacity when that alpha is below 1, so it reads like the web view instead of the
+     * 0.35 floor of the transmission approximation; glass authored opaque keeps the approximation.
+     * Linked refraction uses alpha as inverse transmission, so neither the
+     * live nor the authored alpha is reused as geometric opacity there.
      * Retains a disposal observer only while the snapshot is owned; disposed materials are forgotten untouched.
      * @param {import("@babylonjs/core").PBRMaterial} material - Current physical glass not already adapted.
      * @returns {void} Does not allocate/dispose materials or textures or modify color/reflection properties.
@@ -64,8 +68,11 @@ export default class BabylonJSARGlass {
         this.#materials.set(material, saved);
         sub.isRefractionEnabled = false;
         sub.isTranslucencyEnabled = false;
-        material.alpha = (linked ? 1 : alpha) * Math.max(BabylonJSARGlass.#MIN_GLASS_OPACITY,
-            1 - transmission * BabylonJSARGlass.#TRANSMISSION_REDUCTION);
+        const authored = linked ? null : MaterialUtils.authoredGlassAlpha(material);
+        material.alpha = authored !== null && authored < 1
+            ? authored
+            : (linked ? 1 : alpha) * Math.max(BabylonJSARGlass.#MIN_GLASS_OPACITY,
+                1 - transmission * BabylonJSARGlass.#TRANSMISSION_REDUCTION);
         material.transparencyMode = Material.MATERIAL_ALPHABLEND;
         material.disableDepthWrite = true;
         material.forceDepthWrite = false;

package/src/babylonjs-controller.js

@@ -3940,7 +3940,9 @@ export default class BabylonJSController {
         }
         const enabledGeneration = ++this.#xrGeneration;
         this.#configureDracoCompression();
-        this.#engine = new Engine(this.#canvas, true, { alpha: true, stencil: true, preserveDrawingBuffer: false }, true);
+        // powerPreference is explicit: Babylon fills in "high-performance" when it is absent, and iOS 18.7 /
+        // Safari 26.6.1 (iPhone) returns a WebGL2 context that is already lost for that preference.
+        this.#engine = new Engine(this.#canvas, true, { alpha: true, stencil: true, preserveDrawingBuffer: false, powerPreference: "default" }, true);
         this.#engine.disableUniformBuffers = true;
 
         // OPTIMIZATION: Detect hardware tier and apply quality settings

package/src/babylonjs-view-cube-canvas-renderer.js

@@ -87,11 +87,13 @@ export default class BabylonJSViewCubeCanvasRenderer {
 
 
     /**
-     * Options of the default cube Engine (as in PrefSketch, plus loseContextOnDispose). Babylon only calls
-     * WEBGL_lose_context.loseContext() on dispose when loseContextOnDispose is set; without it the cube's WebGL context
-     * would linger until garbage collection, and browsers cap the number of live contexts per page.
+     * Options of the default cube Engine (as in PrefSketch, plus loseContextOnDispose and powerPreference). Babylon only
+     * calls WEBGL_lose_context.loseContext() on dispose when loseContextOnDispose is set; without it the cube's WebGL
+     * context would linger until garbage collection, and browsers cap the number of live contexts per page.
+     * powerPreference is explicit because Babylon fills in "high-performance" otherwise, and iOS 18.7 / Safari 26.6.1
+     * (iPhone) returns a WebGL2 context that is already lost for that preference.
      */
-    static #VIEW_CUBE_ENGINE_OPTIONS = Object.freeze({ alpha: true, antialias: true, premultipliedAlpha: false, stencil: false, loseContextOnDispose: true });
+    static #VIEW_CUBE_ENGINE_OPTIONS = Object.freeze({ alpha: true, antialias: true, premultipliedAlpha: false, stencil: false, loseContextOnDispose: true, powerPreference: "default" });
 
     static #DEFAULT_LABELS = Object.freeze({ right: "Right", left: "Left", bottom: "Bottom", top: "Top", back: "Back", front: "Front" });
 

package/src/ibl-source-resolver.js

@@ -0,0 +1,107 @@
+import { FilesInputStore } from "@babylonjs/core";
+import FileStorage from "./file-storage.js";
+
+/**
+ * Resolves the environment map (`options.ibl.url`) into a source Babylon can load on every browser.
+ *
+ * The cached environment used to reach Babylon as a `blob:` object URL of the IndexedDB record. iOS WebKit answers
+ * an XHR to such a URL with status 0, Babylon retries and gives up, and the texture never becomes ready, so the
+ * 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.
+ *
+ * Every resolution registers its own file name; the owner releases it with `release` once Babylon has consumed it.
+ */
+export default class IBLSourceResolver {
+    static #FILE_PREFIX = "pref-viewer-ibl-";
+    static #sequence = 0;
+    #fileStorage;
+
+    /**
+     * Upper bound for reading a cached environment out of IndexedDB before falling back to the server URL.
+     * @public
+     * @static
+     * @type {number}
+     */
+    static CACHE_READ_TIMEOUT_MS = 5000;
+
+    /**
+     * @param {FileStorage} [fileStorage] - Cache to read from; defaults to the viewer's shared store.
+     */
+    constructor(fileStorage = new FileStorage("PrefViewer", "Files")) {
+        this.#fileStorage = fileStorage;
+    }
+
+    /**
+     * Resolves one environment URL into a loadable source.
+     * @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.
+     */
+    async resolve(url) {
+        let record;
+        try {
+            record = await IBLSourceResolver.#withTimeout(this.#fileStorage.get(url), IBLSourceResolver.CACHE_READ_TIMEOUT_MS);
+        } catch {
+            return false;
+        }
+        if (!record || !record.blob) {
+            return false;
+        }
+        const timeStamp = record.timeStamp ?? null;
+        let bytes = null;
+        if (record.blob.size > 0) {
+            try {
+                bytes = await IBLSourceResolver.#withTimeout(record.blob.arrayBuffer(), IBLSourceResolver.CACHE_READ_TIMEOUT_MS);
+            } catch {
+                bytes = null;
+            }
+        }
+        if (!bytes || bytes.byteLength === 0) {
+            // Fire-and-forget: a hung IndexedDB transaction must not block this load either.
+            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}`;
+        FilesInputStore.FilesToLoad[name.toLowerCase()] = new File([bytes], name, { type: record.blob.type || "" });
+        return { cachedUrl: `file:${name}`, timeStamp };
+    }
+
+    /**
+     * Releases a source produced by `resolve` (or an older `blob:` URL): drops the in-memory file from Babylon's
+     * store or revokes the object URL. Server URLs and empty values are ignored.
+     * @public
+     * @static
+     * @param {string|null|undefined} cachedUrl - Source to release.
+     * @returns {void}
+     */
+    static release(cachedUrl) {
+        if (typeof cachedUrl !== "string") {
+            return;
+        }
+        if (cachedUrl.startsWith("file:")) {
+            delete FilesInputStore.FilesToLoad[decodeURIComponent(cachedUrl.slice("file:".length)).toLowerCase()];
+        } else if (cachedUrl.startsWith("blob:")) {
+            URL.revokeObjectURL(cachedUrl);
+        }
+    }
+
+    /**
+     * 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`.
+     */
+    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);
+        });
+        return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+    }
+}

package/src/material-utils.js

@@ -6,6 +6,7 @@ import { PBRMaterial } from "@babylonjs/core";
  */
 export default class MaterialUtils {
     static #SIMPLIFIED_TRANSMISSION_KEY = "prefViewerSimplifiedTransmission";
+    static #AUTHORED_GLASS_ALPHA_KEY = "prefViewerAuthoredGlassAlpha";
 
     /**
      * Tags a PBR material as having been converted from physical KHR_materials_transmission to simple
@@ -70,6 +71,12 @@ export default class MaterialUtils {
             return false;
         }
 
+        if (MaterialUtils.authoredGlassAlpha(mat) === null && Number.isFinite(mat.alpha)) {
+            mat.metadata = {
+                ...(mat.metadata ?? {}),
+                [MaterialUtils.#AUTHORED_GLASS_ALPHA_KEY]: Math.max(0, Math.min(1, mat.alpha)),
+            };
+        }
         mat.alpha = look?.alpha ?? 1;
         mat.metallicF0Factor = look?.metallicF0Factor ?? 3;
         mat.useSpecularOverAlpha = true;
@@ -77,6 +84,20 @@ export default class MaterialUtils {
         return true;
     }
 
+    /**
+     * Returns the base color alpha the glass was authored with (for example the SDK's `0.15`) before
+     * `tunePhysicalGlassMaterial` raised it for the web look. Native AR has no physical transmission,
+     * so that authored alpha is the opacity that keeps the glass looking like the web view.
+     * @public
+     * @static
+     * @param {import("@babylonjs/core").Material|null|undefined} mat - Material to read.
+     * @returns {number|null} The authored alpha in [0, 1], or null when the material was never tuned.
+     */
+    static authoredGlassAlpha(mat) {
+        const value = mat?.metadata?.[MaterialUtils.#AUTHORED_GLASS_ALPHA_KEY];
+        return Number.isFinite(value) ? value : null;
+    }
+
     /**
      * Returns true when a material should be placed in the transparent rendering group (renderingGroupId=1).
      *

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

@@ -1,3 +1,5 @@
+import IBLSourceResolver from "./ibl-source-resolver.js";
+
 /**
  * ContainerData - Represents state, cache metadata, and update lifecycle for a 3D asset container
  * (for example: model, environment, or materials).
@@ -410,15 +412,14 @@ export class IBLData {
     }
 
     /**
-     * Revokes object URLs (`blob:`) to release browser memory.
+     * Releases a temporary cached source: a `blob:` object URL is revoked and a `file:` source registered by
+     * `IBLSourceResolver` is dropped from Babylon's file store. Server URLs are left alone.
      * @private
-     * @param {string|null|undefined} url URL to revoke when applicable.
+     * @param {string|null|undefined} url Cached source to release when applicable.
      * @returns {void}
      */
     #revokeIfBlobURL(url) {
-        if (typeof url === "string" && url.startsWith("blob:")) {
-            URL.revokeObjectURL(url);
-        }
+        IBLSourceResolver.release(url);
     }
 
     /**

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

@@ -2,7 +2,7 @@ import { CameraData, ContainerData, MaterialData, IBLData } from "./pref-viewer-
 import BabylonJSController from "./babylonjs-controller.js";
 import { PrefViewer3DStyles } from "./styles.js";
 import PrefViewerControlsPresentation from "./pref-viewer-controls-presentation.js";
-import FileStorage from "./file-storage.js";
+import IBLSourceResolver from "./ibl-source-resolver.js";
 
 /**
  * PrefViewer3D - Custom Web Component for interactive 3D visualization and configuration.
@@ -446,12 +446,12 @@ export default class PrefViewer3D extends HTMLElement {
         let intensity = undefined;
 
         if (typeof options.ibl.url === "string" && options.ibl.url.length > 0) {
-            const fileStorage = new FileStorage("PrefViewer", "Files");
-            const newURL = await fileStorage.getURL(options.ibl.url);
-            if (newURL) {
+            // The cached bytes reach Babylon as an in-memory file, never as a blob: URL (iOS WebKit cannot XHR those).
+            const source = await new IBLSourceResolver().resolve(options.ibl.url);
+            if (source) {
                 url = options.ibl.url;
-                cachedUrl = newURL;
-                timeStamp = await fileStorage.getTimeStamp(options.ibl.url);
+                cachedUrl = source.cachedUrl;
+                timeStamp = source.timeStamp;
             } else {
                 url = null;
                 cachedUrl = null;