@preference-sl/pref-viewer 2.16.0-beta.10 → 2.16.0-beta.12

package/src/pref-viewer.js

@@ -1,5 +1,5 @@
 import PrefViewerTask from "./pref-viewer-task.js";
-import { PrefViewerStyles } from "./styles.js";
+import { PREF_VIEWER_STYLES_STORAGE_KEY, PrefViewerStyles, PrefViewerStyleVariables } from "./styles.js";
 import { DEFAULT_LOCALE, resolveLocale, setLocale, SUPPORTED_LOCALES } from "./localization/i18n.js";
 
 /**
@@ -9,10 +9,10 @@ import { DEFAULT_LOCALE, resolveLocale, setLocale, SUPPORTED_LOCALES } from "./l
  *  - 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.
+ *  - Persists the active locale and supported style variables to localStorage, mirrors locale 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.
+ *  - Emits granular lifecycle custom events so host applications can react to loading progress, drawing zoom changes, selection changes, and menu interactions.
+ *  - Exposes imperative methods for toggling visibility, updating options, switching modes, controlling animations, managing selection state, 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:
@@ -20,29 +20,49 @@ import { DEFAULT_LOCALE, resolveLocale, setLocale, SUPPORTED_LOCALES } from "./l
  *  - 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.
+ *  - Listen for `pref-viewer-initialized`, `pref-viewer-loading`, `pref-viewer-loaded`, `pref-viewer-error`, `pref-viewer-3d-loaded`, `pref-viewer-2d-loaded`, and `pref-viewer-2d-viewport-changed` to integrate with surrounding UX.
  *
  * Reactive Attributes:
  *  - 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.
+ *  - options: JSON describing render toggles (AA, SSAO, IBL, shadows), animation menu, highlight, lighting, and 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.
+ *  - show-render-menu: Boolean flag to show or hide the render-settings menu (default: true).
+ *  - styles: JSON style overrides. Currently supports `colorPrimary`, persisted in localStorage and exposed as `--pref-viewer-color-primary`.
  *
  * Public Methods (selection):
  *  - loadConfig / loadModel / loadScene / loadMaterials / loadDrawing: Queue asset ingestion jobs.
- *  - setOptions / setMode / setCulture: Update runtime behavior, render mode, or locale.
+ *  - setOptions / setIBL / setMode / setCulture / setStyles: Update runtime behavior, IBL lighting, render mode, locale, or supported visual variables.
  *  - 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.
+ *  - downloadModelGLB / downloadModelGLTF / downloadModelUSDZ: Export the loaded model in the requested format.
+ *  - downloadSceneGLB / downloadSceneGLTF / downloadSceneUSDZ: Export the loaded environment in the requested format.
+ *  - downloadModelAndSceneGLB / downloadModelAndSceneGLTF / downloadModelAndSceneUSDZ: Export the combined scene in the requested format.
  *  - openDialog / closeDialog: Manage PrefViewerDialog instances rendered inside the shadow tree.
+ *  - setSelectableElements / setSelectedElements / applySelectionState: Drive the semantic selection contract.
+ *  - clearSelectedElements / clearSelectableElements / clearSelectionState: Reset selection state fully or partially.
+ *  - getSelectionState: Return a snapshot of the current selection.
+ *  - notifyElementClick: Forward a host-side element click into the viewer event stream.
+ *  - startTurnable / stopTurnable / toggleTurnable / getTurnableState: Control and inspect the auto-rotate state.
+ *  - getAnimations / playAnimation / setAnimationProgress / setAnimationLoop: Inspect and control named glTF animations.
+ *  - getDebugInfo: Return a diagnostic snapshot of the active 3D runtime.
  *
  * Public Properties:
- *  - culture, isInitialized, isLoaded, isLoading, isMode2D, isMode3D expose runtime state for host inspection.
+ *  - Getters: culture, isInitialized, isLoaded, isLoading, isMode2D, isMode3D expose runtime state for host inspection.
+ *  - Setters: config, culture, drawing, materials, mode, model, options, scene, and styles mirror the corresponding load/set methods for reactive bindings.
  *
  * Events:
- *  - `scene-loading` / `scene-loaded` announce Babylon work, `drawing-loading` / `drawing-loaded` cover SVG pipelines, `drawing-zoom-changed` proxies pan/zoom delta.
+ *  - `pref-viewer-initialized`: emitted after the host and internal components are mounted and public methods/properties are available.
+ *  - `pref-viewer-loading` / `pref-viewer-loaded` / `pref-viewer-error`: generic lifecycle events that fire for both 2D and 3D pipelines.
+ *  - `pref-viewer-3d-loading` / `pref-viewer-3d-loaded` / `pref-viewer-3d-error`: announce Babylon.js work start, completion, and failure.
+ *  - `pref-viewer-2d-loading` / `pref-viewer-2d-loaded` / `pref-viewer-2d-error`: announce SVG pipeline start, completion, and failure.
+ *  - `pref-viewer-2d-viewport-changed`: proxies pan/zoom delta from the 2D controller.
+ *  - `pref-viewer-selection-state-changed`: emitted whenever the selectable or selected element sets change.
+ *  - `pref-viewer-3d-turnable-changed`: emitted after the auto-rotate state starts, stops, or is toggled.
+ *  - `pref-viewer-element-click`: emitted when the host forwards an element click via `notifyElementClick`.
+ *  - Legacy `scene-*` and `drawing-*` aliases are still emitted alongside their modern equivalents for backward compatibility.
  *
  * Notes:
  *  - Internally wires PrefViewerMenu3D hover/apply events to PrefViewer3D render settings, ensuring persisted toggles stay in sync with BabylonJSController.
@@ -56,6 +76,16 @@ export default class PrefViewer extends HTMLElement {
     #isLoaded = false;
     #isLoading = false;
     #mode = "3d";
+    #selectionState = {
+        selectableIds: [],
+        selectedIds: [],
+        selectedItems: [],
+    };
+    #turnableState = {
+        running: false,
+        speed: 1,
+        direction: "clockwise",
+    };
 
     // Task queue for sequential processing
     #taskQueue = [];
@@ -67,6 +97,12 @@ export default class PrefViewer extends HTMLElement {
     #culture = "";
     #cultureSuppressAttribute = false;
 
+    // Runtime style management
+    #STYLES_STORAGE_KEY = PREF_VIEWER_STYLES_STORAGE_KEY;
+    #styles = {
+        colorPrimary: PrefViewerStyleVariables.colorPrimary,
+    };
+
     // References to internal components
     #wrapper = null;
     #component2D = null;
@@ -98,6 +134,8 @@ export default class PrefViewer extends HTMLElement {
         } else {
             this.#culture = setLocale(this.#cultureInitial);
         }
+
+        this.#applyStyles(this.#stylesReadPersisted(), { persist: false, applyCssVariables: false });
     }
 
     /**
@@ -106,13 +144,13 @@ export default class PrefViewer extends HTMLElement {
      * @returns {string[]} Array of attribute names to observe.
      */
     static get observedAttributes() {
-        return ["config", "culture", "drawing", "materials", "mode", "model", "scene", "options", "show-model", "show-scene", "show-menu", "accent-color", "show-animation-menu", "highlight-color", "highlight-enabled"];
+        return ["config", "culture", "drawing", "materials", "mode", "model", "scene", "options", "show-model", "show-scene", "show-render-menu", "styles"];
     }
 
     /**
      * 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.
+     * Toggles model or scene visibility when "show-model" or "show-scene" attributes change, recreates the 3D menu when "show-render-menu" changes, and queues style overrides when "styles" changes.
      * @public
      * @param {string} name - The name of the changed attribute.
      * @param {*} _old - The previous value of the attribute (unused).
@@ -174,16 +212,12 @@ export default class PrefViewer extends HTMLElement {
                 const showScene = value.toLowerCase() === "true";
                 showScene ? this.showScene() : this.hideScene();
                 break;
-            case "show-menu":
+            case "show-render-menu":
                 // Recreate menu to apply show/hide setting
                 this.#createMenu3D();
                 break;
-            case "accent-color":
-            case "show-animation-menu":
-            case "highlight-color":
-            case "highlight-enabled":
-                // Pass these attributes to the 3D component and menu
-                this.#updateComponentAttributes(name, value);
+            case "styles":
+                this.setStyles(value);
                 break;
         }
     }
@@ -195,24 +229,24 @@ export default class PrefViewer extends HTMLElement {
      * @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.#createShadowDOM();
+        this.#stylesApplyCssVariables();
         this.#createComponent3D();
         this.#createComponent2D();
         this.#createMenu3D();
 
-        if (!this.hasAttribute("mode")) {
-            this.setMode();
-        }
+        this.setMode(this.getAttribute("mode") ?? this.#mode);
 
         this.#isInitialized = true;
-        this.#processNextTask();
+        Promise.resolve().then(() => {
+            if (!this.isConnected || !this.#isInitialized) {
+                return;
+            }
+            this.#dispatchPrefViewerEvent("pref-viewer-initialized", {
+                isInitialized: this.#isInitialized,
+            });
+            this.#processNextTask();
+        });
     }
 
     /**
@@ -229,21 +263,41 @@ export default class PrefViewer extends HTMLElement {
             this.#dialog?.remove();
         }
         if (this.#component2D) {
-            this.#component2D.removeEventListener("drawing-zoom-changed", this.#handlers.on2DZoomChanged);
+            this.#component2D.removeEventListener("pref-viewer-2d-viewport-changed", this.#handlers.on2DZoomChanged);
             this.#component2D.remove();
         }
         if (this.#component3D) {
-            this.#component3D.removeEventListener("scene-loaded", this.#handlers.on3DSceneLoaded);
-            this.#component3D.removeEventListener("scene-error", this.#handlers.on3DSceneError);
+            this.#component3D.removeEventListener("pref-viewer-3d-loaded", this.#handlers.on3DSceneLoaded);
+            this.#component3D.removeEventListener("pref-viewer-3d-error", this.#handlers.on3DSceneError);
             this.#component3D.remove();
         }
         if (this.#menu3D) {
-            this.#menu3D.removeEventListener("pref-viewer-menu-3d-apply", this.#handlers.onMenuApply);
+            this.#menu3D.removeEventListener("pref-viewer-3d-render-settings-change-requested", this.#handlers.onMenuApply);
             this.#menu3D.remove();
             this.#menu3D = null;
         }
     }
 
+    /**
+     * Creates the root shadow DOM structure and host styles.
+     * @private
+     * @returns {void}
+     */
+    #createShadowDOM() {
+        this.#wrapper = document.createElement("div");
+        this.#wrapper.classList.add("pref-viewer-wrapper");
+        this.shadowRoot.append(this.#wrapper);
+
+        const link = document.createElement("link");
+        link.setAttribute("rel", "stylesheet");
+        link.setAttribute("href", "https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100..900;1,100..900&display=swap");
+        this.shadowRoot.append(link);
+
+        const style = document.createElement("style");
+        style.textContent = PrefViewerStyles;
+        this.shadowRoot.append(style);
+    }
+
     /**
      * Creates and appends the 2D viewer component to the shadow DOM.
      * Sets the "visible" attribute to true by default.
@@ -254,7 +308,7 @@ export default class PrefViewer extends HTMLElement {
         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.#component2D.addEventListener("pref-viewer-2d-viewport-changed", this.#handlers.on2DZoomChanged);
         this.#wrapper.appendChild(this.#component2D);
     }
 
@@ -267,15 +321,7 @@ export default class PrefViewer extends HTMLElement {
     #createComponent3D() {
         this.#component3D = document.createElement("pref-viewer-3d");
         this.#component3D.setAttribute("visible", "false");
-        
-        // Pass new configuration attributes to 3D component
-        const newAttrs = ["show-animation-menu", "highlight-color", "highlight-enabled"];
-        for (const attr of newAttrs) {
-            if (this.hasAttribute(attr)) {
-                this.#component3D.setAttribute(attr, this.getAttribute(attr));
-            }
-        }
-        
+
         this.#handlers.on3DSceneLoaded = () => {
             this.#menu3DSyncSettings();
             this.#menu3D?.setApplying(false);
@@ -283,15 +329,15 @@ export default class PrefViewer extends HTMLElement {
         this.#handlers.on3DSceneError = () => {
             this.#menu3D?.setApplying(false, true);
         };
-        this.#component3D.addEventListener("scene-loaded", this.#handlers.on3DSceneLoaded);
-        this.#component3D.addEventListener("scene-error", this.#handlers.on3DSceneError);
+        this.#component3D.addEventListener("pref-viewer-3d-loaded", this.#handlers.on3DSceneLoaded);
+        this.#component3D.addEventListener("pref-viewer-3d-error", this.#handlers.on3DSceneError);
         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.
-     * Respects the "show-menu" attribute to determine if menu should be visible.
+     * Respects the "show-render-menu" attribute to determine if the menu should be visible.
      * @private
      * @returns {void}
      */
