@preference-sl/pref-viewer 2.11.0-beta.2 → 2.11.0-beta.20

package/src/pref-viewer.js

@@ -0,0 +1,934 @@
+import PrefViewerTask from "./pref-viewer-task.js";
+import { PrefViewerStyles } from "./styles.js";
+
+/**
+ * PrefViewer - Custom Web Component for advanced 2D and 3D product visualization and configuration.
+ *
+ * Overview:
+ *  - Encapsulates both 2D (SVG) and 3D (Babylon.js) viewers, supporting glTF/GLB models, environments, and drawings.
+ *  - Loads assets from remote URLs, Base64 data URIs, and IndexedDB sources.
+ *  - Provides a unified API for loading models, scenes, drawings, materials, and configuration via attributes or methods.
+ *  - Manages an internal task queue for sequential processing of viewer operations.
+ *  - Emits custom events for loading, errors, and state changes to facilitate integration.
+ *  - Supports downloading models and scenes in GLB and USDZ formats.
+ *  - Automatically updates the viewer when reactive attributes change.
+ *
+ * Usage:
+ *  - Use as a custom HTML element: <pref-viewer ...>
+ *  - Configure via attributes (config, model, scene, materials, drawing, options, mode).
+ *  - Control viewer mode, visibility, and downloads via public methods.
+ *
+ * Reactive Attributes:
+ *  - config: URL or Base64 for configuration file.
+ *  - model: URL or Base64 for 3D model (glTF/GLB).
+ *  - scene: URL or Base64 for environment/scene (glTF/GLB).
+ *  - materials: URL or Base64 for materials definition.
+ *  - drawing: URL or Base64 for SVG drawing.
+ *  - options: JSON string for viewer options.
+ *  - mode: Viewer mode ("2d" or "3d").
+ *
+ * Public Methods:
+ *  - loadConfig(config): Loads a configuration object or JSON string.
+ *  - loadModel(model): Loads a model object or JSON string.
+ *  - loadScene(scene): Loads a scene/environment object or JSON string.
+ *  - loadMaterials(materials): Loads materials object or JSON string.
+ *  - loadDrawing(drawing): Loads a drawing object or JSON string.
+ *  - setOptions(options): Sets viewer options from an object or JSON string.
+ *  - setMode(mode): Sets the viewer mode to "2d" or "3d" and updates component visibility.
+ *  - showModel(): Shows the 3D model.
+ *  - hideModel(): Hides the 3D model.
+ *  - showScene(): Shows the 3D environment/scene.
+ *  - hideScene(): Hides the 3D environment/scene.
+ *  - zoomCenter(): Centers the 2D drawing view.
+ *  - zoomExtentsAll(): Zooms the 2D drawing to fit all content.
+ *  - zoomIn(): Zooms in on the 2D drawing.
+ *  - zoomOut(): Zooms out of the 2D drawing.
+ *  - 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.
+ *  - 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.
+ *  - downloadSceneGLB(): Downloads the environment as a GLB file.
+ *  - downloadSceneGLTF(): Downloads the environment as a glTF ZIP file.
+ *  - downloadSceneUSDZ(): Downloads the environment as a USDZ file.
+ *  - openDialog(title, content, footer): Opens a modal dialog with the specified title, content, and footer.
+ *  - closeDialog(): Closes the currently open dialog, if any, and removes it from the DOM.
+ *
+ * Public Properties:
+ *  - isInitialized: Indicates if the viewer is initialized.
+ *  - isLoaded: Indicates if the viewer has finished loading.
+ *  - isLoading: Indicates if the viewer is currently loading.
+ *  - isMode2D: Indicates if the viewer is in 2D mode.
+ *  - isMode3D: Indicates if the viewer is in 3D mode.
+ *
+ * Events:
+ *  - "scene-loading": Dispatched when a 3D loading operation starts.
+ *  - "scene-loaded": Dispatched when a 3D loading operation completes.
+ *  - "drawing-loading": Dispatched when a 2D drawing loading operation starts.
+ *  - "drawing-loaded": Dispatched when a 2D drawing loading operation completes.
+ *  - "drawing-zoom-changed": Dispatched when the 2D drawing zoom/pan state changes.
+ *
+ * Notes:
+ *  - Automatically creates and manages 2D and 3D viewer components in its shadow DOM.
+ *  - Processes tasks sequentially to ensure consistent state.
+ *  - Designed for extensibility and integration in product configurators and visualization tools.
+ */
+export default class PrefViewer extends HTMLElement {
+    #isInitialized = false;
+    #isLoaded = false;
+    #isLoading = false;
+    #mode = "3d";
+
+    #taskQueue = [];
+
+    #wrapper = null;
+    #component2D = null;
+    #component3D = null;
+    #dialog = null;
+
+    #handlers = {
+        on2DZoomChanged: null,
+    };
+
+    /**
+     * Creates a new PrefViewer instance and attaches a shadow DOM.
+     * Initializes internal state and component references.
+     * @public
+     */
+    constructor() {
+        super();
+        this.attachShadow({ mode: "open" });
+    }
+
+    /**
+     * Returns the list of attributes to observe for changes.
+     * @public
+     * @returns {string[]} Array of attribute names to observe.
+     */
+    static get observedAttributes() {
+        return ["config", "drawing", "materials", "mode", "model", "scene", "options", "show-model", "show-scene"];
+    }
+
+    /**
+     * Observes changes to specific attributes and triggers corresponding actions.
+     * Loads configuration, drawing, model, scene, materials, or options when their attributes change.
+     * Toggles model or scene visibility when "show-model" or "show-scene" attributes change.
+     * @public
+     * @param {string} name - The name of the changed attribute.
+     * @param {*} _old - The previous value of the attribute (unused).
+     * @param {*} value - The new value of the attribute.
+     * @returns {void}
+     */
+    attributeChangedCallback(name, _old, value) {
+        switch (name) {
+            case "config":
+                this.loadConfig(value);
+                break;
+            case "drawing":
+                this.loadDrawing(value);
+                break;
+            case "materials":
+                this.loadMaterials(value);
+                break;
+            case "mode":
+                if (_old === value || value.toLowerCase() === this.#mode) {
+                    return;
+                }
+                this.setMode(value);
+                break;
+            case "model":
+                this.loadModel(value);
+                break;
+            case "scene":
+                this.loadScene(value);
+                break;
+            case "options":
+                this.setOptions(value);
+                break;
+            case "show-model":
+                if (_old === value) {
+                    return;
+                }
+                const showModel = value.toLowerCase() === "true";
+                showModel ? this.showModel() : this.hideModel();
+                break;
+            case "show-scene":
+                if (_old === value) {
+                    return;
+                }
+                const showScene = value.toLowerCase() === "true";
+                showScene ? this.showScene() : this.hideScene();
+                break;
+        }
+    }
+
+    /**
+     * Called when the element is inserted into the DOM.
+     * Initializes the 3D and 2D viewer components and starts processing tasks.
+     * @public
+     * @returns {void|boolean} Returns false if initialization fails; otherwise void.
+     */
+    connectedCallback() {
+        this.#wrapper = document.createElement("div");
+        this.#wrapper.classList.add("pref-viewer-wrapper");
+        this.shadowRoot.append(this.#wrapper);
+
+        const style = document.createElement("style");
+        style.textContent = PrefViewerStyles;
+        this.shadowRoot.append(style);
+
+        this.#createComponent3D();
+        this.#createComponent2D();
+
+        if (!this.hasAttribute("mode")) {
+            this.setMode();
+        }
+
+        this.#isInitialized = true;
+        this.#processNextTask();
+    }
+
+    /**
+     * Called when the element is removed from the DOM.
+     * @public
+     * @returns {void}
+     */
+    disconnectedCallback() {
+        if (this.#dialog) {
+            this.#dialog?.remove();
+        }
+        if (this.#component2D) {
+            this.#component2D.removeEventListener("drawing-zoom-changed", this.#handlers.on2DZoomChanged);
+            this.#component2D.remove();
+        }
+        if (this.#component3D) {
+            this.#component3D.remove();
+        }
+    }
+
+    /**
+     * Creates and appends the 2D viewer component to the shadow DOM.
+     * Sets the "visible" attribute to true by default.
+     * @private
+     * @returns {void}
+     */
+    #createComponent2D() {
+        this.#handlers.on2DZoomChanged = this.#on2DZoomChanged.bind(this);
+        this.#component2D = document.createElement("pref-viewer-2d");
+        this.#component2D.setAttribute("visible", "false");
+        this.#component2D.addEventListener("drawing-zoom-changed", this.#handlers.on2DZoomChanged);
+        this.#wrapper.appendChild(this.#component2D);
+    }
+
+    /**
+     * Creates and appends the 3D viewer component to the shadow DOM.
+     * Sets the "visible" attribute to true by default.
+     * @private
+     * @returns {void}
+     */
+    #createComponent3D() {
+        this.#component3D = document.createElement("pref-viewer-3d");
+        this.#component3D.setAttribute("visible", "false");
+        this.#wrapper.appendChild(this.#component3D);
+    }
+
+    /**
+     * Adds a new task to the internal queue for processing.
+     * If the viewer is initialized and not currently loading, immediately processes the next task.
+     * @private
+     * @param {*} value - The payload or data for the task.
+     * @param {string} type - The type of task (see PrefViewerTask.Types).
+     * @returns {void}
+     */
+    #addTaskToQueue(value, type) {
+        this.#taskQueue.push(new PrefViewerTask(value, type));
+        if (this.#isInitialized && !this.#isLoading) {
+            this.#processNextTask();
+        }
+    }
+
+    /**
+     * Processes the next task in the queue, if any.
+     * Dispatches the task to the appropriate handler based on its type.
+     * @private
+     * @returns {boolean|void} Returns false if the queue is empty; otherwise void.
+     */
+    #processNextTask() {
+        if (!this.#taskQueue.length) {
+            return false;
+        }
+        const task = this.#taskQueue[0];
+        this.#taskQueue.shift();
+        switch (task.type) {
+            case PrefViewerTask.Types.Config:
+                this.#processConfig(task.value);
+                break;
+            case PrefViewerTask.Types.Drawing:
+                this.#processDrawing(task.value);
+                break;
+            case PrefViewerTask.Types.Environment:
+                this.#processEnvironment(task.value);
+                break;
+            case PrefViewerTask.Types.Materials:
+                this.#processMaterials(task.value);
+                break;
+            case PrefViewerTask.Types.Model:
+                this.#processModel(task.value);
+                break;
+            case PrefViewerTask.Types.Options:
+                this.#processOptions(task.value);
+                break;
+            case PrefViewerTask.Types.Visibility:
+                this.#processVisibility(task.value);
+                break;
+        }
+    }
+
+    /**
+     * Handles the start of a 3D loading operation.
+     * Updates loading state, sets attributes, and dispatches a "scene-loading" event.
+     * @private
+     * @returns {void}
+     */
+    #on3DLoading() {
+        this.#isLoaded = false;
+        this.#isLoading = true;
+
+        this.removeAttribute("loaded-3d");
+        this.setAttribute("loading-3d", "");
+
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: false,
+            composed: true,
+        };
+        this.dispatchEvent(new CustomEvent("scene-loading", customEventOptions));
+    }
+
+    /**
+     * Handles the completion of a 3D loading operation.
+     * Updates loading state, sets attributes, dispatches a "scene-loaded" event, and processes the next task.
+     * @private
+     * @param {object} [detail] - Optional details to include in the event.
+     * @returns {void}
+     */
+    #on3DLoaded(detail) {
+        this.#isLoaded = true;
+        this.#isLoading = false;
+
+        this.removeAttribute("loading-3d");
+        this.setAttribute("loaded-3d", "");
+
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+        };
+        if (detail) {
+            customEventOptions.detail = detail;
+        }
+        this.dispatchEvent(new CustomEvent("scene-loaded", customEventOptions));
+    }
+
+    /**
+     * Handles the start of a 2D loading operation.
+     * Updates loading state, sets attributes, and dispatches a "drawing-loading" event.
+     * @private
+     * @returns {void}
+     */
+    #on2DLoading() {
+        this.#isLoaded = false;
+        this.#isLoading = true;
+
+        this.removeAttribute("loaded-2d");
+        this.setAttribute("loading-2d", "");
+
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+        };
+        this.dispatchEvent(new CustomEvent("drawing-loading", customEventOptions));
+    }
+
+    /**
+     * Handles the completion of a 2D loading operation.
+     * Updates loading state, sets attributes, dispatches a "drawing-loaded" event, and processes the next task.
+     * @private
+     * @param {object} [detail] - Optional details to include in the event.
+     * @returns {void}
+     */
+    #on2DLoaded(detail) {
+        this.#isLoaded = true;
+        this.#isLoading = false;
+
+        this.removeAttribute("loading-2d");
+        this.setAttribute("loaded-2d", "");
+
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+        };
+        if (detail) {
+            customEventOptions.detail = detail;
+        }
+        this.dispatchEvent(new CustomEvent("drawing-loaded", customEventOptions));
+    }
+
+    /**
+     * Handles the "drawing-zoom-changed" event from the 2D viewer component.
+     * Dispatches a custom "drawing-zoom-changed" event from the PrefViewer element, forwarding the event detail to external listeners.
+     * @private
+     * @param {CustomEvent} event - The original zoom change event from the 2D viewer.
+     * @returns {void}
+     */
+    #on2DZoomChanged(event) {
+        event.stopPropagation();
+        event.preventDefault();
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+            detail: event.detail,
+        };
+        this.dispatchEvent(new CustomEvent("drawing-zoom-changed", customEventOptions));
+    }
+
+    /**
+     * Processes a configuration object by loading it into the 3D component.
+     * Dispatches loading events and processes the next task when finished.
+     * @private
+     * @param {object} config - The configuration object to process.
+     * @returns {void}
+     */
+    #processConfig(config) {
+        if (!this.#component3D) {
+            return;
+        }
+
+        this.#on3DLoading();
+        this.#component3D.load(config).then((detail) => {
+            this.#on3DLoaded(detail);
+            this.#processNextTask();
+        });
+    }
+
+    /**
+     * Processes a drawing object by loading it into the 2D component.
+     * Processes the next task when finished.
+     * @private
+     * @param {object} drawing - The drawing object to process.
+     * @returns {void}
+     */
+    #processDrawing(drawing) {
+        if (!this.#component2D) {
+            return;
+        }
+
+        this.#on2DLoading();
+        this.#component2D.load(drawing).then((detail) => {
+            this.#on2DLoaded(detail);
+            this.#processNextTask();
+        });
+    }
+
+    /**
+     * Processes an environment (scene) object by wrapping it in a config and loading it.
+     * @private
+     * @param {object} environment - The environment/scene object to process.
+     * @returns {void}
+     */
+    #processEnvironment(environment) {
+        const config = {};
+        config.scene = environment;
+        this.#processConfig(config);
+    }
+
+    /**
+     * Processes a materials object by wrapping it in a config and loading it.
+     * @private
+     * @param {object} materials - The materials object to process.
+     * @returns {void}
+     */
+    #processMaterials(materials) {
+        const config = {};
+        config.materials = materials;
+        this.#processConfig(config);
+    }
+
+    /**
+     * Processes a model object by wrapping it in a config and loading it.
+     * @private
+     * @param {object} model - The model object to process.
+     * @returns {void}
+     */
+    #processModel(model) {
+        const config = {};
+        config.model = model;
+        this.#processConfig(config);
+    }
+
+    /**
+     * Processes viewer options by loading them into the 3D component.
+     * Dispatches loading events and processes the next task.
+     * @private
+     * @param {object} options - The options object to process.
+     * @returns {void}
+     */
+    #processOptions(options) {
+        if (!this.#component3D) {
+            return;
+        }
+
+        this.#on3DLoading();
+        const detail = this.#component3D.setOptions(options);
+        this.#on3DLoaded(detail);
+        this.#processNextTask();
+    }
+
+    /**
+     * Processes visibility configuration for the model and scene.
+     * Shows or hides the model and/or scene based on the config, then processes the next task.
+     * @private
+     * @param {object} config - The visibility configuration object.
+     * @returns {void}
+     */
+    #processVisibility(config) {
+        if (!this.#component3D) {
+            return;
+        }
+        const showModel = config.model?.visible;
+        const showScene = config.scene?.visible;
+        if (showModel !== undefined) {
+            showModel ? this.#component3D.showModel() : this.#component3D.hideModel();
+        }
+        if (showScene !== undefined) {
+            showScene ? this.#component3D.showEnvironment() : this.#component3D.hideEnvironment();
+        }
+        this.#processNextTask();
+    }
+
+    /**
+     * ---------------------------
+     * Public methods
+     * ---------------------------
+     */
+
+    /**
+     * Sets the viewer mode to "2d" or "3d" and updates component visibility accordingly.
+     * @public
+     * @param {string} [mode=this.#mode] - The mode to set ("2d" or "3d").
+     * @returns {void}
+     */
+    setMode(mode = this.#mode) {
+        mode = mode.toLowerCase();
+        if (mode !== "2d" && mode !== "3d") {
+            console.warn(`PrefViewer: invalid mode "${mode}". Allowed modes are "2d" and "3d".`);
+            mode = this.#mode;
+        }
+        this.#mode = mode;
+        if (mode === "2d") {
+            this.#component3D?.hide();
+            this.#component2D?.show();
+        } else {
+            this.#component2D?.hide();
+            this.#component3D?.show();
+        }
+        if (this.getAttribute("mode") !== mode) {
+            this.setAttribute("mode", mode);
+            if (this.#dialog) {
+                this.closeDialog();
+            }
+        }
+    }
+
+    /**
+     * Loads a configuration object or JSON string and adds it to the task queue.
+     * If the config contains a drawing, adds a drawing task as well.
+     * @public
+     * @param {object|string} config - Configuration object or JSON string.
+     * @returns {boolean|void} Returns false if config is invalid; otherwise void.
+     */
+    loadConfig(config) {
+        config = typeof config === "string" ? JSON.parse(config) : config;
+        if (!config) {
+            return false;
+        }
+        if (config.drawing) {
+            this.#addTaskToQueue(config.drawing, "drawing");
+        }
+        this.#addTaskToQueue(config, "config");
+    }
+
+    /**
+     * Loads a model object or JSON string and adds it to the task queue.
+     * @public
+     * @param {object|string} model - Model object or JSON string.
+     * @returns {boolean|void} Returns false if model is invalid; otherwise void.
+     */
+    loadModel(model) {
+        model = typeof model === "string" ? JSON.parse(model) : model;
+        if (!model) {
+            return false;
+        }
+        this.#addTaskToQueue(model, "model");
+    }
+
+    /**
+     * Loads a scene/environment object or JSON string and adds it to the task queue.
+     * @public
+     * @param {object|string} scene - Scene object or JSON string.
+     * @returns {boolean|void} Returns false if scene is invalid; otherwise void.
+     */
+    loadScene(scene) {
+        scene = typeof scene === "string" ? JSON.parse(scene) : scene;
+        if (!scene) {
+            return false;
+        }
+        this.#addTaskToQueue(scene, "environment");
+    }
+
+    /**
+     * Loads materials object or JSON string and adds it to the task queue.
+     * @public
+     * @param {object|string} materials - Materials object or JSON string.
+     * @returns {boolean|void} Returns false if materials are invalid; otherwise void.
+     */
+    loadMaterials(materials) {
+        materials = typeof materials === "string" ? JSON.parse(materials) : materials;
+        if (!materials) {
+            return false;
+        }
+        this.#addTaskToQueue(materials, "materials");
+    }
+
+    /**
+     * Loads a drawing object or JSON string and adds it to the task queue.
+     * @public
+     * @param {object|string} drawing - Drawing object or JSON string.
+     * @returns {boolean|void} Returns false if drawing is invalid; otherwise void.
+     */
+    loadDrawing(drawing) {
+        drawing = typeof drawing === "string" ? JSON.parse(drawing) : drawing;
+        if (!drawing) {
+            return false;
+        }
+        this.#addTaskToQueue(drawing, "drawing");
+    }
+
+    /**
+     * Sets viewer options from an object or JSON string and adds them to the task queue.
+     * @public
+     * @param {object|string} options - Options object or JSON string.
+     * @returns {boolean|void} Returns false if options are invalid; otherwise void.
+     */
+    setOptions(options) {
+        options = typeof options === "string" ? JSON.parse(options) : options;
+        if (!options) {
+            return false;
+        }
+        this.#addTaskToQueue(options, "options");
+    }
+
+    /**
+     * Shows the 3D model by setting its visibility to true.
+     * Adds a visibility task to the queue for processing.
+     * @public
+     * @returns {void}
+     */
+    showModel() {
+        const config = { model: { visible: true } };
+        this.#addTaskToQueue(config, "visibility");
+    }
+
+    /**
+     * Hides the 3D model by setting its visibility to false.
+     * Adds a visibility task to the queue for processing.
+     * @public
+     * @returns {void}
+     */
+    hideModel() {
+        const config = { model: { visible: false } };
+        this.#addTaskToQueue(config, "visibility");
+    }
+
+    /**
+     * Shows the scene/environment by setting its visibility to true.
+     * Adds a visibility task to the queue for processing.
+     * @public
+     * @returns {void}
+     */
+    showScene() {
+        const config = { scene: { visible: true } };
+        this.#addTaskToQueue(config, "visibility");
+    }
+
+    /**
+     * Hides the scene/environment by setting its visibility to false.
+     * Adds a visibility task to the queue for processing.
+     * @public
+     * @returns {void}
+     */
+    hideScene() {
+        const config = { scene: { visible: false } };
+        this.#addTaskToQueue(config, "visibility");
+    }
+
+    /**
+     * Centers the 2D drawing view in the viewer.
+     * @public
+     * @returns {void}
+     * @description
+     * Only works when the viewer is in 2D mode. Pending implementation for 3D mode when active camera is not blocked.
+     */
+    zoomCenter() {
+        if (!this.#component2D || this.#mode !== "2d") {
+            return;
+        }
+        this.#component2D.zoomCenter();
+    }
+
+    /**
+     * Zooms the 2D drawing to fit all content within the viewer.
+     * @public
+     * @returns {void}
+     * @description
+     * Only works when the viewer is in 2D mode. Pending implementation for 3D mode when active camera is not blocked.
+     */
+    zoomExtentsAll() {
+        if (!this.#component2D || this.#mode !== "2d") {
+            return;
+        }
+        this.#component2D.zoomExtentsAll();
+    }
+
+    /**
+     * Zooms in on the 2D drawing.
+     * @public
+     * @returns {void}
+     * @description
+     * Only works when the viewer is in 2D mode. Pending implementation for 3D mode when active camera is not blocked.
+     */
+    zoomIn() {
+        if (!this.#component2D || this.#mode !== "2d") {
+            return;
+        }
+        this.#component2D.zoomIn();
+    }
+
+    /**
+     * Zooms out of the 2D drawing.
+     * @public
+     * @returns {void}
+     * @description
+     * Only works when the viewer is in 2D mode. Pending implementation for 3D mode when active camera is not blocked.
+     */
+    zoomOut() {
+        if (!this.#component2D || this.#mode !== "2d") {
+            return;
+        }
+        this.#component2D.zoomOut();
+    }
+
+    /**
+     * Initiates download of the current 3D model in GLB format.
+     * @public
+     * @returns {void}
+     */
+    downloadModelGLB() {
+        if (!this.#component3D) {
+            return;
+        }
+
+        this.#component3D.downloadModelGLB();
+    }
+
+    /**
+     * Initiates download of the current 3D model in GLTF format.
+     * @public
+     * @returns {void}
+     */
+    downloadModelGLTF() {
+        if (!this.#component3D) {
+            return;
+        }
+
+        this.#component3D.downloadModelGLTF();
+    }
+
+    /**
+     * Initiates download of the current 3D model in USDZ format.
+     * @public
+     * @returns {void}
+     */
+    downloadModelUSDZ() {
+        if (!this.#component3D) {
+            return;
+        }
+
+        this.#component3D.downloadModelUSDZ();
+    }
+
+    /**
+     * Initiates download of the current complete scene (3D model and environment) in GLB format.
+     * @public
+     * @returns {void}
+     */
+    downloadModelAndSceneGLB() {
+        if (!this.#component3D) {
+            return;
+        }
+
+        this.#component3D.downloadModelAndSceneGLB();
+    }
+
+    /**
+     * Initiates download of the current complete scene (3D model and environment) in GLTF format.
+     * @public
+     * @returns {void}
+     */
+    downloadModelAndSceneGLTF() {
+        if (!this.#component3D) {
+            return;
+        }
+
+        this.#component3D.downloadModelAndSceneGLTF();
+    }
+
+    /**
+     * Initiates download of the current complete scene (3D model and environment) in USDZ format.
+     * @public
+     * @returns {void}
+     */
+    downloadModelAndSceneUSDZ() {
+        if (!this.#component3D) {
+            return;
+        }
+
+        this.#component3D.downloadModelAndSceneUSDZ();
+    }
+
+    /**
+     * Initiates download of the current 3D environment in GLB format.
+     * @public
+     * @returns {void}
+     */
+    downloadSceneGLB() {
+        if (!this.#component3D) {
+            return;
+        }
+
+        this.#component3D.downloadSceneGLB();
+    }
+
+    /**
+     * Initiates download of the current 3D environment in GLTF format.
+     * @public
+     * @returns {void}
+     */
+    downloadSceneGLTF() {
+        if (!this.#component3D) {
+            return;
+        }
+
+        this.#component3D.downloadSceneGLTF();
+    }
+
+    /**
+     * Initiates download of the current 3D environment in USDZ format.
+     * @public
+     * @returns {void}
+     */
+    downloadSceneUSDZ() {
+        if (!this.#component3D) {
+            return;
+        }
+        this.#component3D.downloadSceneUSDZ();
+    }
+
+    /**
+     * Opens a modal dialog with the specified title, content, and footer.
+     * @public
+     * @param {string} title - The dialog title to display in the header.
+     * @param {string} content - The HTML content to display in the dialog body.
+     * @param {string} footer - The HTML content to display in the dialog footer (e.g., action buttons).
+     * @returns {HTMLElement} The created dialog element.
+     * @description
+     * If a dialog is already open, it is closed before opening the new one.
+     * The dialog is appended to the viewer's shadow DOM and returned for further manipulation.
+     */
+    openDialog(title, content, footer) {
+        if (this.#dialog && this.#dialog.hasAttribute("open")) {
+            this.#dialog.close();
+        }
+        this.#dialog = document.createElement("pref-viewer-dialog");
+        this.shadowRoot.querySelector(".pref-viewer-wrapper").appendChild(this.#dialog);
+        const opened = this.#dialog.open(title, content, footer);
+        return opened ? this.#dialog : null;
+    }
+
+    /**
+     * Closes the currently open dialog, if any, and removes it from the DOM.
+     * @public
+     * @returns {void}
+     */
+    closeDialog() {
+        if (this.#dialog) {
+            this.#dialog.close();
+            this.#dialog = null;
+        }
+    }
+
+    /**
+     * ---------------------------
+     * Public properties
+     * ---------------------------
+     */
+
+    /**
+     * Indicates whether the viewer has been initialized.
+     * @public
+     * @returns {boolean} True if initialized; otherwise, false.
+     */
+    get isInitialized() {
+        return this.#isInitialized;
+    }
+
+    /**
+     * Indicates whether the viewer has finished loading.
+     * @public
+     * @returns {boolean} True if loaded; otherwise, false.
+     */
+    get isLoaded() {
+        return this.#isLoaded;
+    }
+
+    /**
+     * Indicates whether the viewer is currently loading.
+     * @public
+     * @returns {boolean} True if loading; otherwise, false.
+     */
+    get isLoading() {
+        return this.#isLoading;
+    }
+
+    /**
+     * Indicates whether the viewer is currently in 2D mode.
+     * @public
+     * @returns {boolean} True if the viewer is in 2D mode; otherwise, false.
+     */
+    get isMode2D() {
+        return this.#mode === "2d";
+    }
+
+    /**
+     * Indicates whether the viewer is currently in 3D mode.
+     * @public
+     * @returns {boolean} True if the viewer is in 3D mode; otherwise, false.
+     */
+    get isMode3D() {
+        return this.#mode === "3d";
+    }
+}