@preference-sl/pref-viewer 2.12.0 → 2.13.0-beta.1

package/src/pref-viewer.js

@@ -1,94 +1,86 @@
 import PrefViewerTask from "./pref-viewer-task.js";
 import { PrefViewerStyles } from "./styles.js";
+import { DEFAULT_LOCALE, resolveLocale, setLocale, SUPPORTED_LOCALES } from "./localization/i18n.js";
 
 /**
- * PrefViewer - Custom Web Component for advanced 2D and 3D product visualization and configuration.
+ * PrefViewer - Custom Web Component for immersive 2D/3D product visualization with localization, persistence, and download tooling.
  *
  * 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.
+ *  - Hosts synchronized 2D (SVG) and 3D (Babylon.js) canvases plus a render-settings menu inside a single shadow DOM wrapper.
+ *  - Queues mutations (config/model/scene/materials/drawing/options/culture) to guarantee deterministic execution and avoid race conditions.
+ *  - Normalizes remote URLs, Base64 payloads, and IndexedDB lookups before forwarding jobs to the BabylonJSController stack.
+ *  - Persists the active locale to localStorage, mirrors it to PrefViewerMenu3D, and keeps the shared i18n module in sync with the chosen culture.
+ *  - Surfaces a dialog API that powers built-in download flows (GLB, glTF+ZIP, USDZ) for model-only, scene-only, or combined asset exports.
+ *  - Emits granular lifecycle custom events so host applications can react to loading progress, drawing zoom changes, and menu interactions.
+ *  - Exposes imperative methods for toggling visibility, updating options, switching modes, and requesting downloads without attribute juggling.
+ *  - Automatically reflects supported attributes back to the DOM so templates, frameworks, and manual scripting stay aligned with viewer state.
  *
  * 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.
+ *  - Drop the `<pref-viewer>` custom element into any document or framework wrapper and supply configuration via attributes or setters.
+ *  - Feed serialized JSON strings or plain objects to `loadConfig`, `loadModel`, `loadScene`, `loadMaterials`, `loadDrawing`, or `setOptions`.
+ *  - Drive localization by setting the `culture` attribute/property or invoking `setCulture("es-ES")`, which propagates to the menu and dialog copy.
+ *  - Trigger downloads through the provided public methods or open the interactive dialog with `openDialog()` for user-driven selection.
+ *  - Listen for `scene-loading`, `scene-loaded`, `drawing-loading`, `drawing-loaded`, and `drawing-zoom-changed` to integrate with surrounding UX.
  *
  * 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").
+ *  - config: Configuration descriptor that can bundle model/scene/materials/drawing/culture hints.
+ *  - model / scene / materials / drawing: Independent asset entry points (URLs, Base64, indexed data) for each subsystem.
+ *  - options: JSON describing render toggles (AA, SSAO, IBL, shadows) plus misc viewer knobs.
+ *  - culture: Locale identifier (RFC-5646 style) that resolves against `SUPPORTED_LOCALES` before applying.
+ *  - mode: Switches between `2d` and `3d`, automatically hiding/showing the relevant subcomponents and menu states.
+ *  - show-model / show-scene: Boolean flags to toggle visibility without reloading the underlying resources.
  *
- * 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 Methods (selection):
+ *  - loadConfig / loadModel / loadScene / loadMaterials / loadDrawing: Queue asset ingestion jobs.
+ *  - setOptions / setMode / setCulture: Update runtime behavior, render mode, or locale.
+ *  - 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.
+ *  - downloadModel / downloadScene / downloadModelAndScene: Export assets in GLB, glTF ZIP, or USDZ flavors.
+ *  - openDialog / closeDialog: Manage PrefViewerDialog instances rendered inside the shadow tree.
  *
  * 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.
+ *  - culture, isInitialized, isLoaded, isLoading, isMode2D, isMode3D expose runtime state for host inspection.
  *
  * 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.
+ *  - `scene-loading` / `scene-loaded` announce Babylon work, `drawing-loading` / `drawing-loaded` cover SVG pipelines, `drawing-zoom-changed` proxies pan/zoom delta.
  *
  * 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.
+ *  - Internally wires PrefViewerMenu3D hover/apply events to PrefViewer3D render settings, ensuring persisted toggles stay in sync with BabylonJSController.
+ *  - Cleans up dialogs, listeners, and subcomponents on disconnect to prevent leaks when frameworks mount/unmount the custom element.
+ *  - Uses localStorage-backed culture persistence and attribute reflection safeguards to keep templates, menu, and global i18n aligned.
+ *  - Designed for embeddable configurators, product showcases, and sales tooling that require responsive 2D/3D switching plus offline-friendly exports.
  */
 export default class PrefViewer extends HTMLElement {
+    // Internal state flags
     #isInitialized = false;
     #isLoaded = false;
     #isLoading = false;
     #mode = "3d";
 
+    // Task queue for sequential processing
     #taskQueue = [];
 
+    // Localization/culture management
+    #CULTURE_STORAGE_KEY = "pref-viewer/culture";
+    #cultureInitial = DEFAULT_LOCALE;
+    #cultureList = SUPPORTED_LOCALES;
+    #culture = "";
+    #cultureSuppressAttribute = false;
+
+    // References to internal components
     #wrapper = null;
     #component2D = null;
     #component3D = null;
     #dialog = null;
+    #menu3D = null;
 
+    // Event handlers
     #handlers = {
         on2DZoomChanged: null,
+        onMenuApply: null,
+        onViewerHoverStart: null,
+        onViewerHoverEnd: null,
+        on3DSceneLoaded: null,
     };
 
     /**
@@ -99,6 +91,12 @@ export default class PrefViewer extends HTMLElement {
     constructor() {
         super();
         this.attachShadow({ mode: "open" });
+        const storedCulture = this.#cultureReadPersisted();
+        if (storedCulture) {
+            this.#culture = resolveLocale(storedCulture);
+        } else {
+            this.#culture = setLocale(this.#cultureInitial);
+        }
     }
 
     /**
@@ -107,7 +105,7 @@ export default class PrefViewer extends HTMLElement {
      * @returns {string[]} Array of attribute names to observe.
      */
     static get observedAttributes() {
-        return ["config", "drawing", "materials", "mode", "model", "scene", "options", "show-model", "show-scene"];
+        return ["config", "culture", "drawing", "materials", "mode", "model", "scene", "options", "show-model", "show-scene"];
     }
 
     /**
@@ -125,6 +123,12 @@ export default class PrefViewer extends HTMLElement {
             case "config":
                 this.loadConfig(value);
                 break;
+            case "culture":
+                if (this.#cultureSuppressAttribute) {
+                    return;
+                }
+                this.setCulture(value);
+                break;
             case "drawing":
                 this.loadDrawing(value);
                 break;
@@ -180,6 +184,7 @@ export default class PrefViewer extends HTMLElement {
 
         this.#createComponent3D();
         this.#createComponent2D();
+        this.#createMenu3D();
 
         if (!this.hasAttribute("mode")) {
             this.setMode();
@@ -195,6 +200,10 @@ export default class PrefViewer extends HTMLElement {
      * @returns {void}
      */
     disconnectedCallback() {
+        if (this.#wrapper) {
+            this.#wrapper.removeEventListener("mouseenter", this.#handlers.onViewerHoverStart);
+            this.#wrapper.removeEventListener("mouseleave", this.#handlers.onViewerHoverEnd);
+        }
         if (this.#dialog) {
             this.#dialog?.remove();
         }
@@ -203,8 +212,14 @@ export default class PrefViewer extends HTMLElement {
             this.#component2D.remove();
         }
         if (this.#component3D) {
+            this.#component3D.removeEventListener("scene-loaded", this.#handlers.on3DSceneLoaded);
             this.#component3D.remove();
         }
+        if (this.#menu3D) {
+            this.#menu3D.removeEventListener("pref-viewer-menu-apply", this.#handlers.onMenuApply);
+            this.#menu3D.remove();
+            this.#menu3D = null;
+        }
     }
 
     /**
@@ -230,9 +245,192 @@ export default class PrefViewer extends HTMLElement {
     #createComponent3D() {
         this.#component3D = document.createElement("pref-viewer-3d");
         this.#component3D.setAttribute("visible", "false");
+        this.#handlers.on3DSceneLoaded = () => {
+            this.#menu3DSyncSettings();
+            this.#menu3D?.setApplying(false);
+        };
+        this.#component3D.addEventListener("scene-loaded", this.#handlers.on3DSceneLoaded);
         this.#wrapper.appendChild(this.#component3D);
     }
 
+    /**
+     * Creates (or recreates) the PrefViewerMenu3D element, wires hover/apply handlers, and syncs it with the 3D component.
+     * When a menu already exists it is removed so the DOM stays clean.
+     * @private
+     * @returns {void}
+     */
+    #createMenu3D() {
+        if (!this.#wrapper) {
+            return;
+        }
+        if (this.#menu3D) {
+            this.#menu3D.removeEventListener("pref-viewer-menu-apply", this.#handlers.onMenuApply);
+            this.#menu3D.remove();
+        }
+        this.#menu3D = document.createElement("pref-viewer-menu-3d");
+        if (typeof this.#menu3D.setCulture === "function") {
+            this.#menu3D.setCulture(this.#culture);
+        } else {
+            this.#menu3D.setAttribute("culture", this.#culture);
+        }
+
+        if (!this.#handlers.onMenuApply) {
+            this.#handlers.onMenuApply = this.#onMenuApply.bind(this);
+        }
+        this.#handlers.onViewerHoverStart = () => this.#menu3D.setViewerHover(true);
+        this.#handlers.onViewerHoverEnd = () => this.#menu3D.setViewerHover(false);
+
+        this.#menu3D.addEventListener("pref-viewer-menu-apply", this.#handlers.onMenuApply);
+        this.#wrapper.addEventListener("mouseenter", this.#handlers.onViewerHoverStart);
+        this.#wrapper.addEventListener("mouseleave", this.#handlers.onViewerHoverEnd);
+
+        this.#wrapper.appendChild(this.#menu3D);
+        this.#menu3DSyncSettings();
+        this.#menu3DUpdateAvailability();
+    }
+
+    /**
+     * Reads the last persisted locale from localStorage so the viewer restores user preference.
+     * @private
+     * @returns {string|null} Resolved locale or null when unavailable.
+     */
+    #cultureReadPersisted() {
+        if (typeof window === "undefined") {
+            return null;
+        }
+        try {
+            return window.localStorage?.getItem(this.#CULTURE_STORAGE_KEY);
+        } catch (_error) {
+            return null;
+        }
+    }
+
+    /**
+     * Persists the active locale in localStorage so it survives reloads and sessions.
+     * @private
+     * @param {string} culture - Locale identifier to store.
+     * @returns {void}
+     */
+    #culturePersist(culture) {
+        if (typeof window === "undefined") {
+            return;
+        }
+        try {
+            window.localStorage?.setItem(this.#CULTURE_STORAGE_KEY, culture);
+        } catch (_error) {}
+    }
+
+    /**
+     * Mirrors the internal `#culture` value back to the `culture` attribute without feedback loops.
+     * @private
+     * @param {string} value - Locale identifier that should be reflected.
+     * @returns {void}
+     */
+    #cultureReflectAttribute(value) {
+        if (this.#cultureSuppressAttribute) {
+            return;
+        }
+        if (this.getAttribute("culture") === value) {
+            return;
+        }
+        this.#cultureSuppressAttribute = true;
+        this.setAttribute("culture", value);
+        this.#cultureSuppressAttribute = false;
+    }
+
+    /**
+     * Synchronizes the menu switches with the current render settings reported by PrefViewer3D.
+     * Skips the update when either the menu or the getter API is unavailable.
+     * @private
+     * @returns {void}
+     */
+    #menu3DSyncSettings() {
+        if (!this.#menu3D || !this.#component3D?.getRenderSettings) {
+            return;
+        }
+        const settings = this.#component3D.getRenderSettings();
+        if (settings) {
+            this.#menu3D.setSettings(settings);
+        }
+    }
+
+    /**
+     * Enables or disables the render menu depending on the active viewer mode.
+     * Clears hover/open states when the viewer switches to 2D so stale UI does not linger.
+     * @private
+     * @returns {void}
+     */
+    #menu3DUpdateAvailability() {
+        if (!this.#menu3D) {
+            return;
+        }
+        const isMode3D = this.#mode === "3d";
+        if (!isMode3D) {
+            this.#menu3D.removeAttribute("data-viewer-hover");
+            this.#menu3D.removeAttribute("data-open");
+        }
+        this.#menu3D.setEnabled?.(isMode3D);
+    }
+
+    /**
+     * Applies render toggles via PrefViewer3D, showing progress in the menu and resyncing on completion.
+     * When no changes occur, the menu is simply refreshed to match the controller snapshot.
+     * @private
+     * @param {object} settings - Partial render settings (AA, SSAO, IBL, shadows) requested by the menu.
+     * @returns {Promise<void>}
+     */
+    async #applyRenderSettings(settings) {
+        if (!this.#component3D) {
+            return;
+        }
+        this.#menu3D?.setApplying(true);
+        try {
+            const result = await this.#component3D.applyRenderSettings(settings);
+            if (!result?.changed) {
+                const controllerSettings = this.#component3D.getRenderSettings();
+                if (controllerSettings) {
+                    this.#menu3D?.setSettings(controllerSettings);
+                }
+                this.#menu3D?.setApplying(false);
+            }
+        } catch (error) {
+            console.error("PrefViewer: failed to apply render settings", error);
+            this.#menu3D?.setApplying(false, true);
+        }
+    }
+
+    /**
+     * Resolves the requested culture, updates internal/global state, and persists the selection.
+     * @private
+     * @param {string} [cultureId] - Desired locale to activate.
+     * @param {object} [options] - Extra flags for the update.
+     * @param {boolean} [options.reflectAttribute=false] - Whether to mirror the attribute.
+     * @returns {boolean} True when the culture actually changes.
+     */
+    #applyCulture(cultureId, options = {}) {
+        let changed = false;
+        if (!cultureId || typeof cultureId !== "string") {
+            return changed;
+        }
+        const cultureInList = this.#cultureList.find((c) => c.toLowerCase() === cultureId.toLowerCase());
+        if (!cultureInList) {
+            return changed;
+        }
+        const { reflectAttribute = false } = options;
+        const resolved = resolveLocale(cultureId);
+        changed = resolved !== this.#culture;
+        if (reflectAttribute) {
+            this.#cultureReflectAttribute(resolved);
+        }
+        if (changed) {
+            this.#culture = resolved;
+            setLocale(resolved);
+            this.#menu3D?.setCulture?.(resolved);
+            this.#culturePersist(resolved);
+        }
+        return changed;
+    }
+
     /**
      * Adds a new task to the internal queue for processing.
      * If the viewer is initialized and not currently loading, immediately processes the next task.
@@ -260,10 +458,16 @@ export default class PrefViewer extends HTMLElement {
         }
         const task = this.#taskQueue[0];
         this.#taskQueue.shift();
+        if (this.#dialog) {
+            this.closeDialog();
+        }
         switch (task.type) {
             case PrefViewerTask.Types.Config:
                 this.#processConfig(task.value);
                 break;
+            case PrefViewerTask.Types.Culture:
+                this.#processCulture(task.value);
+                break;
             case PrefViewerTask.Types.Drawing:
                 this.#processDrawing(task.value);
                 break;
@@ -396,6 +600,22 @@ export default class PrefViewer extends HTMLElement {
         this.dispatchEvent(new CustomEvent("drawing-zoom-changed", customEventOptions));
     }
 
+    /**
+     * Handles the custom "pref-viewer-menu-apply" event emitted by the menu component.
+     * Forwards the requested settings to the render-application pipeline.
+     * @private
+     * @param {CustomEvent} event - Menu event containing the `settings` payload.
+     * @returns {void}
+     */
+    #onMenuApply(event) {
+        event.stopPropagation();
+        const settings = event.detail?.settings;
+        if (!settings) {
+            return;
+        }
+        this.#applyRenderSettings(settings);
+    }
+
     /**
      * Processes a configuration object by loading it into the 3D component.
      * Dispatches loading events and processes the next task when finished.
@@ -415,6 +635,17 @@ export default class PrefViewer extends HTMLElement {
         });
     }
 
+    /**
+     * Handles queued culture changes by applying the locale and advancing the task queue.
+     * @private
+     * @param {string} culture - Locale identifier coming from config, attributes, or API calls.
+     * @returns {void}
+     */
+    #processCulture(culture) {
+        this.#applyCulture(culture, { reflectAttribute: true });
+        this.#processNextTask();
+    }
+
     /**
      * Processes a drawing object by loading it into the 2D component.
      * Processes the next task when finished.
@@ -517,31 +748,119 @@ export default class PrefViewer extends HTMLElement {
      */
 
     /**
-     * Sets the viewer mode to "2d" or "3d" and updates component visibility accordingly.
+     * Initiates download of the current complete scene (3D model and environment) in GLB format.
      * @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;
+    downloadModelAndSceneGLB() {
+        if (!this.#component3D) {
+            return;
         }
-        this.#mode = mode;
-        if (mode === "2d") {
-            this.#component3D?.hide();
-            this.#component2D?.show();
-        } else {
-            this.#component2D?.hide();
-            this.#component3D?.show();
+
+        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;
         }
-        if (this.getAttribute("mode") !== mode) {
-            this.setAttribute("mode", mode);
-            if (this.#dialog) {
-                this.closeDialog();
-            }
+
+        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 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 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();
     }
 
     /**
@@ -556,10 +875,41 @@ export default class PrefViewer extends HTMLElement {
         if (!config) {
             return false;
         }
+        this.#addTaskToQueue(config, "config");
         if (config.drawing) {
             this.#addTaskToQueue(config.drawing, "drawing");
         }
-        this.#addTaskToQueue(config, "config");
+        if (config.culture) {
+            this.#addTaskToQueue(config.culture, "culture");
+        }
+    }
+
+    /**
+     * 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");
+    }
+
+    /**
+     * 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");
     }
 
     /**
@@ -591,31 +941,42 @@ export default class PrefViewer extends HTMLElement {
     }
 
     /**
-     * Loads materials object or JSON string and adds it to the task queue.
+     * Sets the active culture for UI translations and propagates it to child components.
      * @public
-     * @param {object|string} materials - Materials object or JSON string.
-     * @returns {boolean|void} Returns false if materials are invalid; otherwise void.
+     * @param {string} [cultureId] - Locale identifier, e.g., "en-EN".
+     * @returns {void}
      */
