@preference-sl/pref-viewer 3.1.0-beta.0 → 3.1.0-beta.2

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.
 
@@ -54,6 +54,22 @@ On eligible Safari, the AR control uses the existing XR appearance and position.
 
 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.
 
+#### Host-supplied Quick Look asset
+
+A host that produces the AR asset elsewhere (for example a server-generated USDZ or USD) can hand it to the Quick Look action with `setQuickLookAssetProvider(provider)`. The provider is a function returning `Promise<{ data: Uint8Array | ArrayBuffer | Blob, mimeType?: string, fileName?: string }>`; `mimeType` defaults to `model/vnd.usdz+zip` and `fileName` to `model.usdz`. Pass `null` to clear it. The viewer never learns how the asset is made.
+
+```js
+viewer.setQuickLookAssetProvider(async () => {
+  const response = await fetch("/my-server/ar-model");
+  return { data: await response.arrayBuffer(), mimeType: "model/vnd.usdz+zip", fileName: "model.usdz" };
+});
+```
+
+- While a provider is set, the Quick Look link uses its asset instead of the Babylon USDZ export. It is called each time the link is prepared (after model/material loading and changes), only on the Quick Look route (eligible iOS/iPadOS Safari without WebXR AR).
+- Setting or clearing the provider re-prepares the link when Quick Look is active; a provider set earlier (even before the element is connected) is retained.
+- The ZIP signature check applies only when `mimeType` is `model/vnd.usdz+zip`. Any other MIME type (for example `model/vnd.usd`, or `text/plain` for USDA) is passed through unchanged as the Blob type, with `fileName` as the link's `download` attribute. AR Quick Look officially opens only `.usdz`/`.reality`, so what iOS does with other types is the host's experiment.
+- If the provider throws, rejects or returns empty data, the viewer logs `PrefViewer: Quick Look asset provider failed` with `console.warn` and falls back to its own USDZ export.
+
 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.
 
 ## Installation
@@ -438,6 +454,7 @@ Dialogs opened with `openDialog()`, including the **Ctrl+Alt+D** download dialog
 | `downloadModelGLB()` / `downloadModelGLTF()` / `downloadModelUSDZ()` | Exports the current model. |
 | `downloadSceneGLB()` / `downloadSceneGLTF()` / `downloadSceneUSDZ()` | Exports the current scene/environment. |
 | `downloadModelAndSceneGLB()` / `downloadModelAndSceneGLTF()` / `downloadModelAndSceneUSDZ()` | Exports the combined model and scene. |
+| `setQuickLookAssetProvider(provider \| null)` | Lets the host supply the asset opened by the iOS AR Quick Look action instead of the viewer's client-generated USDZ (for example a file produced by a server). See [AR and VR support](#ar-and-vr-support). |
 
 All viewer dialogs share this priority, including the model-download dialog opened with **Ctrl+Alt+D** while the 3D canvas receives keyboard input. Existing backdrop dismissal remains available: a click over a covered control may close the dialog, but does not also activate that control. Closing the dialog restores access to the underlying controls.
 
@@ -563,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
 
@@ -574,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:
 
@@ -754,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/index.d.ts

@@ -139,6 +139,18 @@ export interface PrefViewerElementClickDetail {
   ids: string[];
 }
 
