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

package/src/file-storage.js

@@ -9,6 +9,7 @@ import { openDB } from "idb";
  *  - Falls back to direct server access when IndexedDB is unavailable.
  *  - Supports file blob retrieval, timestamp checking, and size queries.
  *  - Uses the idb library for simplified IndexedDB operations.
+ *  - Observes cache-write request and transaction completion together so simultaneous failures are handled.
  *
  * Dependencies:
  *  - idb (IndexedDB wrapper library)
@@ -34,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.
@@ -423,6 +425,7 @@ export default class FileStorage {
 
     /**
      * Updates `lastAccess` for a record to keep LRU ordering current.
+     * Observes the write and transaction together; failed touches are caught without leaking an abort rejection.
      * @private
      * @param {String} uri Record key.
      * @param {Object} record Existing normalized record.
@@ -443,8 +446,7 @@ export default class FileStorage {
         try {
             const transaction = this.#db.transaction(this.osName, "readwrite");
             const store = transaction.objectStore(this.osName);
-            store.put(normalized, uri);
-            await transaction.done;
+            await Promise.all([store.put(normalized, uri), transaction.done]);
         } catch (error) {}
     }
 
@@ -596,6 +598,7 @@ export default class FileStorage {
      * @description
      * Runs maintenance before write (TTL, max entries, and quota-aware cleanup), then retries quota errors
      * by evicting least-recently-used entries.
+     * Observes each write request and transaction completion together so simultaneous WebKit failures are handled.
      */
     async #putFile(file, uri) {
         if (this.#db === undefined) {
@@ -619,8 +622,9 @@ export default class FileStorage {
             try {
                 const transaction = this.#db.transaction(this.osName, "readwrite");
                 const store = transaction.objectStore(this.osName);
-                const result = await store.put(record, uri);
-                await transaction.done;
+                // Observe both promises immediately: WebKit can reject the write and abort
+                // its transaction together. Awaiting them sequentially leaks a rejection.
+                const [result] = await Promise.all([store.put(record, uri), transaction.done]);
                 return result;
             } catch (error) {
                 if (!this.#isQuotaExceededError(error) || attempt === this.#maxQuotaEvictionRetries) {
@@ -695,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

@@ -9,7 +9,9 @@ import { closeDb, initDb, loadModel } from "./gltf-storage.js";
  *  - Decodes base64 data and determines file type (.gltf or .glb).
  *  - Normalizes and replaces asset URIs with resolved URLs from FileStorage.
  *  - Handles cache validation using asset size and timestamp to avoid unnecessary reloads.
- *  - Tracks generated object URLs so callers can revoke them after Babylon finishes loading.
+ *    Callers may opt into an explicit unchanged marker to distinguish cache hits from unavailable content.
+ *  - 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:
@@ -17,7 +19,7 @@ import { closeDb, initDb, loadModel } from "./gltf-storage.js";
  *  - Prepare asset: await resolver.getSource(storage, currentSize, currentTimeStamp);
  *
  * Public Methods:
- *  - getSource(storage, currentSize, currentTimeStamp): Resolves and prepares a glTF/GLB source for loading.
+ *  - getSource(storage, currentSize, currentTimeStamp, reportUnchanged?): Prepares a source or reports a cache hit.
  *  - revokeObjectURLs(objectURLs): Releases temporary blob URLs generated during source resolution.
  *  - dispose(): Releases resolver resources and closes the internal FileStorage DB handle.
  *
@@ -217,10 +219,76 @@ 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
-     * @param {string[]} objectURLs - URLs previously created via URL.createObjectURL.
+     * @param {string[]} [objectURLs=[]] - URLs previously created via URL.createObjectURL.
      * @returns {void}
      */
     revokeObjectURLs(objectURLs = []) {
@@ -251,17 +319,22 @@ export default class GLTFResolver {
      * @param {object} storage - Storage descriptor containing url, db, table, and id properties.
      * @param {number|null} currentSize - The current cached size of the asset, or null if not cached.
      * @param {string|null} currentTimeStamp - The current cached timestamp of the asset, or null if not cached.
-     * @returns {Promise<false|{source: File|string, size: number, timeStamp: string|null, extension: string, metadata: object, objectURLs: string[]}>}
-     *   - Resolves to false if no update is needed or on error.
+     * @param {boolean} [reportUnchanged=false] - Return an explicit unchanged marker for cache hits.
+     * @returns {Promise<false|{unchanged:true}|{source: File|string, size: number, timeStamp: string|null, extension: string, metadata: object, objectURLs: string[]}>}
+     *   - Resolves to false for missing data or an unchanged asset when reportUnchanged is false.
+     *   - Resolves to {unchanged: true} for a cache hit when reportUnchanged is true.
      *   - Resolves to an object containing source, cache metadata, and tracked object URLs if an update is required.
+     * @throws {Error} Rejects when storage access, source retrieval or glTF JSON decoding fails.
      * @description
      *   - If storage specifies IndexedDB (db, table, id), loads the asset from IndexedDB and checks for updates.
      *   - 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.
      */
-    async getSource(storage, currentSize, currentTimeStamp) {
+    async getSource(storage, currentSize, currentTimeStamp, reportUnchanged = false) {
         let source = storage.url || null;
         let newSize, newTimeStamp;
         let pending = false;
@@ -277,7 +350,7 @@ export default class GLTFResolver {
             source = object.data;
             metadata = { ...(object.metadata ?? {}) };
             if (object.timeStamp === currentTimeStamp) {
-                return false;
+                return reportUnchanged ? { unchanged: true } : false;
             } else {
                 pending = true;
                 newSize = object.size;
@@ -304,7 +377,7 @@ export default class GLTFResolver {
             }
             if (!pending) {
                 if (currentTimeStamp === null && currentSize === size) {
-                    return false;
+                    return reportUnchanged ? { unchanged: true } : false;
                 } else {
                     pending = true;
                     newSize = size;
@@ -316,7 +389,7 @@ export default class GLTFResolver {
             extension = extMatch ? `.${extMatch[1].toLowerCase()}` : ".gltf";
             let [fileSize, fileTimeStamp] = [await this.#fileStorage.getSize(source), await this.#fileStorage.getTimeStamp(source)];
             if (currentSize === fileSize && currentTimeStamp === fileTimeStamp) {
-                return false;
+                return reportUnchanged ? { unchanged: true } : false;
             } else {
                 pending = true;
                 newSize = fileSize;
@@ -327,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/localization/translations.js

@@ -1,6 +1,11 @@
 export const translations = {
     "en-EN": {
         prefViewer: {
+            ar: {
+                open: "View in AR",
+                preparing: "Preparing AR…",
+                retry: "Retry preparing AR",
+            },
             viewCube: {
                 title: "View orientation",
                 front: "Inner",
@@ -14,6 +19,7 @@ export const translations = {
                 title: "3D render settings",
                 subtitle: "Modify the visual effects.",
                 actions: {
+                    close: "Close",
                     play: "Play",
                     pause: "Pause",
                 },
@@ -71,6 +77,11 @@ export const translations = {
     },
     "es-ES": {
         prefViewer: {
+            ar: {
+                open: "Ver en RA",
+                preparing: "Preparando RA…",
+                retry: "Reintentar preparar RA",
+            },
             viewCube: {
                 title: "Orientación de vista",
                 front: "Interior",
@@ -84,6 +95,7 @@ export const translations = {
                 title: "Ajustes de render 3D",
                 subtitle: "Modifica los efectos visuales.",
                 actions: {
+                    close: "Cerrar",
                     play: "Reproducir",
                     pause: "Pausar",
                 },

package/src/panzoom-controller.js

@@ -108,10 +108,10 @@ export default class PanzoomController {
     /**
      * Stores the SVG wrapper, Panzoom options and callbacks, and binds reusable input handlers.
      * @public
-     * @param {HTMLElement|SVGElement} wrapper - Element transformed by Panzoom.
-     * @param {object} [options] - Panzoom configuration.
-     * @param {function(object): void} [changedCallback] - Receives the current viewport state.
-     * @param {function(Event): void} [clickCallback] - Receives the original event for a recognized click.
+     * @param {HTMLElement|SVGElement|null} [wrapper=null] - Element transformed by Panzoom.
+     * @param {object} [options={}] - Panzoom configuration.
+     * @param {?(function(object): void)} [changedCallback=null] - Receives the current viewport state.
+     * @param {?(function(Event): void)} [clickCallback=null] - Receives the original event for a recognized click.
      */
     constructor(wrapper = null, options = {}, changedCallback = null, clickCallback = null) {
         this.#wrapper = wrapper;

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

@@ -492,7 +492,7 @@ export default class PrefViewer2D extends HTMLElement {
      * @param {Element} node - Clone to append.
      * @param {string} semanticId - Business id represented by the clone.
      * @param {"selectable"|"selected"|"definition"} layer - Layer type.
-     * @param {Element|null} parent - Optional parent; defaults to drawing root.
+     * @param {Element|null} [parent=null] - Optional parent; defaults to drawing root.
      * @returns {Element|null}
      */
     #appendSelectionNode(node, semanticId, layer, parent = null) {
@@ -697,7 +697,7 @@ export default class PrefViewer2D extends HTMLElement {
     /**
      * Apply a complete semantic selection snapshot to the current drawing.
      * @public
-     * @param {{selectableIds?: string[], selectedItems?: Array<{id: string, highlights?: string[]}>}} state - Selection snapshot.
+     * @param {{selectableIds?: string[], selectedItems?: Array<{id: string, highlights?: string[]}>}} [state={}] - Selection snapshot.
      * @returns {void}
      */
     applySelectionState(state = {}) {

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

@@ -1,6 +1,7 @@
 import { CameraData, ContainerData, MaterialData, IBLData } from "./pref-viewer-3d-data.js";
 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";
 
 /**
@@ -25,6 +26,7 @@ import FileStorage from "./file-storage.js";
  *  - show-model: Show or hide the 3D model ("true"/"false").
  *  - show-scene: Show or hide the 3D environment ("true"/"false").
  *  - visible: Show or hide the entire viewer ("true"/"false").
+ *  - view-cube-renderer: Selects independent Babylon Canvas (default) or SVG via reflected viewCubeRenderer.
  *  - show-view-cube: Enable the orientation overlay while visible; only "false" disables it (default: enabled).
  *
  * Public Methods:
@@ -80,11 +82,14 @@ import FileStorage from "./file-storage.js";
  *  - "pref-viewer-3d-element-click": Internal event carrying distance-ordered semantic model mesh ids.
  *
  * Notes:
+ *  - Owns responsive controls only when standalone; nested 3D inherits its root viewer presentation.
  *  - Internal state and heavy initialization are handled in connectedCallback.
  *  - Designed for extensibility and integration in product configurators, PrefViewer host elements, and visualization tools.
  *  - All resource management and rendering operations are performed asynchronously for performance.
  */
 export default class PrefViewer3D extends HTMLElement {
+    #controlsPresentation = null;
+    #componentStyle = null;
     // State flags
     #isInitialized = false;
     #isLoaded = false;
@@ -98,6 +103,20 @@ export default class PrefViewer3D extends HTMLElement {
 
     #babylonJSController = null; // BabylonJSController instance
 
+    /** @returns {"svg"|"canvas"} Per-instance normalized renderer; missing/invalid attributes use Canvas. */
+    get viewCubeRenderer() {
+        return this.getAttribute("view-cube-renderer") === "svg" ? "svg" : "canvas";
+    }
+
+    /**
+     * Reflects the renderer preference immediately without reloading assets or changing visibility.
+     * @param {"svg"|"canvas"} value - SVG selects the vector widget; all other values select the dedicated Canvas 3D scene.
+     * @returns {void}
+     */
+    set viewCubeRenderer(value) {
+        this.setAttribute("view-cube-renderer", value === "svg" ? "svg" : "canvas");
+    }
+
     /**
      * Create a new instance of the 3D viewer component.
      * The constructor only calls super(); heavy initialization happens in connectedCallback.
@@ -107,11 +126,11 @@ export default class PrefViewer3D extends HTMLElement {
     }
 
     /**
-     * Attributes observed by the custom element.
+     * Attributes observed by the custom element, including renderer selection and standalone controls-density.
      * @returns {string[]} Array of attribute names that trigger attributeChangedCallback.
      */
     static get observedAttributes() {
-        return ["show-model", "show-scene", "visible", "show-view-cube"];
+        return ["show-model", "show-scene", "visible", "show-view-cube", "view-cube-renderer", "controls-density"];
     }
 
     /**
@@ -124,10 +143,18 @@ export default class PrefViewer3D extends HTMLElement {
      * - "show-model": shows or hides the model according to the attribute value ("true"/"false").
      * - "show-scene": shows or hides the scene according to the attribute value ("true"/"false").
      * - "visible": shows or hides the component according to the attribute value ("true"/"false").
+     * - "view-cube-renderer": replaces only the cube overlay, preserving camera and assets.
+     * - "controls-density": refreshes standalone presentation without reloading the scene.
      * - "show-view-cube": activates the cube only while visible and the attribute is not "false".
      */
     attributeChangedCallback(name, _old, value) {
         switch (name) {
+            case "view-cube-renderer":
+                this.#babylonJSController?.setViewCubeRenderer(this.viewCubeRenderer);
+                break;
+            case "controls-density":
+                this.#controlsPresentation?.refresh();
+                break;
             case "show-view-cube":
                 this.#babylonJSController?.setViewCubeEnabled(this.#isVisible && value !== "false");
                 break;
@@ -161,12 +188,16 @@ export default class PrefViewer3D extends HTMLElement {
     /**
      * Called when the element is added to the DOM.
      * Creates the DOM structure, sets initial visibility, initializes component data, and sets up the BabylonJSController.
-     * Performs heavy initialization tasks required for the 3D viewer.
+     * Creates a presentation owner only when standalone, then performs heavy 3D initialization.
      * @public
      * @returns {void}
      */
     connectedCallback() {
         this.#createDOMElements();
+        if (!this.getRootNode().host?.matches?.("pref-viewer")) {
+            this.#controlsPresentation = new PrefViewerControlsPresentation(this,
+                () => this.getAttribute("controls-density"), () => this.refreshViewCube());
+        }
         this.#setInitialVisibility();
         this.#initializeData();
         this.#initializeBabylonJS();
@@ -175,29 +206,33 @@ export default class PrefViewer3D extends HTMLElement {
 
     /**
      * Called when the element is removed from the DOM.
-     * Disables the BabylonJSController to clean up resources and event listeners associated with the 3D viewer.
+     * Releases standalone presentation observers and disables Babylon resources/listeners.
      * @public
      * @returns {void}
      */
     disconnectedCallback() {
+        this.#controlsPresentation?.dispose();
+        this.#controlsPresentation = null;
         if (this.#babylonJSController) {
             void this.#babylonJSController.disable();
         }
     }
 
     /**
-     * Create DOM structure and basic styles used by the component.
+     * Replaces the owned canvas wrapper/styles on reconnect, retaining any consumer-added child content.
      * @private
      * @returns {void}
      */
     #createDOMElements() {
+        this.#wrapper?.remove();
+        this.#componentStyle?.remove();
         this.#wrapper = document.createElement("div");
         this.append(this.#wrapper);
 
         this.#canvas = document.createElement("canvas");
         this.#wrapper.appendChild(this.#canvas);
 
-        const style = document.createElement("style");
+        const style = this.#componentStyle = document.createElement("style");
         style.textContent = PrefViewer3DStyles;
         this.append(style);
     }
@@ -245,7 +280,7 @@ export default class PrefViewer3D extends HTMLElement {
     }
 
     /**
-     * Initializes the Babylon controller with asset/option state and the visibility-aware cube contract.
+     * 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.
      * @private
@@ -253,8 +288,19 @@ export default class PrefViewer3D extends HTMLElement {
      */
     #initializeBabylonJS() {
         this.#babylonJSController = new BabylonJSController(this.#canvas, this.#data.containers, this.#data.options, {
+            renderer: this.viewCubeRenderer,
             enabled: this.#isVisible && this.getAttribute("show-view-cube") !== "false",
+            /**
+             * Resolves the containing viewer culture for localized ViewCube labels.
+             * @returns {string|undefined} Host culture, or undefined for standalone default handling.
+             */
             getCulture: () => this.getRootNode().host?.culture,
+            /**
+             * Publishes current ViewCube layout measurements for the containing viewer controls.
+             * @param {number} offset - Active cube height in CSS pixels; zero clears the offset.
+             * @param {number} height - Scene viewport height in CSS pixels.
+             * @returns {void}
+             */
             onLayout: (offset, height) => this.dispatchEvent(new CustomEvent("view-cube-layout", { detail: { offset, height } })),
         });
         this.#babylonJSController.enable();
@@ -798,7 +844,7 @@ export default class PrefViewer3D extends HTMLElement {
     /**
      * Applies the host-owned semantic selection snapshot to the 3D model.
      * @public
-     * @param {object} state - Canonical PrefViewer selection state.
+     * @param {object} [state={}] - Canonical PrefViewer selection state.
      * @returns {void}
      */
     applySelectionState(state = {}) {
@@ -927,7 +973,7 @@ export default class PrefViewer3D extends HTMLElement {
     }
 
     /**
-     * Forwards an internal culture/camera refresh to the existing overlay without activating a disabled cube.
+     * Forwards an internal culture/camera/presentation resize refresh to the existing overlay without activating a disabled cube.
      * @public
      * @returns {void}
      */