@preference-sl/pref-viewer 2.16.0-beta.1 → 2.16.0-beta.11

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

@@ -3,34 +3,32 @@ import BabylonJSController from "./babylonjs-controller.js";
 import { DEFAULT_LOCALE, resolveLocale, translate } from "./localization/i18n.js";
 
 /**
- * PrefViewerMenu3D - Localized floating control surface for Babylon render toggles used by PrefViewer.
+ * PrefViewerMenu3D - Localized floating control panel for Babylon.js render settings.
  *
- * Capabilities:
- *  - Builds an accessible hover/focus-activated panel with switches for AA, SSAO, IBL, and dynamic shadows.
- *  - Caches translated copy in `#texts` and listens for culture changes via the `culture` attribute or `setCulture()`.
- *  - Tracks applied vs. draft render settings so pending diffs, button enablement, and status text stay in sync.
- *  - Supports per-switch availability (enabled/disabled), preventing interaction and pending diffs for unavailable toggles.
- *  - Emits `pref-viewer-menu-3d-apply` whenever the user confirms toggles, allowing PrefViewer/BabylonJSController to persist.
- *  - Shows transient status/error messages and per-switch pending states while operations complete.
+ * Renders a gear-icon toggle button that appears on viewer hover and opens a panel with:
+ *  - Boolean switches for every boolean render setting (AA, SSAO, IBL, shadows, highlight, etc.).
+ *  - A hue slider for the highlight color.
+ *  - A time-of-day slider with play/pause continuous lighting-cycle animation.
+ *
+ * Every interaction emits `pref-viewer-3d-render-settings-change-requested` immediately; there is no Apply button or
+ * draft/pending state. Switch changes emit the full settings snapshot, while highlight color and
+ * lighting changes emit partial payloads to avoid unnecessary scene reloads.
  *
  * Public API:
- *  - `setSettings(settings)`: hydrates switches with the latest applied render snapshot.
- *  - `setApplying(isApplying, hasError?)`: locks the UI and optionally displays errors while async updates run.
- *  - `setViewerHover(isHovering)`: opens/closes the panel based on viewer hover state.
- *  - `setEnabled(isEnabled)`: hides the menu in 2D mode and clears hover data.
- *  - `setSwitchEnabled(settingKey, isEnabled)`: enables/disables a concrete toggle (e.g. IBL) based on runtime availability.
- *  - `setCulture(cultureId)`: forces a locale change and re-renders copy from the i18n layer.
+ *  - `setSettings(settings)`: syncs the UI with the latest render settings snapshot.
+ *  - `setApplying(isApplying)`: locks interactions while an async apply operation is running.
+ *  - `setViewerHover(isHovering)`: drives panel visibility from the 3D viewport hover state.
+ *  - `setEnabled(isEnabled)`: hides the menu when 3D mode is unavailable.
+ *  - `setElementEnabled(settingKey, isEnabled)`: enables/disables a specific switch or slider at runtime.
+ *  - `setElementVisible(settingKey, isVisible)`: shows/hides a specific switch or slider at runtime.
+ *  - `setCulture(cultureId)`: switches the display locale.
  *
- * Lifecycle & Integration:
- *  - Automatically creates shadow DOM/UI in `connectedCallback`, wiring hover/focus listeners and ARIA labels.
- *  - Exposes a single `culture` observed attribute so hosts can drive localization declaratively.
+ * Observed attributes: `culture`. Runtime render values are synchronized through `setSettings()`.
  *
- * Accessibility:
- *  - Uses ARIA labels/live regions for the toggle button, dialog panel, pending indicator, and status slot.
+ * Events emitted: `pref-viewer-3d-render-settings-change-requested` - `{ detail: { settings: object } }`.
  */
 export default class PrefViewerMenu3D extends HTMLElement {
     #elements = {
-        applyButton: null,
         colorPicker: null,
         colorSlider: null,
         colorPickerPreview: null,
@@ -43,8 +41,8 @@ export default class PrefViewerMenu3D extends HTMLElement {
         lightingSlider: null,
         lightingValue: null,
         panel: null,
-        pendingLabel: null,
-        status: null,
+        sliders: {},
+        sliderWrappers: {},
         subtitle: null,
         switches: {},
         switchCopyNodes: {},
@@ -54,7 +52,6 @@ export default class PrefViewerMenu3D extends HTMLElement {
     };
 
     #handles = {
-        onApplyClick: null,
         onColorSliderInput: null,
         onLightingSliderInput: null,
         onLightingPlayClick: null,
@@ -65,25 +62,29 @@ export default class PrefViewerMenu3D extends HTMLElement {
     };
 
     #DEFAULT_RENDER_SETTINGS = { ...BabylonJSController.DEFAULT_RENDER_SETTINGS };
-    // Only include boolean settings as switches (exclude illuminationColor which is handled by color picker)
+    // Only include boolean settings as switches; scalar settings are handled by sliders.
     #MENU_SWITCHES = Object.keys(this.#DEFAULT_RENDER_SETTINGS).filter(key => 
         typeof this.#DEFAULT_RENDER_SETTINGS[key] === "boolean"
     );
-    #appliedSettings = { ...this.#DEFAULT_RENDER_SETTINGS };
-    #draftSettings = { ...this.#DEFAULT_RENDER_SETTINGS };
-    #switchAvailability = {};
-    #statusTimeout = null;
+    #settings = { ...this.#DEFAULT_RENDER_SETTINGS };
+    #elementAvailability = {};
+    #elementVisibility = {};
     #isApplying = false;
     #isEnabled = true;
     #isLightingPlaying = false;
     #lightingAnimationFrame = null;
     #lightingPlaybackStart = 0;
     #lightingPlaybackBase = 0.5;
-    #lightingPlaybackDurationMs = 28000;
+    #lightingPlaybackDurationMs = 15000;
 
     #culture = DEFAULT_LOCALE;
     #texts = {};
     
+    /**
+     * Creates the menu custom element.
+     * Rendering is deferred until connectedCallback() so attributes can be set before the UI is built.
+     * @public
+     */
     constructor() {
         super();
     }
@@ -94,40 +95,22 @@ export default class PrefViewerMenu3D extends HTMLElement {
      * @returns {string[]} Array of attribute names to observe.
      */
     static get observedAttributes() {
-        return ["culture", "show-illumination", "illumination-color", "lighting-time-of-day"];
+        return ["culture"];
     }
     
     /**
-     * Reacts to observed attribute mutations, currently handling locale changes.
+     * Reacts to observed attribute mutations and mirrors them into the internal settings/UI state.
      * @public
-     * @param {string} name - Attribute name that changed.
-     * @param {*} _old - Previous attribute value (unused).
-     * @param {*} value - New attribute value.
+     * @param {"culture"} name - Attribute name that changed.
+     * @param {string|null} _old - Previous attribute value (unused).
+     * @param {string|null} value - New attribute value.
      * @returns {void}
      */
     attributeChangedCallback(name, _old, value) {
-        if (name === "culture") {
-            this.#setCultureInternal(value || DEFAULT_LOCALE);
-        } else if (name === "show-illumination" || name === "illumination-color") {
-            // Update draft settings when attributes change
-            if (name === "show-illumination") {
-                this.#draftSettings.illuminationEnabled = value === "true" || value === true;
-                // Update the corresponding switch if it exists
-                const switchEl = this.#elements.switches?.illuminationEnabled;
-                if (switchEl) {
-                    switchEl.checked = this.#draftSettings.illuminationEnabled;
-                }
-            } else if (name === "illumination-color") {
-                this.#draftSettings.illuminationColor = value;
-                // Update color picker preview if exists
-                this.#updateColorPickerPreview(value);
-            }
-        } else if (name === "lighting-time-of-day") {
-            const parsed = Number(value);
-            if (Number.isFinite(parsed)) {
-                this.#draftSettings.lightingTimeOfDay = this.#clampLightingTime(parsed);
-                this.#updateLightingSliderUI(this.#draftSettings.lightingTimeOfDay);
-            }
+        switch (name) {
+            case "culture":
+                this.#setCultureInternal(value || DEFAULT_LOCALE);
+                break;
         }
     }
 
@@ -143,27 +126,23 @@ export default class PrefViewerMenu3D extends HTMLElement {
             this.#createDOMElements();
             this.#cacheElements();
             this.#attachEvents();
-            this.setSettings(this.#appliedSettings);
+            this.setSettings(this.#settings);
         }
     }
 
     /**
      * Lifecycle hook invoked when the element is removed from the DOM.
-     * Cleans up listeners and pending timers to avoid leaks.
+     * Cleans up listeners and stops lighting playback to avoid leaks.
      * @public
      * @returns {void}
      */
     disconnectedCallback() {
         this.#detachEvents();
         this.#stopLightingPlayback();
-        if (this.#statusTimeout) {
-            clearTimeout(this.#statusTimeout);
-            this.#statusTimeout = null;
-        }
     }
 
     /**
-     * Builds the shadow DOM structure for the toggle button, panel, switches, and footer controls.
+     * Builds the internal DOM structure for the toggle button, panel, switches, color slider, and lighting controls.
      * @private
      * @returns {void}
      */
@@ -180,34 +159,31 @@ export default class PrefViewerMenu3D extends HTMLElement {
                     <p class="menu-subtitle">${this.#texts.subtitle}</p>
                 </div>
                 <div class="menu-switches">
-                    ${this.#MENU_SWITCHES.map((key) => this.#renderSwitchRow(key, this.#texts)).join("")}
+                    ${this.#MENU_SWITCHES.map((key) => this.#renderSwitchRow(key, this.#texts.features)).join("")}
                 </div>
-                <div class="menu-color-picker" data-setting="highlightColor">
+                <div class="menu-color-picker menu-slider" data-setting="highlightColor">
                     <div class="color-slider-row">
-                        <span class="color-picker-label">${this.#texts.switches?.highlightColor?.label || "Highlight Color"}</span>
-                        <span class="color-preview" style="background-color: ${this.#draftSettings.highlightColor || '#ff6700'}"></span>
+                        <span class="color-picker-label">${this.#texts.features?.highlightColor?.label || "Highlight Color"}</span>
+                        <span class="color-preview" style="background-color: ${this.#settings.highlightColor || '#ff6700'}"></span>
                     </div>
-                    <input type="range" class="color-slider" min="0" max="359" value="${PrefViewerMenu3D.#hexToHue(this.#draftSettings.highlightColor || '#ff6700')}">
+                    <input type="range" data-setting="highlightColor" class="color-slider" min="0" max="359" value="${PrefViewerMenu3D.#hexToHue(this.#settings.highlightColor || '#ff6700')}">
                 </div>
-                <div class="menu-lighting-slider" data-setting="lightingTimeOfDay">
+                <div class="menu-lighting-slider menu-slider" data-setting="lightingTimeOfDay">
                     <div class="lighting-slider-row">
-                        <span class="lighting-slider-label">${this.#texts.switches?.lightingTimeOfDay?.label || "Time of day"}</span>
-                        <span class="lighting-slider-value">${PrefViewerMenu3D.#formatLightingTime(this.#draftSettings.lightingTimeOfDay ?? 0.5)}</span>
+                        <span class="lighting-slider-label menu-slider-label">${this.#texts.features?.lightingTimeOfDay?.label || "Time of day"}</span>
+                        <span class="lighting-slider-value">${PrefViewerMenu3D.#formatLightingTime(this.#settings.lightingTimeOfDay ?? 0.5)}</span>
                     </div>
-                    <input type="range" class="lighting-slider" min="0" max="1000" step="1" value="${Math.round((this.#draftSettings.lightingTimeOfDay ?? 0.5) * 1000)}">
+                    <input type="range" data-setting="lightingTimeOfDay" class="lighting-slider" min="0" max="1000" step="1" value="${Math.round((this.#settings.lightingTimeOfDay ?? 0.5) * 1000)}">
                     <div class="lighting-slider-markers" aria-hidden="true">
-                        <span class="lighting-slider-start">${this.#texts.switches?.lightingTimeOfDay?.startLabel || "Night"}</span>
-                        <span class="lighting-slider-mid">${this.#texts.switches?.lightingTimeOfDay?.midLabel || "Day"}</span>
-                        <span class="lighting-slider-end">${this.#texts.switches?.lightingTimeOfDay?.endLabel || "Night"}</span>
+                        <span class="lighting-slider-start">${this.#texts.features?.lightingTimeOfDay?.startLabel || "Night"}</span>
+                        <span class="lighting-slider-mid">${this.#texts.features?.lightingTimeOfDay?.midLabel || "Day"}</span>
+                        <span class="lighting-slider-end">${this.#texts.features?.lightingTimeOfDay?.endLabel || "Night"}</span>
                     </div>
                     <div class="lighting-slider-actions">
                         <button type="button" class="lighting-play-button">${this.#texts.actions?.play || "Play"}</button>
                     </div>
                 </div>
-                <div class="menu-footer">
-                    <span class="menu-pending" aria-live="polite">${this.#texts.pendingLabel}</span>
-                    <span class="menu-status" aria-live="assertive"></span>
-                </div>
+                <div class="menu-footer"></div>
             </div>
         `;
         const style = document.createElement("style");
@@ -216,14 +192,14 @@ export default class PrefViewerMenu3D extends HTMLElement {
     }
 
     /**
-     * Generates the HTML fragment for a single render-setting switch.
+     * Generates the HTML fragment for a single boolean render-setting switch.
      * @private
-     * @param {string} key - Render setting identifier (aa, ssao, ibl, etc.).
-     * @param {object} copy - Locale-aware copy bundle used for labels.
+     * @param {string} key - Render setting key from BabylonJSController.DEFAULT_RENDER_SETTINGS.
+     * @param {Record<string, {label?: string, helper?: string}>} copy - Locale-aware feature copy used for labels.
      * @returns {string} HTML string representing the switch row.
      */
     #renderSwitchRow(key, copy) {
-        const switchCopy = copy.switches?.[key] ?? {};
+        const switchCopy = copy?.[key] ?? {};
         const label = switchCopy.label ?? key;
         const helper = switchCopy.helper ?? "";
         return `
@@ -243,7 +219,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
     /**
      * Pulls the full translation namespace for the menu using the active culture.
      * @private
-     * @returns {object} Resolved translation object or an empty fallback.
+     * @returns {object} Resolved `prefViewer.menu3d` translation object or an empty fallback.
      */
     #getMenuNamespace() {
         const namespace = translate("prefViewer.menu3d", { locale: this.#culture });
@@ -253,24 +229,18 @@ export default class PrefViewerMenu3D extends HTMLElement {
     /**
      * Normalizes locale data into a predictable shape consumed by the UI helpers.
      * @private
-     * @returns {object} Structured copy bundle for titles, actions, status, and switches.
+     * @returns {{title: string, subtitle: string, actions: {play: string, pause: string}, features: object}} Structured copy bundle for titles, actions, and feature labels.
      */
     #getMenuTexts() {
         const data = this.#getMenuNamespace();
         return {
             title: data.title || "",
             subtitle: data.subtitle || "",
-            pendingLabel: data.pendingLabel || "",
             actions: {
-                apply: data.actions?.apply || "",
-                applying: data.actions?.applying || "",
                 play: data.actions?.play || "",
                 pause: data.actions?.pause || "",
             },
-            status: {
-                error: data.status?.error || "",
-            },
-            switches: data.switches || {},
+            features: data.features || {},
         };
     }
 
@@ -291,34 +261,28 @@ export default class PrefViewerMenu3D extends HTMLElement {
         if (this.#elements.subtitle) {
             this.#elements.subtitle.textContent = this.#texts.subtitle;
         }
-        if (this.#elements.pendingLabel) {
-            this.#elements.pendingLabel.textContent = this.#texts.pendingLabel;
-        }
-        if (this.#elements.applyButton) {
-            this.#elements.applyButton.textContent = this.#isApplying ? this.#texts.actions.applying : this.#texts.actions.apply;
-        }
         if (this.#elements.lightingPlayButton) {
             this.#elements.lightingPlayButton.textContent = this.#isLightingPlaying ? (this.#texts.actions.pause || "Pause") : (this.#texts.actions.play || "Play");
             this.#elements.lightingPlayButton.setAttribute("aria-pressed", this.#isLightingPlaying ? "true" : "false");
         }
         if (this.#elements.lightingSliderLabel) {
-            this.#elements.lightingSliderLabel.textContent = this.#texts.switches?.lightingTimeOfDay?.label || "Time of day";
+            this.#elements.lightingSliderLabel.textContent = this.#texts.features?.lightingTimeOfDay?.label || "Time of day";
         }
         if (this.#elements.lightingSliderStart) {
-            this.#elements.lightingSliderStart.textContent = this.#texts.switches?.lightingTimeOfDay?.startLabel || "Night";
+            this.#elements.lightingSliderStart.textContent = this.#texts.features?.lightingTimeOfDay?.startLabel || "Night";
         }
         if (this.#elements.lightingSliderMid) {
-            this.#elements.lightingSliderMid.textContent = this.#texts.switches?.lightingTimeOfDay?.midLabel || "Day";
+            this.#elements.lightingSliderMid.textContent = this.#texts.features?.lightingTimeOfDay?.midLabel || "Day";
         }
         if (this.#elements.lightingSliderEnd) {
-            this.#elements.lightingSliderEnd.textContent = this.#texts.switches?.lightingTimeOfDay?.endLabel || "Night";
+            this.#elements.lightingSliderEnd.textContent = this.#texts.features?.lightingTimeOfDay?.endLabel || "Night";
         }
         this.#updateLightingPlayButtonUI();
         Object.entries(this.#elements.switchCopyNodes).forEach(([key, nodes]) => {
             if (!nodes) {
                 return;
             }
-            const switchCopy = this.#texts.switches?.[key] ?? {};
+            const switchCopy = this.#texts.features?.[key] ?? {};
             nodes.title && (nodes.title.textContent = switchCopy.label ?? key);
             nodes.helper && (nodes.helper.textContent = switchCopy.helper ?? "");
         });
@@ -342,7 +306,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
     }
 
     /**
-     * Caches references to frequently used DOM nodes for faster lookups.
+     * Caches references to frequently used DOM nodes for event binding and UI synchronization.
      * @private
      * @returns {void}
      */
@@ -351,11 +315,8 @@ export default class PrefViewerMenu3D extends HTMLElement {
         this.#elements.panel = this.querySelector(".menu-panel");
         this.#elements.title = this.querySelector(".menu-title");
         this.#elements.subtitle = this.querySelector(".menu-subtitle");
-        this.#elements.applyButton = this.querySelector(".menu-apply");
-        this.#elements.pendingLabel = this.querySelector(".menu-pending");
-        this.#elements.status = this.querySelector(".menu-status");
-        
-        // Cache color picker elements
+
+        // Cache slider elements
         this.#elements.colorPicker = this.querySelector(".menu-color-picker");
         this.#elements.colorSlider = this.querySelector(".color-slider");
         this.#elements.colorPickerPreview = this.querySelector(".color-preview");
@@ -367,6 +328,11 @@ export default class PrefViewerMenu3D extends HTMLElement {
         this.#elements.lightingSliderEnd = this.querySelector(".lighting-slider-end");
         this.#elements.lightingSlider = this.querySelector(".lighting-slider");
         this.#elements.lightingValue = this.querySelector(".lighting-slider-value");
+
+        this.#elements.sliders["highlightColor"] = this.querySelector("input[data-setting='highlightColor']");
+        this.#elements.sliderWrappers["highlightColor"] = this.querySelector(".menu-slider[data-setting='highlightColor']");
+        this.#elements.sliders["lightingTimeOfDay"] = this.querySelector("input[data-setting='lightingTimeOfDay']");
+        this.#elements.sliderWrappers["lightingTimeOfDay"] = this.querySelector(".menu-slider[data-setting='lightingTimeOfDay']");
         
         this.#MENU_SWITCHES.forEach((key) => {
             this.#elements.switches[key] = this.querySelector(`input[data-setting="${key}"]`);
@@ -380,7 +346,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
     }
 
     /**
-     * Attaches all interactive event listeners for hover, focus, switch changes, and apply clicks.
+     * Attaches all interactive event listeners for hover, focus, switch, color, and lighting controls.
      * @private
      * @returns {void}
      */
@@ -397,7 +363,6 @@ export default class PrefViewerMenu3D extends HTMLElement {
             this.#closeMenu();
         };
         this.#handles.onSwitchChange = (event) => this.#handleSwitchChange(event);
-        this.#handles.onApplyClick = () => this.#emitApply();
         this.#handles.onColorSliderInput = (event) => this.#handleColorSliderInput(event);
         this.#handles.onLightingSliderInput = (event) => this.#handleLightingSliderInput(event);
         this.#handles.onLightingPlayClick = () => this.#toggleLightingPlayback();
@@ -407,7 +372,6 @@ export default class PrefViewerMenu3D extends HTMLElement {
         this.#elements.panel.addEventListener("mouseenter", this.#handles.onPanelEnter);
         this.addEventListener("mouseleave", this.#handles.onHostLeave);
         Object.values(this.#elements.switches).forEach((input) => input?.addEventListener("change", this.#handles.onSwitchChange));
-        this.#elements.applyButton?.addEventListener("click", this.#handles.onApplyClick);
         this.#elements.colorSlider?.addEventListener("input", this.#handles.onColorSliderInput);
         this.#elements.lightingSlider?.addEventListener("input", this.#handles.onLightingSliderInput);
         this.#elements.lightingPlayButton?.addEventListener("click", this.#handles.onLightingPlayClick);
@@ -427,8 +391,6 @@ export default class PrefViewerMenu3D extends HTMLElement {
         this.#elements.panel?.removeEventListener("mouseenter", this.#handles.onPanelEnter);
         this.removeEventListener("mouseleave", this.#handles.onHostLeave);
         Object.values(this.#elements.switches).forEach((input) => input?.removeEventListener("change", this.#handles.onSwitchChange));
-        this.#elements.applyButton?.removeEventListener("click", this.#handles.onApplyClick);
-        
         this.#elements.colorSlider?.removeEventListener("input", this.#handles.onColorSliderInput);
         this.#elements.lightingSlider?.removeEventListener("input", this.#handles.onLightingSliderInput);
         this.#elements.lightingPlayButton?.removeEventListener("click", this.#handles.onLightingPlayClick);
@@ -456,7 +418,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
     }
 
     /**
-     * Handles switch changes by updating the draft settings and recomputing pending indicators.
+     * Handles switch changes by updating settings and emitting a full settings snapshot.
      * @private
      * @param {Event} event - Change event triggered by a switch input.
      * @returns {void}
@@ -469,32 +431,28 @@ export default class PrefViewerMenu3D extends HTMLElement {
         if (!key) {
             return;
         }
-        this.#draftSettings[key] = event.currentTarget.checked;
-        this.#updatePendingState();
-
-        // For highlight toggle, apply immediately without waiting for user to click Apply
-        if (key === "highlightEnabled") {
-            this.#emitApply(true);
-        }
+        this.#settings[key] = event.currentTarget.checked;
+        this.#emitApply();
     }
 
     /**
-     * Handles clicks on the color picker buttons.
+     * Handles hue slider input by converting the selected hue to a highlight color.
+     * Emits a partial payload so highlight color changes apply without scheduling a render-settings reload.
      * @private
-     * @param {Event} event - Click event.
+     * @param {Event} event - Input event from the hue slider.
      * @returns {void}
      */
     #handleColorSliderInput(event) {
         const hue = parseInt(event.target.value, 10);
         const color = PrefViewerMenu3D.#hueToHex(hue);
-        this.#draftSettings.highlightColor = color;
+        this.#settings.highlightColor = color;
         this.#updateColorPickerPreview(color);
-        this.#updatePendingState();
-        this.#emitApply(true);
+        this.#emitApply({ highlightColor: color }, { partial: true });
     }
 
     /**
-     * Handles lighting cycle slider input by updating the draft state and applying it immediately.
+     * Handles lighting cycle slider input by updating the normalized time-of-day value.
+     * Emits a partial payload so lighting changes apply immediately without scheduling a render-settings reload.
      * @private
      * @param {Event} event - Input event from the time-of-day slider.
      * @returns {void}
@@ -505,14 +463,13 @@ export default class PrefViewerMenu3D extends HTMLElement {
             return;
         }
         const normalized = this.#clampLightingTime(rawValue / 1000);
-        this.#draftSettings.lightingTimeOfDay = normalized;
+        this.#settings.lightingTimeOfDay = normalized;
         if (this.#isLightingPlaying) {
             this.#lightingPlaybackBase = normalized;
             this.#lightingPlaybackStart = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
         }
         this.#updateLightingSliderUI(normalized);
-        this.#updatePendingState();
-        this.#emitApply(true);
+        this.#emitApply({ lightingTimeOfDay: normalized }, { partial: true });
     }
 
     /**
@@ -530,6 +487,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
 
     /**
      * Starts the continuous day/night playback loop.
+     * The playback speed is controlled by `#lightingPlaybackDurationMs`, which represents one full 0..1 cycle.
      * @private
      * @returns {void}
      */
@@ -538,7 +496,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
             return;
         }
         this.#isLightingPlaying = true;
-        this.#lightingPlaybackBase = this.#draftSettings.lightingTimeOfDay ?? 0.5;
+        this.#lightingPlaybackBase = this.#settings.lightingTimeOfDay ?? 0.5;
         this.#lightingPlaybackStart = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
         this.#updateLightingPlayButtonUI();
         const tick = () => {
@@ -548,9 +506,9 @@ export default class PrefViewerMenu3D extends HTMLElement {
             const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
             const elapsed = now - this.#lightingPlaybackStart;
             const cycle = (this.#lightingPlaybackBase + (elapsed / this.#lightingPlaybackDurationMs)) % 1;
-            this.#draftSettings.lightingTimeOfDay = cycle;
+            this.#settings.lightingTimeOfDay = cycle;
             this.#updateLightingSliderUI(cycle);
-            this.#emitApply(true, { persist: false });
+            this.#emitApply({ lightingTimeOfDay: cycle, persist: false }, { partial: true });
             this.#lightingAnimationFrame = requestAnimationFrame(tick);
         };
         this.#lightingAnimationFrame = requestAnimationFrame(tick);
@@ -559,6 +517,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
     /**
      * Stops the continuous day/night playback loop.
      * @private
+     * @param {boolean} [persist=false] - True to emit a final apply event that should be persisted by the host.
      * @returns {void}
      */
     #stopLightingPlayback(persist = false) {
@@ -568,7 +527,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
             this.#lightingAnimationFrame = null;
         }
         if (persist) {
-            this.#emitApply(true, { persist: true });
+            this.#emitApply({ lightingTimeOfDay: this.#settings.lightingTimeOfDay, persist: true }, { partial: true });
         }
         this.#updateLightingPlayButtonUI();
     }
@@ -587,6 +546,12 @@ export default class PrefViewerMenu3D extends HTMLElement {
         this.#elements.lightingPlayButton.setAttribute("aria-pressed", this.#isLightingPlaying ? "true" : "false");
     }
 
+    /**
+     * Converts a hue angle into a saturated hex color.
+     * @private
+     * @param {number} hue - Hue angle in degrees. Values outside 0..359 wrap around.
+     * @returns {string} Hex color string in "#rrggbb" format.
+     */
     static #hueToHex(hue) {
         const h = ((hue % 360) + 360) % 360;
         const a = Math.min(0.5, 1 - 0.5);
@@ -597,6 +562,12 @@ export default class PrefViewerMenu3D extends HTMLElement {
         return '#' + [f(0), f(8), f(4)].map((v) => Math.round(v * 255).toString(16).padStart(2, '0')).join('');
     }
 
+    /**
+     * Extracts the hue angle from a hex color string.
+     * @private
+     * @param {string} hex - Hex color string in "#rrggbb" format.
+     * @returns {number} Hue angle in degrees, or the default orange hue when the value is invalid.
+     */
     static #hexToHue(hex) {
         if (!hex || hex.length < 7) return 24;
         const r = parseInt(hex.slice(1, 3), 16) / 255;
@@ -609,6 +580,12 @@ export default class PrefViewerMenu3D extends HTMLElement {
         return Math.round(h * 60);
     }
 
+    /**
+     * Formats a normalized lighting-cycle value as a 24-hour clock label.
+     * @private
+     * @param {number} value - Normalized time-of-day value between 0 and 1.
+     * @returns {string} Time label formatted as "HH:mm".
+     */
     static #formatLightingTime(value) {
         const normalized = Math.min(1, Math.max(0, Number(value) || 0));
         const minutes = Math.round(normalized * 24 * 60) % (24 * 60);
@@ -617,6 +594,12 @@ export default class PrefViewerMenu3D extends HTMLElement {
         return `${String(hours).padStart(2, "0")}:${String(mins).padStart(2, "0")}`;
     }
 
+    /**
+     * Clamps a lighting-cycle value to the supported normalized range.
+     * @private
+     * @param {number} value - Value to clamp.
+     * @returns {number} Clamped value between 0 and 1, or 0.5 when the input is invalid.
+     */
     #clampLightingTime(value) {
         if (!Number.isFinite(value)) {
             return 0.5;
@@ -625,7 +608,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
     }
 
     /**
-     * Updates the color picker UI (input value, preview, selected button).
+     * Updates the color picker UI, including the hue slider and color preview.
      * @private
      * @param {string} color - Selected color.
      * @returns {void}
@@ -669,129 +652,60 @@ export default class PrefViewerMenu3D extends HTMLElement {
     }
 
     /**
-     * Emits the apply event with the current draft settings when changes are pending.
+     * Emits the apply event with the current settings immediately unless the menu is locked.
      * @private
+     * @param {object} [extraSettings={}] - Additional fields merged into the emitted settings payload, or the complete payload when `options.partial` is true.
+     * @param {object} [options={}] - Event payload options.
+     * @param {boolean} [options.partial=false] - True to emit only `extraSettings` instead of the full settings snapshot.
      * @returns {void}
      */
-    #emitApply(force = false, extraSettings = {}) {
-        // For illumination/color changes, we apply immediately regardless of pending state
-        if (!force && this.#isApplying) {
+    #emitApply(extraSettings = {}, options = {}) {
+        if (this.#isApplying) {
             return;
         }
-
-        const detail = { settings: { ...this.#draftSettings, ...extraSettings } };
-        const customEventOptions = {
+        const detail = { settings: options.partial ? { ...extraSettings } : { ...this.#settings, ...extraSettings } };
+        const eventOptions = {
             bubbles: true,
             cancelable: true,
             composed: true,
-            detail: detail,
+            detail,
         };
-        this.dispatchEvent(new CustomEvent("pref-viewer-menu-3d-apply", customEventOptions));
+        this.dispatchEvent(new CustomEvent("pref-viewer-3d-render-settings-change-requested", eventOptions));
     }
 
     /**
-     * Synchronizes checkbox states with the draft settings snapshot.
+     * Synchronizes checkbox states with the current settings snapshot.
      * @private
      * @returns {void}
      */
     #updateSwitches() {
         Object.entries(this.#elements.switches).forEach(([key, input]) => {
             if (input) {
-                const isEnabled = this.#switchAvailability[key] !== false;
-                input.checked = Boolean(this.#draftSettings[key]);
+                const isEnabled = this.#elementAvailability[key] !== false;
+                const isVisible = this.#elementVisibility[key] !== false;
+                input.checked = Boolean(this.#settings[key]);
                 input.disabled = !isEnabled;
                 this.#elements.switchWrappers[key]?.toggleAttribute("data-disabled", !isEnabled);
+                this.#elements.switchWrappers[key]?.toggleAttribute("data-hidden", !isVisible);
             }
         });
     }
 
     /**
-     * Toggles pending labels, apply button state, and per-switch markers based on outstanding changes.
+     * Synchronizes slider states with the current settings snapshot.
      * @private
      * @returns {void}
      */
-    #updatePendingState() {
-        const pendingKeys = this.#getPendingKeys();
-        const pending = pendingKeys.length > 0;
-        if (this.#elements.pendingLabel) {
-            this.#elements.pendingLabel.hidden = !pending;
-        }
-        if (!this.#isApplying && this.#elements.applyButton) {
-            this.#elements.applyButton.disabled = !pending;
-        }
-        this.#updateSwitchPendingIndicators(pendingKeys);
-    }
-
-    /**
-     * Calculates which render keys differ between draft and applied snapshots.
-     * @private
-     * @returns {string[]} Keys currently pending application.
-     */
-    #getPendingKeys() {
-        return Object.keys(this.#DEFAULT_RENDER_SETTINGS).filter((key) => {
-            if (key === "lightingTimeOfDay") {
-                return false;
-            }
-            if (this.#elements.switches[key]?.disabled) {
-                return false;
-            }
-            return this.#draftSettings[key] !== this.#appliedSettings[key];
-        });
-    }
-
-    /**
-     * Convenience helper to check if any pending changes exist.
-     * @private
-     * @returns {boolean}
-     */
-    #hasPendingChanges() {
-        return this.#getPendingKeys().length > 0;
-    }
-
-    /**
-     * Adds or removes the `data-pending` attribute on switch wrappers to visually flag unsaved toggles.
-     * @private
-     * @param {string[]} pendingKeys - Keys currently pending.
-     * @returns {void}
-     */
-    #updateSwitchPendingIndicators(pendingKeys = []) {
-        Object.entries(this.#elements.switchWrappers).forEach(([key, wrapper]) => {
-            if (!wrapper) {
-                return;
+    #updateSliders() {
+        Object.entries(this.#elements.sliders).forEach(([key, input]) => {
+            if (input) {
+                const isEnabled = this.#elementAvailability[key] !== false;
+                const isVisible = this.#elementVisibility[key] !== false;
+                input.disabled = !isEnabled;
+                this.#elements.sliderWrappers[key]?.toggleAttribute("data-disabled", !isEnabled);
+                this.#elements.sliderWrappers[key]?.toggleAttribute("data-hidden", !isVisible);
             }
-            wrapper.toggleAttribute("data-pending", pendingKeys.includes(key));
         });
-        this.#elements.lightingSliderWrapper?.toggleAttribute("data-pending", pendingKeys.includes("lightingTimeOfDay"));
-    }
-
-    /**
-     * Shows a transient status message in the footer and schedules it to auto-clear.
-     * @private
-     * @param {string} message - The status text to display.
-     * @returns {void}
-     */
-    #setStatusMessage(message) {
-        if (!this.#elements.status) {
-            return;
-        }
-        this.#elements.status.textContent = message;
-        if (message) {
-            this.setAttribute("data-status", "visible");
-        } else {
-            this.removeAttribute("data-status");
-        }
-        if (this.#statusTimeout) {
-            clearTimeout(this.#statusTimeout);
-            this.#statusTimeout = null;
-        }
-        if (message) {
-            const schedule = typeof window !== "undefined" ? window.setTimeout : setTimeout;
-            this.#statusTimeout = schedule(() => {
-                this.#elements.status.textContent = "";
-                this.removeAttribute("data-status");
-                this.#statusTimeout = null;
-            }, 4000);
-        }
     }
 
     /**
@@ -801,24 +715,14 @@ export default class PrefViewerMenu3D extends HTMLElement {
      */
 
     /**
-     * Locks or unlocks the menu while changes are applied and updates the footer status text.
+     * Locks or unlocks the menu while changes are applied.
      * @public
      * @param {boolean} isApplying - Whether an apply operation is currently running.
-     * @param {boolean} [hasError=false] - Optional flag to show an error message.
      * @returns {void}
      */
-    setApplying(isApplying, hasError = false) {
+    setApplying(isApplying) {
         this.#isApplying = isApplying;
         this.toggleAttribute("data-applying", isApplying);
-        if (this.#elements.applyButton) {
-            this.#elements.applyButton.textContent = isApplying ? this.#texts.actions.applying : this.#texts.actions.apply;
-            this.#elements.applyButton.disabled = isApplying || !this.#hasPendingChanges();
-        }
-        if (hasError) {
-            this.#setStatusMessage(this.#texts.status.error);
-        } else if (!isApplying) {
-            this.#setStatusMessage("");
-        }
     }
     
     /**
@@ -852,32 +756,23 @@ export default class PrefViewerMenu3D extends HTMLElement {
     }
 
     /**
-     * Applies a new set of render settings to the UI, resetting draft state and pending markers.
+     * Applies a new render settings snapshot to the UI and clears the applying state.
      * @public
-     * @param {object} settings - Render settings snapshot from PrefViewer.
+     * @param {object} settings - Render settings snapshot from PrefViewer or BabylonJSController.
      * @returns {void}
      */
     setSettings(settings = {}) {
-        this.#appliedSettings = { ...this.#DEFAULT_RENDER_SETTINGS, ...settings };
-        this.#draftSettings = { ...this.#appliedSettings };
+        this.#settings = { ...this.#DEFAULT_RENDER_SETTINGS, ...settings };
         this.#updateSwitches();
-        this.#updatePendingState();
-        
-        // Sync color slider with current highlightColor
-        if (this.#draftSettings.highlightColor) {
-            this.#updateColorPickerUI(this.#draftSettings.highlightColor);
-        }
-        if (this.#draftSettings.lightingTimeOfDay !== undefined) {
-            this.#updateLightingSliderUI(this.#draftSettings.lightingTimeOfDay);
+        if (this.#settings.highlightColor) {
+            this.#updateColorPickerUI(this.#settings.highlightColor);
         }
-        // Update illumination color picker if present
-        if (this.#draftSettings.illuminationColor) {
-            this.#updateColorPickerUI(this.#draftSettings.illuminationColor);
+        if (this.#settings.lightingTimeOfDay !== undefined) {
+            this.#updateLightingSliderUI(this.#settings.lightingTimeOfDay);
         }
+        this.#updateSliders();
         this.#updateLightingPlayButtonUI();
-        
         this.setApplying(false);
-        this.#setStatusMessage("");
     }
     
     /**
@@ -899,22 +794,44 @@ export default class PrefViewerMenu3D extends HTMLElement {
     }
 
     /**
-     * Enables or disables a specific render-setting switch in the menu.
+     * Enables or disables a specific render-setting switch or slider in the menu.
      * @public
-     * @param {string} settingKey - Switch key (e.g. "iblEnabled").
+     * @param {string} settingKey - Setting key (e.g. "iblEnabled", "highlightColor", or "lightingTimeOfDay").
      * @param {boolean} [isEnabled=true] - True to allow interaction, false to disable it.
      * @returns {void}
      */
-    setSwitchEnabled(settingKey, isEnabled = true) {
-        if (!settingKey || !this.#MENU_SWITCHES.includes(settingKey)) {
+    setElementEnabled(settingKey, isEnabled = true) {
+        if (!settingKey) {
             return;
         }
-        const enabled = Boolean(isEnabled);
-        this.#switchAvailability[settingKey] = enabled;
-        if (!enabled) {
-            this.#draftSettings[settingKey] = this.#appliedSettings[settingKey];
+
+        if (this.#MENU_SWITCHES.includes(settingKey)) {
+            this.#elementAvailability[settingKey] = Boolean(isEnabled);
+            this.#updateSwitches();
+        } else if (this.#elements.sliders[settingKey]) {
+            this.#elementAvailability[settingKey] = Boolean(isEnabled);
+            this.#updateSliders();
+        }
+    }
+
+    /**
+     * Shows or hides a specific render-setting switch or slider in the menu.
+     * @public
+     * @param {string} settingKey - Setting key (e.g. "iblEnabled", "highlightColor", or "lightingTimeOfDay").
+     * @param {boolean} [isVisible=true] - True to show the switch, false to hide it.
+     * @returns {void}
+     */
+    setElementVisible(settingKey, isVisible = true) {
+        if (!settingKey) {
+            return;
+        }
+
+        if (this.#MENU_SWITCHES.includes(settingKey)) {
+            this.#elementVisibility[settingKey] = Boolean(isVisible);
+            this.#updateSwitches();
+        } else if (this.#elements.sliders[settingKey]) {
+            this.#elementVisibility[settingKey] = Boolean(isVisible);
+            this.#updateSliders();
         }
-        this.#updateSwitches();
-        this.#updatePendingState();
     }
 }