@@ -300,7 +346,7 @@ export default class PrefViewer extends HTMLElement {
             return;
         }
         if (this.#menu3D) {
-            this.#menu3D.removeEventListener("pref-viewer-menu-3d-apply", this.#handlers.onMenuApply);
+            this.#menu3D.removeEventListener("pref-viewer-3d-render-settings-change-requested", this.#handlers.onMenuApply);
             this.#menu3D.remove();
             this.#menu3D = null;
         }
@@ -314,13 +360,13 @@ export default class PrefViewer extends HTMLElement {
         }
 
         // Check if menu should be shown (default: true if not specified)
-        const showMenuAttr = this.getAttribute("show-menu");
-        const showMenu = showMenuAttr === null || showMenuAttr === "true";
+        const show3DMenuAttr = this.getAttribute("show-render-menu");
+        const show3DMenu = show3DMenuAttr === null || show3DMenuAttr === "true";
 
-        if (!showMenu) {
+        if (!show3DMenu) {
             return;
         }
-        
+
         this.#menu3D = document.createElement("pref-viewer-menu-3d");
         if (typeof this.#menu3D.setCulture === "function") {
             this.#menu3D.setCulture(this.#culture);
@@ -328,57 +374,22 @@ export default class PrefViewer extends HTMLElement {
             this.#menu3D.setAttribute("culture", this.#culture);
         }
 
-        // Pass illumination-related attributes to menu
-        const illumAttrs = ["show-illumination", "illumination-color"];
-        for (const attr of illumAttrs) {
-            if (this.hasAttribute(attr)) {
-                this.#menu3D.setAttribute(attr, this.getAttribute(attr));
-            }
-        }
-
         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-3d-apply", this.#handlers.onMenuApply);
+        this.#menu3D.addEventListener("pref-viewer-3d-render-settings-change-requested", 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.#menu3DUpdateSwitchAvailability();
+        this.#menu3DUpdateElementAvailability();
         this.#menu3DUpdateAvailability();
     }
 
-    /**
-     * Updates attributes on child components (3D viewer and menu) based on parent attributes.
-     * @private
-     * @param {string} name - Attribute name.
-     * @param {*} value - Attribute value.
-     * @returns {void}
-     */
-    #updateComponentAttributes(name, value) {
-        // Pass to 3D component
-        if (this.#component3D) {
-            if (value === null) {
-                this.#component3D.removeAttribute(name);
-            } else {
-                this.#component3D.setAttribute(name, value);
-            }
-        }
-        
-        // Pass to menu
-        if (this.#menu3D) {
-            if (value === null) {
-                this.#menu3D.removeAttribute(name);
-            } else {
-                this.#menu3D.setAttribute(name, value);
-            }
-        }
-    }
-
     /**
      * Reads the last persisted locale from localStorage so the viewer restores user preference.
      * @private
@@ -428,6 +439,84 @@ export default class PrefViewer extends HTMLElement {
         this.#cultureSuppressAttribute = false;
     }
 
+    /**
+     * Reads persisted style overrides from localStorage.
+     * @private
+     * @returns {object} Persisted style overrides, or an empty object when unavailable.
+     */
+    #stylesReadPersisted() {
+        if (typeof window === "undefined") {
+            return {};
+        }
+        try {
+            const serialized = window.localStorage?.getItem(this.#STYLES_STORAGE_KEY);
+            return serialized ? JSON.parse(serialized) : {};
+        } catch (_error) {
+            return {};
+        }
+    }
+
+    /**
+     * Persists current style overrides in localStorage.
+     * @private
+     * @returns {void}
+     */
+    #stylesPersist() {
+        if (typeof window === "undefined") {
+            return;
+        }
+        try {
+            window.localStorage?.setItem(this.#STYLES_STORAGE_KEY, JSON.stringify(this.#styles));
+        } catch (_error) {}
+    }
+
+    /**
+     * Keeps the host CSS custom properties in sync with the style variables.
+     * @private
+     * @returns {void}
+     */
+    #stylesApplyCssVariables() {
+        this.style.setProperty("--pref-viewer-color-primary", this.#styles.colorPrimary);
+    }
+
+    /**
+     * Applies supported style overrides to PrefViewerStyleVariables and the host CSS variables.
+     * @private
+     * @param {object} styles - Style overrides.
+     * @param {object} [options] - Apply options.
+     * @param {boolean} [options.persist=true] - Whether to persist the resolved styles.
+     * @param {boolean} [options.applyCssVariables=true] - Whether to update host CSS custom properties immediately.
+     * @returns {boolean} True when at least one supported style was applied.
+     */
+    #applyStyles(styles, options = {}) {
+        const { persist = true, applyCssVariables = true } = options;
+        if (!styles || typeof styles !== "object") {
+            return false;
+        }
+
+        const nextStyles = {};
+        if (typeof styles.colorPrimary === "string" && styles.colorPrimary.trim().length > 0) {
+            nextStyles.colorPrimary = styles.colorPrimary.trim();
+        }
+
+        if (!Object.keys(nextStyles).length) {
+            return false;
+        }
+
+        this.#styles = {
+            ...this.#styles,
+            ...nextStyles,
+        };
+        PrefViewerStyleVariables.colorPrimary = this.#styles.colorPrimary;
+        if (applyCssVariables) {
+            this.#stylesApplyCssVariables();
+        }
+        if (persist) {
+            this.#stylesPersist();
+        }
+        return true;
+    }
+
     /**
      * 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.
@@ -467,12 +556,19 @@ export default class PrefViewer extends HTMLElement {
      * @private
      * @returns {void}
      */
