@preference-sl/pref-viewer 3.0.0-beta.0 → 3.0.0-beta.1

package/README.md

@@ -46,7 +46,7 @@ While AR waits for floor placement (including `preview`), `getDebugInfo().ar.dia
 
 On eligible Safari, the AR control uses the existing XR appearance and position. The viewer prepares USDZ after model/material loading; the control becomes usable when that preparation finishes. Updates invalidate the previous file. A failed preparation offers a retry through the same control. No new public method or configuration is required, and the existing USDZ download methods remain downloads.
 
-The link uses `rel="ar"`, `download="model.usdz"` and a `model/vnd.usdz+zip` Blob URL, so its native navigation runs directly on the user tap. Only model meshes with supported materials and current visibility are exported. Environment and viewer overlays are excluded. Babylon's exporter currently loads its `fflate` helper from `https://unpkg.com/fflate@0.8.2` when that global is absent; the host's network/CSP must permit that existing exporter dependency.
+The link uses `rel="ar"`, `download="model.usdz"` and a `model/vnd.usdz+zip` Blob URL with the `#allowsContentScaling=0` fragment, so its native navigation runs directly on the user tap and Quick Look keeps the authored real-world size (no pinch scaling, as on Android WebXR). Only model meshes with supported materials and current visibility are exported. Environment and viewer overlays are excluded. Physical transmission glass is exported with an equivalent alpha opacity, because USDZ has no transmission. The viewer bundles the `fflate` helper the exporter needs, so no request to `unpkg.com` is made.
 
 Manual iOS Quick Look validation has been reported: its AR button remains usable even when the Babylon 3D view is empty. The empty scene/model failure has also been reproduced on an iPhone and remains unresolved; Quick Look validation does not establish successful in-page 3D rendering. Device/browser versions and itemized scale, glass, texture, close/reopen, iPad and production-iframe results were not supplied, so those details remain unconfirmed. Safari remote inspection is unavailable in the current test setup because no macOS system is available. An iframe must permit the browser's native AR/navigation behavior; no automatic top-level redirect or parent-message protocol is added. Used Blob URLs are retained through model replacement/detach until an observed browser return; if Safari emits no return signal, their lifetime ends with the document.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "3.0.0-beta.0",