+/** Asset a host hands to the iOS AR Quick Look action. */
+export interface PrefViewerQuickLookAsset {
+  data: Uint8Array | ArrayBuffer | Blob;
+  /** Defaults to `model/vnd.usdz+zip`; the ZIP signature is checked only for that type. */
+  mimeType?: string;
+  /** Defaults to `model.usdz`; used as the link's `download` attribute. */
+  fileName?: string;
+}
+
+/** Async factory of the Quick Look asset, called each time the Quick Look link is prepared. */
+export type PrefViewerQuickLookAssetProvider = () => Promise<PrefViewerQuickLookAsset>;
+
 /** Optional speed/direction for `startTurnable` / `toggleTurnable`. */
 export interface PrefViewerTurnableOptions {
   speed?: number;
@@ -356,6 +368,13 @@ export declare class PrefViewer extends HTMLElement {
   setAnimationProgress(name: string, progress: number): boolean;
   setAnimationLoop(name: string, loop: boolean): boolean;
 
+  // ── AR Quick Look (iOS) ──
+  /**
+   * Supplies (or clears with `null`) the asset opened by the iOS AR Quick Look action instead of the
+   * viewer's client-generated USDZ. A failing provider falls back to the built-in export with a console warning.
+   */
+  setQuickLookAssetProvider(provider: PrefViewerQuickLookAssetProvider | null): void;
+
   // ── Downloads ──
   downloadModelGLB(): void;
   downloadModelGLTF(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "3.1.0-beta.0",
+    "version": "3.1.0-beta.2",
     "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

@@ -72,6 +72,7 @@ import QuickLookAction from "./quick-look-action.js";
  *  - enable() / disable()
  *  - load(force?) / reloadWithCurrentSettings()
  *  - downloadGLB(content) / downloadGLTF(content) / downloadUSDZ(content)
+ *  - setQuickLookAssetProvider(provider)
  *  - getRenderSettings() / scheduleRenderSettingsReload(settings)
  *  - getDebugInfo()
  *  - setContainerVisibility(name, show)
@@ -133,6 +134,7 @@ export default class BabylonJSController {
     #xrButtons = null;
     #xrGeneration = 0;
     #quickLookAction = null;
+    #quickLookAssetProvider = null;
     #quickLookGlass = new BabylonJSARGlass();
     #quickLookLoads = 0;
     #quickLookValid = { model: false, materials: true };
@@ -1221,6 +1223,7 @@ export default class BabylonJSController {
      * Prepares Quick Look from completed, visible model/material state without changing download helpers.
      * Invalid or absent content invalidates the link. Only supported visible model meshes are serialized;
      * asynchronous export ownership, stale results and preparation errors are handled by QuickLookAction.
+     * The prepared asset comes from the host provider when one is set (see setQuickLookAssetProvider), otherwise from the export.
      * @private
      * @returns {void} Starts preparation without waiting for it or changing public task-queue ordering.
      */
@@ -1248,7 +1251,66 @@ 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(() => this.#exportQuickLookUSDZ(asset, eligible));
+        void this.#quickLookAction.update(() => this.#prepareQuickLookAsset(asset, eligible));
+    }
+
+    /**
+     * Installs or clears the host-supplied provider of the asset opened by the iOS Quick Look action.
+     * The provider is retained even before the Quick Look route exists. While Quick Look is active, changing it
+     * re-prepares the link at once, so clearing returns to the in-browser USDZ export.
+     * @public
+     * @param {?(function(): Promise<{data: (Uint8Array|ArrayBuffer|Blob), mimeType?: string, fileName?: string}>)} provider
+     *   Async asset factory (defaults: MIME `model/vnd.usdz+zip`, file name `model.usdz`), or null to clear.
+     * @returns {void} Ignores any value that is neither a function nor null by clearing the provider.
+     */
+    setQuickLookAssetProvider(provider) {
+        this.#quickLookAssetProvider = typeof provider === "function" ? provider : null;
+        this.#refreshQuickLook();
+    }
+
+    /**
+     * Prepares the Quick Look asset: the host provider's asset when one is set, otherwise (or when the provider
+     * fails or returns no data) the in-browser USDZ export of the current model.
+     * @private
+     * @param {import("@babylonjs/core").AssetContainer} asset - Model container used by the fallback export.
+     * @param {function(import("@babylonjs/core").AbstractMesh): boolean} eligible - Mesh filter for the fallback export.
+     * @returns {Promise<Uint8Array|{data: Uint8Array, mimeType?: string, fileName?: string}>} Asset for QuickLookAction.
+     */
+    async #prepareQuickLookAsset(asset, eligible) {
+        const provider = this.#quickLookAssetProvider;
+        if (provider) {
+            try {
+                return await BabylonJSController.#readQuickLookAsset(provider);
+            } catch (error) {
+                console.warn("PrefViewer: Quick Look asset provider failed", error);
+            }
+        }
+        return this.#exportQuickLookUSDZ(asset, eligible);
+    }
+
+    /**
+     * Invokes a host asset provider and converts its data to bytes.
+     * @private
+     * @static
+     * @param {function(): Promise<{data: (Uint8Array|ArrayBuffer|Blob), mimeType?: string, fileName?: string}>} provider - Host asset factory.
+     * @returns {Promise<{data: Uint8Array, mimeType?: string, fileName?: string}>} Nonempty asset with byte data.
+     * @throws {Error} When the provider rejects, or returns no data or empty/unsupported data.
+     */
+    static async #readQuickLookAsset(provider) {
+        const result = await provider();
+        const raw = result?.data;
+        let data = null;
+        if (raw instanceof Uint8Array) {
+            data = raw;
+        } else if (raw instanceof ArrayBuffer) {
+            data = new Uint8Array(raw);
+        } else if (typeof Blob !== "undefined" && raw instanceof Blob) {
+            data = new Uint8Array(await raw.arrayBuffer());
+        }
+        if (!data || data.length === 0) {
+            throw new Error("PrefViewer: Quick Look asset provider returned no data");
+        }
+        return { data, mimeType: result.mimeType, fileName: result.fileName };
     }
 
     /**
@@ -3878,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.
@@ -51,6 +51,7 @@ import FileStorage from "./file-storage.js";
  *  - downloadModelGLB(): Downloads the current 3D model as a GLB file.
  *  - downloadModelGLTF(): Downloads the current 3D model as a glTF ZIP file.
  *  - downloadModelUSDZ(): Downloads the current 3D model as a USDZ file.
+ *  - setQuickLookAssetProvider(provider): Supplies (or clears) the asset opened by the iOS AR Quick Look action.
  *  - downloadModelAndSceneGLB(): Downloads both the model and scene as a GLB file.
  *  - downloadModelAndSceneGLTF(): Downloads both the model and scene as a glTF ZIP file.
  *  - downloadModelAndSceneUSDZ(): Downloads both the model and scene as a USDZ file.
@@ -102,6 +103,7 @@ export default class PrefViewer3D extends HTMLElement {
     #data = null; // Component data
 
     #babylonJSController = null; // BabylonJSController instance
+    #quickLookAssetProvider = null; // Host asset provider, reapplied to every controller this element creates
 
     /** @returns {"svg"|"canvas"} Per-instance normalized renderer; missing/invalid attributes use Canvas. */
     get viewCubeRenderer() {
@@ -283,6 +285,7 @@ export default class PrefViewer3D extends HTMLElement {
      * Initializes the Babylon controller with asset/option state and the selected visibility-aware cube contract.
      * Supplies current host culture and dispatches measured view-cube-layout events for render-menu positioning.
      * Starts asynchronous engine initialization without waiting for asset loading.
+     * Reapplies any retained Quick Look asset provider to the new controller before it starts.
      * @private
      * @returns {void}
      */
@@ -303,6 +306,7 @@ export default class PrefViewer3D extends HTMLElement {
              */
             onLayout: (offset, height) => this.dispatchEvent(new CustomEvent("view-cube-layout", { detail: { offset, height } })),
         });
+        this.#babylonJSController.setQuickLookAssetProvider(this.#quickLookAssetProvider);
         this.#babylonJSController.enable();
 
     }
@@ -442,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;
@@ -875,6 +879,20 @@ export default class PrefViewer3D extends HTMLElement {
         this.#babylonJSController.downloadGLTF(1);
     }
 
+    /**
+     * Sets or clears the host-supplied asset opened by the iOS AR Quick Look action instead of the in-browser USDZ export.
+     * The provider is retained across connection cycles, even when set before the element is connected.
+     * @public
+     * @param {?(function(): Promise<{data: (Uint8Array|ArrayBuffer|Blob), mimeType?: string, fileName?: string}>)} provider
+     *   Async asset factory (defaults: MIME `model/vnd.usdz+zip`, file name `model.usdz`), or null to restore the built-in export.
+     *   A failing provider falls back to the built-in export with a console warning.
+     * @returns {void}
+     */
+    setQuickLookAssetProvider(provider) {
+        this.#quickLookAssetProvider = typeof provider === "function" ? provider : null;
+        this.#babylonJSController?.setQuickLookAssetProvider(this.#quickLookAssetProvider);
+    }
+
     /**
      * Downloads the current 3D model as a USDZ file.
      * @public

package/src/pref-viewer.js

@@ -43,6 +43,7 @@ import I18n from "./localization/i18n.js";
  *  - showModel / hideModel / showScene / hideScene: Toggle visibility using the internal task queue for consistent sequencing.
  *  - zoomCenter / zoomExtentsAll / zoomIn / zoomOut: Forward zoom commands to the 2D controller when active.
  *  - downloadModelGLB / downloadModelGLTF / downloadModelUSDZ: Export the loaded model in the requested format.
+ *  - setQuickLookAssetProvider(provider): Supplies (or clears) the asset opened by the iOS AR Quick Look action.
  *  - downloadSceneGLB / downloadSceneGLTF / downloadSceneUSDZ: Export the loaded environment in the requested format.
  *  - downloadModelAndSceneGLB / downloadModelAndSceneGLTF / downloadModelAndSceneUSDZ: Export the combined scene in the requested format.
  *  - openDialog / closeDialog: Manage PrefViewerDialog instances rendered inside the shadow tree.
@@ -115,6 +116,7 @@ export default class PrefViewer extends HTMLElement {
     #wrapper = null;
     #component2D = null;
     #component3D = null;
+    #quickLookAssetProvider = null; // Host asset provider, reapplied to every 3D component this element creates
     #dialog = null;
     #menu3D = null;
 
@@ -394,6 +396,7 @@ export default class PrefViewer extends HTMLElement {
      * Creates and appends the 3D viewer component to the shadow DOM, initially hidden.
      * Forwards renderer selection and show-view-cube, stores its layout handler in #handlers and subscribes before activation
      * so the first measured layout positions the render menu correctly.
+     * Hands any retained Quick Look asset provider to the new component.
      * @private
      * @returns {void}
      */
@@ -401,6 +404,7 @@ export default class PrefViewer extends HTMLElement {
         this.#handlers.on3DElementClick = this.#on3DElementClick.bind(this);
         this.#component3D = document.createElement("pref-viewer-3d");
         this.#component3D.setAttribute("visible", "false");
+        this.#component3D.setQuickLookAssetProvider?.(this.#quickLookAssetProvider);
         this.#component3D.setAttribute("view-cube-renderer", this.viewCubeRenderer);
         this.#component3D.setAttribute("show-view-cube", this.getAttribute("show-view-cube") === "false" ? "false" : "true");
         this.#handlers.onViewCubeLayout = (event) => {
@@ -1289,6 +1293,21 @@ export default class PrefViewer extends HTMLElement {
         this.#component3D.downloadModelGLTF();
     }
 
+    /**
+     * Sets or clears the host-supplied asset opened by the iOS AR Quick Look action instead of the in-browser USDZ export.
+     * The provider is retained across connection cycles, even when set before the element is connected.
+     * The viewer knows nothing about how the host produces the asset.
+     * @public
+     * @param {?(function(): Promise<{data: (Uint8Array|ArrayBuffer|Blob), mimeType?: string, fileName?: string}>)} provider
+     *   Async asset factory (defaults: MIME `model/vnd.usdz+zip`, file name `model.usdz`), or null to restore the built-in export.
+     *   A failing provider falls back to the built-in export with a console warning.
+     * @returns {void}
+     */
+    setQuickLookAssetProvider(provider) {
+        this.#quickLookAssetProvider = typeof provider === "function" ? provider : null;
+        this.#component3D?.setQuickLookAssetProvider?.(this.#quickLookAssetProvider);
+    }
+
     /**
      * Initiates download of the current 3D model in USDZ format.
      * @public

package/src/quick-look-action.js

@@ -17,6 +17,22 @@ export default class QuickLookAction {
      */
     static QUICK_LOOK_FRAGMENT = "allowsContentScaling=0";
 
+    /**
+     * MIME type of a USDZ archive; the only type whose bytes are validated as a ZIP before being exposed.
+     * @public
+     * @static
+     * @type {string}
+     */
+    static USDZ_MIME_TYPE = "model/vnd.usdz+zip";
+
+    /**
+     * File name given to the anchor's `download` attribute when the prepared asset does not name itself.
+     * @public
+     * @static
+     * @type {string}
+     */
+    static DEFAULT_FILE_NAME = "model.usdz";
+
     #anchor;
     #style;
     #window;
@@ -55,7 +71,7 @@ export default class QuickLookAction {
         this.#anchor = document.createElement("a");
         this.#anchor.className = "babylonVRicon pref-viewer-quick-look";
         this.#anchor.rel = "ar";
-        this.#anchor.download = "model.usdz";
+        this.#anchor.download = QuickLookAction.DEFAULT_FILE_NAME;
         this.#anchor.setAttribute("role", "button");
         this.#anchor.tabIndex = 0;
         this.#anchor.hidden = true;
@@ -204,11 +220,38 @@ export default class QuickLookAction {
     }
 
     /**
-     * Queues current-model export and exposes only a nonempty ZIP-signature USDZ as a native link.
+     * Normalizes an exporter result into the bytes, MIME type and file name of the asset to expose.
+     * A bare `Uint8Array` is a USDZ with default metadata; an object carries its own optional metadata.
+     * USDZ content must be a nonempty ZIP-signature archive; other MIME types are passed through as-is.
+     * @private
+     * @static
+     * @param {Uint8Array|{data: Uint8Array, mimeType?: string, fileName?: string}} result - Exporter result.
+     * @returns {{data: Uint8Array, mimeType: string, fileName: string}} Validated asset description.
+     * @throws {Error} When the result is not byte content or a USDZ lacks the ZIP signature.
+     */
+    static #resolveAsset(result) {
+        const isDescribed = !!result && typeof result === "object" && !(result instanceof Uint8Array);
+        const data = isDescribed ? result.data : result;
+        const mimeType = (isDescribed && result.mimeType) || QuickLookAction.USDZ_MIME_TYPE;
+        const fileName = (isDescribed && result.fileName) || QuickLookAction.DEFAULT_FILE_NAME;
+        if (!(data instanceof Uint8Array) || data.length === 0) {
+            throw new Error("PrefViewer: invalid Quick Look export");
+        }
+        // USDZ is a ZIP archive; never expose empty, JSON or glTF results as native AR.
+        if (mimeType === QuickLookAction.USDZ_MIME_TYPE
+            && (data.length < 4 || data[0] !== 0x50 || data[1] !== 0x4b || data[2] !== 3 || data[3] !== 4)) {
+            throw new Error("PrefViewer: invalid USDZ export");
+        }
+        return { data, mimeType, fileName };
+    }
+
+    /**
+     * Queues current-model export and exposes only a valid asset as a native link: a nonempty ZIP-signature USDZ,
+     * or, when the exporter describes another MIME type, that asset unchanged.
      * Obsolete revisions are ignored. Export failures are logged and shown as a retry action;
      * they do not reject the returned work promise or expose an older model's content.
      * @public
-     * @param {?(function(): Promise<Uint8Array>)} exporter - Current-model serializer, or null to invalidate without preparation.
+     * @param {?(function(): Promise<Uint8Array|{data: Uint8Array, mimeType?: string, fileName?: string}>)} exporter - Current-model serializer returning USDZ bytes or a described asset (defaults: USDZ MIME type, `model.usdz`), or null to invalidate without preparation.
      * @returns {Promise<void>} Resolves after this queued preparation settles or becomes obsolete.
      */
     update(exporter) {
@@ -231,17 +274,15 @@ export default class QuickLookAction {
                 return;
             }
             try {
-                const bytes = await exporter();
+                const result = await exporter();
                 if (this.#disposed || revision !== this.#revision) {
                     return;
                 }
-                // USDZ is a ZIP archive; never expose empty, JSON or glTF results as native AR.
-                if (!(bytes instanceof Uint8Array) || bytes.length < 4 || bytes[0] !== 0x50 || bytes[1] !== 0x4b || bytes[2] !== 3 || bytes[3] !== 4) {
-                    throw new Error("PrefViewer: invalid USDZ export");
-                }
-                const blob = new this.#window.Blob([bytes], {
-                    type: "model/vnd.usdz+zip"
+                const asset = QuickLookAction.#resolveAsset(result);
+                const blob = new this.#window.Blob([asset.data], {
+                    type: asset.mimeType
                 });
+                this.#anchor.download = asset.fileName;
                 this.#url = this.#urlAPI.createObjectURL(blob);
                 // 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.