@preference-sl/pref-viewer 2.16.0-beta.8 → 2.16.0

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-menu-3d-apply` 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.
+ *  - `setSwitchEnabled(settingKey, isEnabled)`: enables/disables a specific toggle 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`, `show-illumination`, `illumination-color`, `lighting-time-of-day`.
+ * The illumination attributes are mirrored for compatibility with hosts that still set them declaratively.
  *
- * Accessibility:
- *  - Uses ARIA labels/live regions for the toggle button, dialog panel, pending indicator, and status slot.
+ * Events emitted: `pref-viewer-menu-3d-apply` - `{ detail: { settings: object } }`.
  */
 export default class PrefViewerMenu3D extends HTMLElement {
     #elements = {
-        applyButton: null,
         colorPicker: null,
         colorSlider: null,
         colorPickerPreview: null,
@@ -43,8 +41,6 @@ export default class PrefViewerMenu3D extends HTMLElement {
         lightingSlider: null,
         lightingValue: null,
         panel: null,
-        pendingLabel: null,
-        status: null,
         subtitle: null,
         switches: {},
         switchCopyNodes: {},
@@ -54,7 +50,6 @@ export default class PrefViewerMenu3D extends HTMLElement {
     };
 
     #handles = {
-        onApplyClick: null,
         onColorSliderInput: null,
         onLightingSliderInput: null,
         onLightingPlayClick: null,
@@ -65,25 +60,28 @@ 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 };
+    #settings = { ...this.#DEFAULT_RENDER_SETTINGS };
     #switchAvailability = {};
-    #statusTimeout = null;
     #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();
     }
@@ -98,35 +96,30 @@ export default class PrefViewerMenu3D extends HTMLElement {
     }
     
     /**
-     * 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"|"show-illumination"|"illumination-color"|"lighting-time-of-day"} 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 === "show-illumination") {
+            this.#settings.illuminationEnabled = value === "true" || value === true;
+            const switchEl = this.#elements.switches?.illuminationEnabled;
+            if (switchEl) {
+                switchEl.checked = this.#settings.illuminationEnabled;
             }
+        } else if (name === "illumination-color") {
+            this.#settings.illuminationColor = value;
+            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);
+                this.#settings.lightingTimeOfDay = this.#clampLightingTime(parsed);
+                this.#updateLightingSliderUI(this.#settings.lightingTimeOfDay);
             }
         }
     }
@@ -143,27 +136,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 +169,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="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" 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="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">${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" 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 +202,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 +229,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 +239,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 +271,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 +316,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,10 +325,6 @@ 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
         this.#elements.colorPicker = this.querySelector(".menu-color-picker");
         this.#elements.colorSlider = this.querySelector(".color-slider");
@@ -380,7 +350,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 +367,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 +376,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 +395,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 +422,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 +435,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 +467,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 +491,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 +500,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 +510,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 +521,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 +531,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 +550,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 +566,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 +584,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 +598,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 +612,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,28 +656,28 @@ 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 } };
+        this.dispatchEvent(new CustomEvent("pref-viewer-menu-3d-apply", {
             bubbles: true,
             cancelable: true,
             composed: true,
-            detail: detail,
-        };
-        this.dispatchEvent(new CustomEvent("pref-viewer-menu-3d-apply", customEventOptions));
+            detail,
+        }));
     }
 
     /**
-     * Synchronizes checkbox states with the draft settings snapshot.
+     * Synchronizes checkbox states with the current settings snapshot.
      * @private
      * @returns {void}
      */
@@ -698,102 +685,13 @@ export default class PrefViewerMenu3D extends HTMLElement {
         Object.entries(this.#elements.switches).forEach(([key, input]) => {
             if (input) {
                 const isEnabled = this.#switchAvailability[key] !== false;
-                input.checked = Boolean(this.#draftSettings[key]);
+                input.checked = Boolean(this.#settings[key]);
                 input.disabled = !isEnabled;
                 this.#elements.switchWrappers[key]?.toggleAttribute("data-disabled", !isEnabled);
             }
         });
     }
 
-    /**
-     * Toggles pending labels, apply button state, and per-switch markers based on outstanding changes.
-     * @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;
-            }
-            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);
-        }
-    }
-
     /**
      * ---------------------------
      * Public methods
@@ -801,24 +699,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 +740,22 @@ 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.#updateLightingPlayButtonUI();
-        
         this.setApplying(false);
-        this.#setStatusMessage("");
     }
     
     /**
@@ -909,12 +787,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
         if (!settingKey || !this.#MENU_SWITCHES.includes(settingKey)) {
             return;
         }
-        const enabled = Boolean(isEnabled);
-        this.#switchAvailability[settingKey] = enabled;
-        if (!enabled) {
-            this.#draftSettings[settingKey] = this.#appliedSettings[settingKey];
-        }
+        this.#switchAvailability[settingKey] = Boolean(isEnabled);
         this.#updateSwitches();
-        this.#updatePendingState();
     }
 }