-    #menu3DUpdateSwitchAvailability() {
+    #menu3DUpdateElementAvailability() {
         if (!this.#menu3D) {
             return;
         }
         const iblAvailable = this.#component3D?.isIBLAvailable?.() === true;
-        this.#menu3D.setSwitchEnabled?.("iblEnabled", iblAvailable);
+        const animationMenuEnabled = this.#component3D?.isAnimationMenuEnabled?.() === true;
+        const lightingTimeOfDayEnabled = this.#component3D?.isLightingTimeOfDayAvailable?.() === true;
+        this.#menu3D.setElementEnabled?.("iblEnabled", iblAvailable);
+        this.#menu3D.setElementVisible?.("showAnimationMenu", false);
+        this.#menu3D.setElementVisible?.("highlightEnabled", animationMenuEnabled);
+        this.#menu3D.setElementVisible?.("highlightColor", animationMenuEnabled);
+        this.#menu3D.setElementVisible?.("showLightingTimeOfDay", false);
+        this.#menu3D.setElementVisible?.("lightingTimeOfDay", lightingTimeOfDayEnabled);
     }
 
     /**
@@ -486,18 +582,19 @@ export default class PrefViewer extends HTMLElement {
         if (!this.#component3D) {
             return;
         }
-        const { highlightEnabled: _he, highlightColor: _hc, lightingTimeOfDay: _lt, lighting: _lighting, persist: _persist, ...reloadSettings } = settings ?? {};
+        const { showAnimationMenu: _sam, highlightEnabled: _he, highlightColor: _hc, showLightingTimeOfDay: _slt, lightingTimeOfDay: _lt, persist: _persist, ...reloadSettings } = settings ?? {};
         const hasReloadSettings = Object.keys(reloadSettings).length > 0;
         if (hasReloadSettings) {
             this.#menu3D?.setApplying(true);
         }
         try {
             const result = await this.#component3D.applyRenderSettings(settings);
+            const controllerSettings = this.#component3D.getRenderSettings();
+            if (controllerSettings) {
+                this.#menu3D?.setSettings(controllerSettings);
+            }
+            this.#menu3DUpdateElementAvailability();
             if (!result?.changed) {
-                const controllerSettings = this.#component3D.getRenderSettings();
-                if (controllerSettings) {
-                    this.#menu3D?.setSettings(controllerSettings);
-                }
                 this.#menu3D?.setApplying(false);
             }
         } catch (error) {
@@ -548,10 +645,7 @@ export default class PrefViewer extends HTMLElement {
      */
     #addTaskToQueue(value, type) {
         const task = new PrefViewerTask(value, type);
