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

package/README.md

@@ -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.
 

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.1",
     "description": "Web Component to preview GLTF models with Babylon.js",
     "author": "Alex Moreno Palacio <amoreno@preference.es>",
     "scripts": {

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 };
     }
 
     /**

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

@@ -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();
 
     }
@@ -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.