+    "version": "3.0.0-beta.1",
     "description": "Web Component to preview GLTF models with Babylon.js",
     "author": "Alex Moreno Palacio <amoreno@preference.es>",
     "scripts": {
@@ -45,6 +45,7 @@
         "@panzoom/panzoom": "^4.6.2",
         "babylonjs-gltf2interface": "^9.11.0",
         "buffer": "^6.0.3",
+        "fflate": "0.8.3",
         "idb": "^8.0.3",
         "is-svg": "^6.1.0",
         "jszip": "^3.10.1",
@@ -59,7 +60,6 @@
         "clean-webpack-plugin": "^4.0.0",
         "draco3dgltf": "1.5.7",
         "esbuild": "^0.25.10",
-        "fflate": "0.8.3",
         "http-server": "^14.1.1",
         "jsdom": "^26.1.0",
         "standard-version": "^9.5.0",

package/src/babylonjs-controller.js

@@ -1,10 +1,14 @@
 import { ArcRotateCamera, AssetContainer, BRDFTextureTools, Camera, Color3, Color4, CubeTexture, DefaultRenderingPipeline, DirectionalLight, Engine, FreeCamera, HDRCubeTexture, HemisphericLight, IblShadowsRenderPipeline, ImageProcessingConfiguration, LoadAssetContainerAsync, Material, Matrix, PBRMaterial, PointerEventTypes, PointLight, RenderTargetTexture, Scene, ShadowGenerator, SpotLight, SSAORenderingPipeline, Texture, Tools, UniversalCamera, Vector3, WebXRDefaultExperience, WebXRSessionManager, WebXRState, WhenTextureReadyAsync } from "@babylonjs/core";
 import BabylonJSARPlacement from "./babylonjs-ar-placement.js";
+import BabylonJSARGlass from "./babylonjs-ar-glass.js";
 import { DracoCompression } from "@babylonjs/core/Meshes/Compression/dracoCompression.js";
 import "@babylonjs/loaders";
 import "@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression.js";
 import { USDZExportAsync, GLTF2Export } from "@babylonjs/serializers";
 import JSZip from "jszip";
+// Browser build of fflate: the package's default export map resolves to its Node flavour under
+// esbuild's `platform: node`, which imports `createRequire` from "module" and breaks in browsers.
+import * as fflate from "fflate/browser";
 
 import GLTFResolver from "./gltf-resolver.js";
 import { MaterialData } from "./pref-viewer-3d-data.js";
@@ -125,6 +129,7 @@ export default class BabylonJSController {
     #arPlacement = null;
     #xrGeneration = 0;
     #quickLookAction = null;
+    #quickLookGlass = new BabylonJSARGlass();
     #quickLookLoads = 0;
     #quickLookValid = { model: false, materials: true };
     #canvasResizeObserver = null;
@@ -1213,7 +1218,37 @@ export default class BabylonJSController {
         }
         // AssetContainer contains only model meshes; applied materials and world transforms are retained.
         // No environment, XR ground, ViewCube or utility-scene overlays enter this export.
-        void this.#quickLookAction.update(() => USDZExportAsync(asset, {}, eligible));
+        void this.#quickLookAction.update(() => this.#exportQuickLookUSDZ(asset, eligible));
+    }
+
+    /**
+     * Exposes the bundled fflate module as the global the Babylon USDZ exporter checks for, so it neither
+     * fetches the library from a CDN nor awaits before its synchronous material pass.
+     * @private
+     * @returns {void} Leaves an existing global untouched.
+     */
+    #ensureUSDZDependencies() {
+        globalThis.fflate ??= fflate;
+    }
+
+    /**
+     * Serializes the model to USDZ with physical (transmission) glass converted to alpha opacity, because the
+     * exporter ignores transmission and would write the on-screen opaque alpha. The exporter reads every
+     * material synchronously before its first await, so the adapter is restored right after the call returns
+     * and the live render loop never draws the adapted glass.
+     * @private
+     * @param {import("@babylonjs/core").AssetContainer} asset - Model container to serialize.
+     * @param {function(import("@babylonjs/core").AbstractMesh): boolean} eligible - Mesh filter for the export.
+     * @returns {Promise<Uint8Array>} The serialized USDZ bytes.
+     */
+    #exportQuickLookUSDZ(asset, eligible) {
+        this.#ensureUSDZDependencies();
+        this.#quickLookGlass.sync(asset);
+        try {
+            return USDZExportAsync(asset, {}, eligible);
+        } finally {
+            this.#quickLookGlass.restore();
+        }
     }
 
     /**

package/src/file-storage.js

@@ -35,6 +35,7 @@ import { openDB } from "idb";
  *  - getTimeStamp(uri): Retrieves cached or server Last-Modified timestamp.
  *  - getSize(uri): Gets cached or server file size in bytes.
  *  - getBlob(uri): Retrieves file blob from cache or server.
+ *  - remove(uri): Deletes a cached record (e.g. an unreadable blob) so it is downloaded again next time.
  *  - get(uri): Gets file from cache with automatic server sync and cache versioning.
  *  - put(uri): Stores file from server in IndexedDB cache.
  *  - dispose(): Closes the active IndexedDB handle held by the instance.
@@ -698,6 +699,20 @@ export default class FileStorage {
         return storedFile ? URL.createObjectURL(storedFile.blob) : (await this.#getServerFileTimeStamp(uri)) ? uri : false;
     }
 
+    /**
+     * Removes a cached record so the next access downloads the file again.
+     * Used when a stored blob turns out to be unreadable (WebKit can abort IndexedDB writes and leave a broken record).
+     * @public
+     * @param {String} uri - File URI (record key).
+     * @returns {Promise<number>} Number of requested deletions (0 when IndexedDB is unavailable).
+     */
+    async remove(uri) {
+        if (!this.#supported || !uri) {
+            return 0;
+        }
+        return this.#deleteKeys([uri]);
+    }
+
     /**
      * Get the cached or server Last-Modified timestamp for a file.
      * @public

package/src/gltf-resolver.js

@@ -10,7 +10,8 @@ import { closeDb, initDb, loadModel } from "./gltf-storage.js";
  *  - Normalizes and replaces asset URIs with resolved URLs from FileStorage.
  *  - Handles cache validation using asset size and timestamp to avoid unnecessary reloads.
  *    Callers may opt into an explicit unchanged marker to distinguish cache hits from unavailable content.
- *  - Tracks generated object URLs so callers can revoke them after Babylon finishes loading.
+ *  - Tracks generated object URLs (used for .gltf dependencies) so callers can revoke them after Babylon finishes loading.
+ *  - Hands cached remote .glb files to Babylon as File objects (no blob: URL, which fails on iOS Safari), falling back to the server URL when the cached blob is missing or empty.
  *  - Provides methods for initializing storage, decoding assets, and preparing sources for viewer components.
  *
  * Usage:
@@ -218,6 +219,72 @@ export default class GLTFResolver {
         await Promise.all(promisesArray);
     }
 
+    /**
+     * Resolves a remote .glb URL into the source handed to Babylon.
+     * @private
+     * @param {string} url - Absolute or relative URL of the .glb asset.
+     * @returns {Promise<File|string>} A File holding the cached bytes, or the original URL when no readable cached blob exists.
+     * @description
+     *   - The cached blob is read into memory here, so Babylon receives a File backed by plain bytes. This avoids both
+     *     the XHR over a blob: URL (status 0 on iOS Safari) and FileReader on an IndexedDB blob that iOS cannot read.
+     *   - A missing or empty cached blob (WebKit can abort IndexedDB writes leaving empty records) falls back to the server URL.
+     *   - A cached blob whose bytes cannot be read, or whose read does not settle within `CACHE_READ_TIMEOUT_MS`
+     *     (iOS Safari can hang on a blob left by an aborted IndexedDB write), is purged from the cache without
+     *     waiting for the purge, and this load falls back to the server URL so the load always completes.
+     *   - No object URL is created, so there is nothing to revoke.
+     */
+    async #getGlbSource(url) {
+        let bytes = null;
+        let type = "";
+        try {
+            bytes = await GLTFResolver.#withTimeout((async () => {
+                const blob = await this.#fileStorage.getBlob(url);
+                if (!blob || !(blob.size > 0)) {
+                    return undefined;
+                }
+                type = blob.type || "";
+                return blob.arrayBuffer();
+            })(), GLTFResolver.CACHE_READ_TIMEOUT_MS);
+        } catch (error) {
+            bytes = null;
+        }
+        if (bytes === undefined) {
+            return url;
+        }
+        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 url;
+        }
+        const name = url.split(/[?#]/)[0].split("/").pop() || "file.glb";
+        return new File([bytes], name, { type: type || "model/gltf-binary" });
+    }
+
+    /**
+     * Upper bound for reading a cached .glb out of IndexedDB before giving up on the cache.
+     * @public
+     * @static
+     * @type {number}
+     */
+    static CACHE_READ_TIMEOUT_MS = 5000;
+
+    /**
+     * Races a promise against a timeout.
+     * @private
+     * @static
+     * @param {Promise<T>} promise - Work to bound.
+     * @param {number} ms - Milliseconds before rejecting with a timeout error.
+     * @returns {Promise<T>} The promise result, or a rejection when the timeout elapses first.
+     * @template T
+     */
+    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));
+    }
+
     /**
      * Revoke browser object URLs and clear the provided list.
      * @public
@@ -263,6 +330,7 @@ export default class GLTFResolver {
      *   - 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.
+     *   - For remote .glb files, source is a File built from the cached blob, or the server URL string when the cached blob is missing or empty.
      *   - Returns the prepared source, size, timestamp, extension, metadata, and objectURLs for further processing.
      *   - The caller owns revoking returned objectURLs after the loader finishes consuming them.
      */