-        if (
-            task.type === PrefViewerTask.Types.Options ||
-            task.type === PrefViewerTask.Types.Drawing
-        ) {
+        if (task.type === PrefViewerTask.Types.Options || task.type === PrefViewerTask.Types.Drawing || task.type === PrefViewerTask.Types.Styles) {
             this.#taskQueue = this.#taskQueue.filter((queuedTask) => queuedTask.type !== task.type);
         }
         this.#taskQueue.push(task);
@@ -597,6 +691,9 @@ export default class PrefViewer extends HTMLElement {
             case PrefViewerTask.Types.Options:
                 this.#processOptions(task.value);
                 break;
+            case PrefViewerTask.Types.Styles:
+                this.#processStyles(task.value);
+                break;
             case PrefViewerTask.Types.Visibility:
                 this.#processVisibility(task.value);
                 break;
@@ -616,12 +713,9 @@ export default class PrefViewer extends HTMLElement {
         this.removeAttribute("loaded-3d");
         this.setAttribute("loading-3d", "");
 
-        const customEventOptions = {
-            bubbles: true,
-            cancelable: false,
-            composed: true,
-        };
-        this.dispatchEvent(new CustomEvent("scene-loading", customEventOptions));
+        this.#dispatchPrefViewerEvent("pref-viewer-3d-loading");
+        this.#dispatchPrefViewerEvent("scene-loading"); // Legacy event for backward compatibility
+        this.#dispatchPrefViewerEvent("pref-viewer-loading");
     }
 
     /**
@@ -634,22 +728,18 @@ export default class PrefViewer extends HTMLElement {
     #on3DLoaded(detail) {
         this.#isLoaded = true;
         this.#isLoading = false;
-        
+
         this.#menu3DSyncSettings();
-        this.#menu3DUpdateSwitchAvailability();
+        this.#menu3DUpdateElementAvailability();
 
         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));
+        this.#dispatchPrefViewerEvent("pref-viewer-3d-loaded", detail ?? {});
+        this.#dispatchPrefViewerEvent("scene-loaded", detail ?? {}); // Legacy event for backward compatibility
+        this.#dispatchPrefViewerEvent("pref-viewer-loaded", {
+            result: detail ?? null,
+        });
     }
 
     /**
@@ -667,15 +757,9 @@ export default class PrefViewer extends HTMLElement {
         this.removeAttribute("loading-3d");
         this.removeAttribute("loaded-3d");
 
-        const customEventOptions = {
-            bubbles: true,
-            cancelable: true,
-            composed: true,
-        };
-        if (detail) {
-            customEventOptions.detail = detail;
-        }
-        this.dispatchEvent(new CustomEvent("scene-error", customEventOptions));
+        this.#dispatchPrefViewerEvent("pref-viewer-3d-error", detail ?? {});
+        this.#dispatchPrefViewerEvent("scene-error", detail ?? {}); // Legacy event for backward compatibility
+        this.#dispatchPrefViewerEvent("pref-viewer-error", { error: detail?.error ?? detail ?? null });
     }
 
     /**
@@ -691,12 +775,9 @@ export default class PrefViewer extends HTMLElement {
         this.removeAttribute("loaded-2d");
         this.setAttribute("loading-2d", "");
 
-        const customEventOptions = {
-            bubbles: true,
-            cancelable: true,
-            composed: true,
-        };
-        this.dispatchEvent(new CustomEvent("drawing-loading", customEventOptions));
+        this.#dispatchPrefViewerEvent("pref-viewer-2d-loading");
+        this.#dispatchPrefViewerEvent("drawing-loading"); // Legacy event for backward compatibility
+        this.#dispatchPrefViewerEvent("pref-viewer-loading");
     }
 
     /**
@@ -713,15 +794,9 @@ export default class PrefViewer extends HTMLElement {
         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));
+        this.#dispatchPrefViewerEvent("pref-viewer-2d-loaded", detail ?? {});
+        this.#dispatchPrefViewerEvent("drawing-loaded", detail ?? {}); // Legacy event for backward compatibility
+        this.#dispatchPrefViewerEvent("pref-viewer-loaded", { result: detail ?? null });
     }
 
     /**
@@ -738,20 +813,14 @@ export default class PrefViewer extends HTMLElement {
         this.removeAttribute("loading-2d");
         this.removeAttribute("loaded-2d");
 
-        const customEventOptions = {
-            bubbles: true,
-            cancelable: true,
-            composed: true,
-        };
-        if (detail) {
-            customEventOptions.detail = detail;
-        }
-        this.dispatchEvent(new CustomEvent("drawing-error", customEventOptions));
+        this.#dispatchPrefViewerEvent("pref-viewer-2d-error", detail ?? {});
+        this.#dispatchPrefViewerEvent("drawing-error", detail ?? {}); // Legacy event for backward compatibility
+        this.#dispatchPrefViewerEvent("pref-viewer-error", { error: detail?.error ?? detail ?? null });
     }
 
     /**
-     * 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.
+     * Handles the "pref-viewer-2d-viewport-changed" event from the 2D viewer component.
+     * Dispatches the public 2D viewport event, forwarding the event detail to external listeners.
      * @private
      * @param {CustomEvent} event - The original zoom change event from the 2D viewer.
      * @returns {void}
@@ -759,29 +828,24 @@ export default class PrefViewer extends HTMLElement {
     #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));
+        const detail = { ...(event.detail ?? {}) };
+        this.#dispatchPrefViewerEvent("pref-viewer-2d-viewport-changed", detail);
     }
 
     /**
-     * Handles the custom "pref-viewer-menu-3d-apply" event emitted by the menu component.
+     * Handles the custom "pref-viewer-3d-render-settings-change-requested" 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) {
+    async #onMenuApply(event) {
         event.stopPropagation();
         const settings = event.detail?.settings;
         if (!settings) {
             return;
         }
-        this.#applyRenderSettings(settings);
+        await this.#applyRenderSettings(settings);
     }
 
     /**
@@ -913,6 +977,17 @@ export default class PrefViewer extends HTMLElement {
         }
     }
 
+    /**
+     * Processes queued style overrides and advances the task queue.
+     * @private
+     * @param {object} styles - Style overrides to apply.
+     * @returns {void}
+     */
+    #processStyles(styles) {
+        this.#applyStyles(styles);
+        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.
@@ -936,6 +1011,107 @@ export default class PrefViewer extends HTMLElement {
         this.#processNextTask();
     }
 
+    /**
+     * Constructs and dispatches a CustomEvent from the host element.
+     * Strips any incoming `mode` field from the detail to avoid leaking stale values,
+     * then re-attaches `mode` only for generic (non-scoped) event types.
+     * Always appends a `timestamp` (Unix ms) so consumers can correlate events.
+     * @private
+     * @param {string} type - The event type string, e.g. "pref-viewer-loaded".
+     * @param {object} [detail={}] - Arbitrary key/value pairs to include in `event.detail`.
+     * @returns {void}
+     */
+    #dispatchPrefViewerEvent(type, detail = {}) {
+        const eventDetail = { ...(detail ?? {}) };
+        delete eventDetail.mode;
+
+        const hasExplicitModeScope = type.startsWith("pref-viewer-2d-")
+            || type.startsWith("pref-viewer-3d-")
+            || type.startsWith("drawing-")
+            || type.startsWith("scene-");
+
+        if (!hasExplicitModeScope) {
+            eventDetail.mode = this.#mode;
+        }
+        eventDetail.timestamp = Date.now();
+
+        this.dispatchEvent(
+            new CustomEvent(type, {
+                bubbles: true,
+                cancelable: false,
+                composed: true,
+                detail: eventDetail,
+            }),
+        );
+    }
+
+    /**
+     * Normalizes a mixed array of element descriptors into a plain string-id list.
+     * Accepts raw strings, objects with an `id` property, or objects with an `Id` property.
+     * Non-string and empty-string results are filtered out.
+     * @private
+     * @param {Array<string|{id?: string, Id?: string}>} value - Array of id-like items to normalize.
+     * @returns {string[]} Deduplicated, non-empty string ids.
+     */
+    #normalizeIdList(value) {
+        if (!Array.isArray(value)) {
+            return [];
+        }
+        return value.map((item) => (typeof item === "string" ? item : (item?.id ?? item?.Id))).filter((id) => typeof id === "string" && id.length > 0);
+    }
+
+    /**
+     * Normalizes a mixed array of selection descriptors into a canonical list of selection items.
+     * Each output item contains an `id` string and a `highlights` string array.
+     * Accepts raw id strings (expanded to `{ id, highlights: [id] }`), or objects with
+     * `id`/`Id` and optional `highlights`/`Highlights` fields.
+     * Items that cannot be resolved to a non-empty string id are discarded.
+     * @private
+     * @param {Array<string|{id?: string, Id?: string, highlights?: string[], Highlights?: string[]}>} value - Raw selection descriptors.
+     * @returns {Array<{id: string, highlights: string[]}>} Normalized, non-null selection items.
+     */
+    #normalizeSelectionItems(value) {
+        if (!Array.isArray(value)) {
+            return [];
+        }
+        return value
+            .map((item) => {
+                if (typeof item === "string") {
+                    return { id: item, highlights: [item] };
+                }
+                const id = item?.id ?? item?.Id;
+                if (typeof id !== "string" || id.length === 0) {
+                    return null;
+                }
+                const highlights = item?.highlights ?? item?.Highlights ?? [id];
+                return {
+                    id,
+                    highlights: this.#normalizeIdList(highlights),
+                };
+            })
+            .filter(Boolean);
+    }
+
+    /**
+     * Dispatches a `pref-viewer-selection-state-changed` event carrying the current selection snapshot.
+     * Called whenever `selectableIds`, `selectedIds`, or `selectedItems` change.
+     * @private
+     * @returns {void}
+     */
+    #emitSelectionStateChanged() {
+        this.#dispatchPrefViewerEvent("pref-viewer-selection-state-changed", this.getSelectionState());
+    }
+
+    /**
+     * Dispatches a `pref-viewer-3d-turnable-changed` event carrying the current turnable snapshot.
+     * Called after `startTurnable`, `stopTurnable`, or `toggleTurnable` mutates the internal state.
+     * @private
+     * @returns {void}
+     */
+    #emitTurnableChanged() {
+        this.#dispatchPrefViewerEvent("pref-viewer-3d-turnable-changed", { state: this.getTurnableState() });
+    }
+
     /**
      * ---------------------------
      * Public methods
@@ -1070,13 +1246,25 @@ export default class PrefViewer extends HTMLElement {
         if (!config) {
             return false;
         }
-        this.#addTaskToQueue(config, "config");
-        if (config.drawing) {
-            this.#addTaskToQueue(config.drawing, "drawing");
+        if (config.styles) {
+            this.#addTaskToQueue(config.styles, "styles");
         }
         if (config.culture) {
             this.#addTaskToQueue(config.culture, "culture");
         }
+        this.#addTaskToQueue(config, "config");
+        if (config.drawing) {
+            this.#addTaskToQueue(config.drawing, "drawing");
+        }
+    }
+
+    /**
+     * Returns a diagnostic snapshot for the active 3D runtime.
+     * @public
+     * @returns {object|null} Debug information, or null when the 3D component is not initialized.
+     */
+    getDebugInfo() {
+        return this.#component3D?.getDebugInfo?.() ?? null;
     }
 
     /**
@@ -1188,6 +1376,191 @@ export default class PrefViewer extends HTMLElement {
         this.#addTaskToQueue(options, "options");
     }
 
+    /**
+     * Sets supported PrefViewer style variables from an object or JSON string and adds them to the task queue.
+     * Currently supports `colorPrimary`, which updates `PrefViewerStyleVariables.colorPrimary`, applies the host CSS custom property, and persists the value in localStorage.
+     * @public
+     * @param {object|string} styles - Style overrides object or JSON string.
+     * @returns {boolean|void} Returns false if styles are invalid; otherwise void.
+     */
+    setStyles(styles) {
+        styles = typeof styles === "string" ? JSON.parse(styles) : styles;
+        if (!styles || typeof styles !== "object") {
+            return false;
+        }
+        this.#addTaskToQueue(styles, "styles");
+    }
+
+    /**
+     * Sets image-based lighting options using the stable contract entry point.
+     * @public
+     * @param {object|string} ibl - IBL options payload.
+     * @returns {boolean|void} Returns false if options are invalid; otherwise void.
+     */
+    setIBL(ibl) {
+        ibl = typeof ibl === "string" ? JSON.parse(ibl) : ibl;
+        if (!ibl) {
+            return false;
+        }
+        return this.setOptions({ ibl });
+    }
+
+    /**
+     * Defines the elements that the host application considers selectable.
+     * This method stores the contract state; visual selection rendering is handled by host-specific follow-up work.
+     * @public
+     * @param {Array<string|{id?: string, Id?: string}>} elements - Element ids or objects containing id/Id.
+     * @returns {object} Current selection state.
+     */
+    setSelectableElements(elements = []) {
+        this.#selectionState.selectableIds = this.#normalizeIdList(elements);
+        this.#emitSelectionStateChanged();
+        return this.getSelectionState();
+    }
+
+    /**
+     * Defines the currently selected elements using the semantic PrefViewer contract.
+     * @public
+     * @param {Array<string|{id?: string, Id?: string, highlights?: string[], Highlights?: string[]}>} elements - Element ids or objects containing id/Id and optional highlights/Highlights.
+     * @returns {object} Current selection state.
+     */
+    setSelectedElements(elements = []) {
+        const selectedItems = this.#normalizeSelectionItems(elements);
+        this.#selectionState.selectedItems = selectedItems;
+        this.#selectionState.selectedIds = selectedItems.map((item) => item.id);
+        this.#emitSelectionStateChanged();
+        return this.getSelectionState();
+    }
+
+    /**
+     * Applies a complete host selection state in one call.
+     * @public
+     * @param {{selectableIds?: string[], selectables?: string[], selectedItems?: object[], selectedIds?: string[], selected?: string[]}} state - Selection state with selectableIds/selectables and selectedItems/selectedIds/selected.
+     * @returns {object} Current selection state.
+     */
+    applySelectionState(state = {}) {
+        this.#selectionState.selectableIds = this.#normalizeIdList(state.selectableIds ?? state.selectables ?? []);
+        this.setSelectedElements(state.selectedItems ?? state.selectedIds ?? state.selected ?? []);
+        return this.getSelectionState();
+    }
+
+    /**
+     * Clears selected elements while keeping the selectable set.
+     * @public
+     * @returns {object} Current selection state.
+     */
+    clearSelectedElements() {
+        this.#selectionState.selectedIds = [];
+        this.#selectionState.selectedItems = [];
+        this.#emitSelectionStateChanged();
+        return this.getSelectionState();
+    }
+
+    /**
+     * Clears selectable elements while keeping the current selected state.
+     * @public
+     * @returns {object} Current selection state.
+     */
+    clearSelectableElements() {
+        this.#selectionState.selectableIds = [];
+        this.#emitSelectionStateChanged();
+        return this.getSelectionState();
+    }
+
+    /**
+     * Clears all semantic selection state.
+     * @public
+     * @returns {object} Current selection state.
+     */
+    clearSelectionState() {
+        this.#selectionState = {
+            selectableIds: [],
+            selectedIds: [],
+            selectedItems: [],
+        };
+        this.#emitSelectionStateChanged();
+        return this.getSelectionState();
+    }
+
+    /**
+     * Returns the current semantic selection state.
+     * @public
+     * @returns {{selectableIds: string[], selectedIds: string[], selectedItems: object[]}}
+     */
+    getSelectionState() {
+        return {
+            selectableIds: [...this.#selectionState.selectableIds],
+            selectedIds: [...this.#selectionState.selectedIds],
+            selectedItems: this.#selectionState.selectedItems.map((item) => ({
+                id: item.id,
+                highlights: [...item.highlights],
+            })),
+        };
+    }
+
+    /**
+     * Contract hook for host-driven element click forwarding.
+     * Internal 2D/3D hit-testing can call this once it exposes stable element ids.
+     * @public
+     * @param {object|string} element - Element id or detail object.
+     * @returns {void}
+     */
+    notifyElementClick(element) {
+        const detail = typeof element === "string" ? { id: element } : { ...(element ?? {}) };
+        this.#dispatchPrefViewerEvent("pref-viewer-element-click", {
+            element: detail,
+        });
+    }
+
+    /**
+     * Starts the semantic turnable state.
+     * @public
+     * @param {{speed?: number, direction?: string}} [options] - Optional speed/direction values.
+     * @returns {object} Current turnable state.
+     */
+    startTurnable(options = {}) {
+        this.#turnableState = {
+            ...this.#turnableState,
+            ...options,
+            running: true,
+        };
+        this.#emitTurnableChanged();
+        return this.getTurnableState();
+    }
+
+    /**
+     * Stops the semantic turnable state.
+     * @public
+     * @returns {object} Current turnable state.
+     */
+    stopTurnable() {
+        this.#turnableState = {
+            ...this.#turnableState,
+            running: false,
+        };
+        this.#emitTurnableChanged();
+        return this.getTurnableState();
+    }
+
+    /**
+     * Toggles the semantic turnable state.
+     * @public
+     * @param {object} [options] - Optional speed/direction values used when starting.
+     * @returns {object} Current turnable state.
+     */
+    toggleTurnable(options = {}) {
+        return this.#turnableState.running ? this.stopTurnable() : this.startTurnable(options);
+    }
+
+    /**
+     * Returns the current semantic turnable state.
+     * @public
+     * @returns {{running: boolean, speed: number, direction: string}}
+     */
+    getTurnableState() {
+        return { ...this.#turnableState };
+    }
+
     /**
      * Opens a modal dialog with the specified title, content, and footer.
      * @public
@@ -1433,31 +1806,20 @@ export default class PrefViewer extends HTMLElement {
     }
 
     /**
-     * Redirects scene assignments to `loadScene()` for normalized handling.
-     * @public
-     * @param {object|string} value - Scene payload or serialized JSON.
-     */
-    set scene(value) {
-        this.loadScene(value);
-    }
-
-    /**
-     * Enables or disables the hover highlight effect at runtime.
-     * Accepts boolean or string "true"/"false".
+     * Sends style updates to `setStyles()` enabling reactive bindings.
      * @public
-     * @param {boolean|string} value
+     * @param {object|string} value - Style overrides object or JSON string.
      */
-    set highlightEnabled(value) {
-        this.setAttribute("highlight-enabled", String(value));
+    set styles(value) {
+        this.setStyles(value);
     }
-
     /**
-     * Sets the hover highlight color at runtime.
+     * Redirects scene assignments to `loadScene()` for normalized handling.
      * @public
-     * @param {string} value - Hex color string, e.g. "#ff6700".
+     * @param {object|string} value - Scene payload or serialized JSON.
      */
-    set highlightColor(value) {
-        this.setAttribute("highlight-color", value);
+    set scene(value) {
+        this.loadScene(value);
     }
 
     /**