-    loadMaterials(materials) {
-        materials = typeof materials === "string" ? JSON.parse(materials) : materials;
-        if (!materials) {
-            return false;
-        }
-        this.#addTaskToQueue(materials, "materials");
+    setCulture(cultureId) {
+        this.#addTaskToQueue(cultureId, "culture");
     }
 
     /**
-     * Loads a drawing object or JSON string and adds it to the task queue.
+     * Sets the viewer mode to "2d" or "3d" and updates component visibility accordingly.
      * @public
-     * @param {object|string} drawing - Drawing object or JSON string.
-     * @returns {boolean|void} Returns false if drawing is invalid; otherwise void.
+     * @param {string} [mode=this.#mode] - The mode to set ("2d" or "3d").
+     * @returns {void}
      */
-    loadDrawing(drawing) {
-        drawing = typeof drawing === "string" ? JSON.parse(drawing) : drawing;
-        if (!drawing) {
-            return false;
+    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();
+        }
+        this.#menu3DUpdateAvailability();
+        if (this.getAttribute("mode") !== mode) {
+            this.setAttribute("mode", mode);
+            if (this.#dialog) {
+                this.closeDialog();
+            }
         }
-        this.#addTaskToQueue(drawing, "drawing");
     }
 
     /**
@@ -632,6 +993,39 @@ export default class PrefViewer extends HTMLElement {
         this.#addTaskToQueue(options, "options");
     }
 
+    /**
+     * 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;
+        }
+    }
+
     /**
      * Shows the 3D model by setting its visibility to true.
      * Adds a visibility task to the queue for processing.
@@ -733,160 +1127,98 @@ export default class PrefViewer extends HTMLElement {
     }
 
     /**
-     * Initiates download of the current 3D model in GLB format.
-     * @public
-     * @returns {void}
+     * ---------------------------
+     * Public properties (setters)
+     * ---------------------------
      */
-    downloadModelGLB() {
-        if (!this.#component3D) {
-            return;
-        }
-
-        this.#component3D.downloadModelGLB();
-    }
 
     /**
-     * Initiates download of the current 3D model in GLTF format.
+     * Accepts a config object or JSON string and forwards it to `loadConfig()`.
      * @public
-     * @returns {void}
+     * @param {object|string} value - Configuration payload or serialized JSON.
      */
-    downloadModelGLTF() {
-        if (!this.#component3D) {
-            return;
-        }
-
-        this.#component3D.downloadModelGLTF();
+    set config(value) {
+        this.loadConfig(value);
     }
 
     /**
-     * Initiates download of the current 3D model in USDZ format.
+     * Mirrors `setCulture()` so templates can change the locale via attributes or props.
      * @public
-     * @returns {void}
+     * @param {string} value - Locale identifier such as "es-ES".
      */
-    downloadModelUSDZ() {
-        if (!this.#component3D) {
-            return;
-        }
-
-        this.#component3D.downloadModelUSDZ();
+    set culture(value) {
+        this.setCulture(value);
     }
 
     /**
-     * Initiates download of the current complete scene (3D model and environment) in GLB format.
+     * Routes incoming drawing data to `loadDrawing()` for queued processing.
      * @public
-     * @returns {void}
+     * @param {object|string} value - Drawing payload or serialized JSON.
      */
-    downloadModelAndSceneGLB() {
-        if (!this.#component3D) {
-            return;
-        }
-
-        this.#component3D.downloadModelAndSceneGLB();
+    set drawing(value) {
+        this.loadDrawing(value);
     }
 
     /**
-     * Initiates download of the current complete scene (3D model and environment) in GLTF format.
+     * Convenience bridge to `loadMaterials()` for template bindings.
      * @public
-     * @returns {void}
+     * @param {object|string} value - Materials definition or JSON string.
      */
-    downloadModelAndSceneGLTF() {
-        if (!this.#component3D) {
-            return;
-        }
-
-        this.#component3D.downloadModelAndSceneGLTF();
+    set materials(value) {
+        this.loadMaterials(value);
     }
 
     /**
-     * Initiates download of the current complete scene (3D model and environment) in USDZ format.
+     * Delegates to `setMode()` so consumers can switch between 2D/3D through a setter.
      * @public
-     * @returns {void}
+     * @param {string} value - Desired viewer mode, e.g., "2d" or "3d".
      */
-    downloadModelAndSceneUSDZ() {
-        if (!this.#component3D) {
-            return;
-        }
-
-        this.#component3D.downloadModelAndSceneUSDZ();
+    set mode(value) {
+        this.setMode(value);
     }
 
     /**
-     * Initiates download of the current 3D environment in GLB format.
+     * Forwards models supplied via property assignment to `loadModel()`.
      * @public
-     * @returns {void}
+     * @param {object|string} value - Model payload or serialized JSON.
      */
-    downloadSceneGLB() {
-        if (!this.#component3D) {
-            return;
-        }
-
-        this.#component3D.downloadSceneGLB();
+    set model(value) {
+        this.loadModel(value);
     }
 
     /**
-     * Initiates download of the current 3D environment in GLTF format.
+     * Sends option updates to `setOptions()` enabling reactive bindings.
      * @public
-     * @returns {void}
+     * @param {object|string} value - Options object or JSON string.
      */
-    downloadSceneGLTF() {
-        if (!this.#component3D) {
-            return;
-        }
-
-        this.#component3D.downloadSceneGLTF();
+    set options(value) {
+        this.setOptions(value);
     }
 
     /**
-     * Initiates download of the current 3D environment in USDZ format.
+     * Redirects scene assignments to `loadScene()` for normalized handling.
      * @public
-     * @returns {void}
+     * @param {object|string} value - Scene payload or serialized JSON.
      */
-    downloadSceneUSDZ() {
-        if (!this.#component3D) {
-            return;
-        }
-        this.#component3D.downloadSceneUSDZ();
+    set scene(value) {
+        this.loadScene(value);
     }
 
     /**
-     * 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.
+     * ---------------------------
+     * Public properties (getters)
+     * ---------------------------
      */
-    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.
+     * Exposes the currently active locale so hosts can inspect which translations are applied.
      * @public
-     * @returns {void}
+     * @returns {string} Locale identifier, e.g., "en-EN".
      */
-    closeDialog() {
-        if (this.#dialog) {
-            this.#dialog.close();
-            this.#dialog = null;
-        }
+    get culture() {
+        return this.#culture;
     }
 
-    /**
-     * ---------------------------
-     * Public properties
-     * ---------------------------
-     */
-
     /**
      * Indicates whether the viewer has been initialized.
      * @public