@@ -332,10 +400,7 @@ export default class GLTFResolver {
                     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);
-                    }
+                    source = await this.#getGlbSource(source);
                 }
             }
         }

package/src/quick-look-action.js

@@ -8,6 +8,15 @@ import I18n from "./localization/i18n.js";
  * Call dispose() when the owning viewer is torn down.
  */
 export default class QuickLookAction {
+    /**
+     * URL fragment appended to the prepared USDZ link; AR Quick Look parses it as viewer options.
+     * `allowsContentScaling=0` disables pinch scaling so the model keeps its authored real-world size.
+     * @public
+     * @static
+     * @type {string}
+     */
+    static QUICK_LOOK_FRAGMENT = "allowsContentScaling=0";
+
     #anchor;
     #style;
     #window;
@@ -234,7 +243,9 @@ export default class QuickLookAction {
                     type: "model/vnd.usdz+zip"
                 });
                 this.#url = this.#urlAPI.createObjectURL(blob);
-                this.#anchor.href = this.#url;
+                // Quick Look reads the fragment: content scaling off keeps the authored 1:1 metre scale,
+                // matching the Android WebXR path. The bare URL is kept for revocation.
+                this.#anchor.href = `${this.#url}#${QuickLookAction.QUICK_LOOK_FRAGMENT}`;
                 this.#anchor.dataset.state = "ready";
                 this.#anchor.setAttribute("aria-disabled", "false");
             } catch (error) {