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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "2.16.0-beta.8",
+    "version": "2.16.0",
     "description": "Web Component to preview GLTF models with Babylon.js",
     "author": "Alex Moreno Palacio <amoreno@preference.es>",
     "scripts": {
@@ -35,11 +35,11 @@
         "index.d.ts"
     ],
     "dependencies": {
-        "@babylonjs/core": "9.3.3",
-        "@babylonjs/loaders": "9.3.3",
-        "@babylonjs/serializers": "9.3.3",
-        "@panzoom/panzoom": "^4.6.0",
-        "babylonjs-gltf2interface": "9.3.3",
+        "@babylonjs/core": "^9.11.0",
+        "@babylonjs/loaders": "^9.11.0",
+        "@babylonjs/serializers": "^9.11.0",
+        "@panzoom/panzoom": "^4.6.2",
+        "babylonjs-gltf2interface": "^9.11.0",
         "buffer": "^6.0.3",
         "idb": "^8.0.3",
         "is-svg": "^6.1.0",

package/src/babylonjs-controller.js

@@ -10,74 +10,13 @@ import { MaterialData } from "./pref-viewer-3d-data.js";
 import BabylonJSAnimationController from "./babylonjs-animation-controller.js";
 import OpeningAnimation from "./babylonjs-animation-opening.js";
 import { translate } from "./localization/i18n.js";
+import { PrefViewerStyleVariables } from "./styles.js";
+import { clamp01, lerp, getAdaptiveHardwareScalingLevel, getLightingCycleProfile } from "./render-math.js";
+import { markPrefViewerSimplifiedTransmissionMaterial, isPrefViewerPhysicalGlassMaterial, isPrefViewerTransparentRenderOrderMaterial } from "./material-utils.js";
 
-export function getAdaptiveHardwareScalingLevel(baseScaling = 1, pixelRatio = 1) {
-    const safeBaseScaling = Number.isFinite(baseScaling) && baseScaling > 0 ? baseScaling : 1;
-    const safePixelRatio = Number.isFinite(pixelRatio) && pixelRatio > 0 ? pixelRatio : 1;
-    return safeBaseScaling / safePixelRatio;
-}
-
-function clamp01(value) {
-    if (!Number.isFinite(value)) {
-        return 0.5;
-    }
-    return Math.min(1, Math.max(0, value));
-}
-
-function lerp(from, to, amount) {
-    const t = clamp01(amount);
-    return from + (to - from) * t;
-}
-
-function smoothstep(edge0, edge1, x) {
-    if (edge0 === edge1) {
-        return x >= edge1 ? 1 : 0;
-    }
-    const t = clamp01((x - edge0) / (edge1 - edge0));
-    return t * t * (3 - 2 * t);
-}
-
-function bellCurve(x) {
-    const clamped = clamp01(x);
-    return Math.sin(clamped * Math.PI);
-}
-
-function normalizeDirection(x, y, z) {
-    const length = Math.hypot(x, y, z) || 1;
-    return {
-        x: x / length,
-        y: y / length,
-        z: z / length,
-    };
-}
-
-export function getLightingCycleProfile(timeOfDay = 0.5) {
-    const normalizedTime = clamp01(timeOfDay);
-    const timeHours = normalizedTime * 24;
-    const sunriseHour = 6.25;
-    const sunsetHour = 20.25;
-    const daylightProgress = clamp01((timeHours - sunriseHour) / (sunsetHour - sunriseHour));
-    const dayFactor = timeHours >= sunriseHour && timeHours <= sunsetHour ? Math.pow(bellCurve(daylightProgress), 0.88) : 0;
-    const nightFactor = 1 - dayFactor;
-    const solarArc = dayFactor > 0 ? Math.pow(dayFactor, 0.72) : 0;
-    const solarAzimuth = lerp(-Math.PI * 0.82, Math.PI * 0.82, daylightProgress);
-    const solarElevation = lerp(-0.18, 1.18, solarArc);
-    const sunPhase = normalizedTime * Math.PI * 2 - Math.PI / 2;
-    const sunDirection = normalizeDirection(-Math.cos(sunPhase), -Math.sin(sunPhase), -0.35);
-    const moonDirection = normalizeDirection(-sunDirection.x, -sunDirection.y, -sunDirection.z);
-
-    return {
-        timeOfDay: normalizedTime,
-        timeHours,
-        sunPhase,
-        solarAzimuth,
-        solarElevation,
-        dayFactor,
-        nightFactor,
-        sunDirection,
-        moonDirection,
-    };
-}
+// Re-export so existing consumers (tests, other modules) can keep importing from this file.
+export { getAdaptiveHardwareScalingLevel, getLightingCycleProfile } from "./render-math.js";
+export { markPrefViewerSimplifiedTransmissionMaterial, isPrefViewerPhysicalGlassMaterial, isPrefViewerTransparentRenderOrderMaterial } from "./material-utils.js";
 
 /**
  * BabylonJSController coordinates the PrefViewer 3D runtime: it bootstraps Babylon.js, manages asset containers,
@@ -100,9 +39,10 @@ export function getLightingCycleProfile(timeOfDay = 0.5) {
  *
  * Runtime Flow
  *  1. Instantiate with `new BabylonJSController(canvas, containers, options)`.
- *  2. Call `enable()` to configure Draco, spin up the engine/scene, attach interaction + XR hooks, and start the render loop.
+ *  2. Call `enable()` to configure Draco, spin up the engine/scene, and attach interaction + XR hooks. The render loop
+ *     does not start here; it starts automatically after the first `load()` completes.
  *  3. When PrefViewer marks containers/options pending, invoke `load()` (or `reloadWithCurrentSettings()`) so the controller
- *     fetches sources, rebuilds containers, and reattaches pipelines.
+ *     fetches sources, rebuilds containers, reattaches pipelines, and starts the render loop.
  *  4. Use `scheduleRenderSettingsReload()` to merge/persist toggles; when it reports `changed: true`, call
  *     `reloadWithCurrentSettings()` to apply the staged settings.
  *  5. Use `setContainerVisibility`, `setMaterialOptions`, `setCameraOptions`, or `setIBLOptions` for targeted updates; these
@@ -119,10 +59,13 @@ export function getLightingCycleProfile(timeOfDay = 0.5) {
  *  - getRenderSettings() / scheduleRenderSettingsReload(settings)
  *  - setContainerVisibility(name, show)
  *  - setMaterialOptions() / setCameraOptions() / setIBLOptions()
+ *  - setIlluminationConfig(config)
+ *  - getAnimations() / playAnimation(name, action) / setAnimationProgress(name, progress) / setAnimationLoop(name, loop)
  *
  * Key Invariants
- *  - Asset containers must expose `setPendingWithCurrentStorage`/`setPending` before calling load/reload; the controller
- *    reads those flags to resolve fresh sources and avoids touching the DOM until data is ready.
+ *  - Asset containers must expose `setPendingWithCurrentStorage` before calling load/reload; the controller reads that
+ *    flag to resolve fresh sources. Option objects (camera, materials, IBL) expose `setPendingWithCurrent` for the same
+ *    purpose. Neither set of flags touches the DOM — they only gate resolver calls.
  *  - Camera-dependent pipelines (DefaultRenderingPipeline, SSAO, IBL shadows, directional shadow generators) are rebuilt
  *    only after the active camera and environment textures are ready; render-loop restarts gate those transitions.
  *  - `show-model`/`show-scene` DOM attributes reflect container visibility; there are no direct `showModel()/hideModel()` APIs.
@@ -156,7 +99,7 @@ export default class BabylonJSController {
         lightingTimeOfDay: 0.5,
         // Highlight settings
         highlightEnabled: true,
-        highlightColor: "#ff6700",
+        highlightColor: PrefViewerStyleVariables.colorPrimary,
     };
 
     // Canvas HTML element
@@ -178,7 +121,7 @@ export default class BabylonJSController {
     #XRExperience = null;
     #canvasResizeObserver = null;
     
-    #hdrTexture = null; // reusable in-memory HDR source cloned into scene.environmentTexture across reloads
+    #hdrTexture = null; // Reusable in-memory HDR source cloned into scene.environmentTexture across reloads
 
     #containers = {};
     #options = {};
@@ -231,30 +174,30 @@ export default class BabylonJSController {
     // Runtime configuration constants (tuning knobs, not per-frame state).
     #config = {
         pointerPicking: {
-            movePickIntervalMs: 50, // cap expensive scene.pick calls to ~20 Hz while moving the pointer
-            movePickMinDistancePx: 2, // skip picks for sub-pixel jitter
+            movePickIntervalMs: 50, // Cap expensive scene.pick calls to ~20 Hz while moving the pointer
+            movePickMinDistancePx: 2, // Skip picks for sub-pixel jitter
         },
         render: {
             burstFramesBase: 2,
-            burstFramesEnhanced: 32, // when AA/SSAO/IBL is enabled, more frames are needed to reach stable output
+            burstFramesEnhanced: 32, // When AA/SSAO/IBL is enabled, more frames are needed to reach stable output
             interactionMs: 250,
             animationMs: 200,
             idleThrottleMs: 1000 / 8, // Reduced from 15 FPS to 8 FPS for idle - reduces GPU/CPU load
             idleThresholdMs: 3000, // Time before going to true idle (no renders)
         },
         resize: {
-            throttleMs: 50, // cap resize work to ~20 Hz while dragging/resizing containers
+            throttleMs: 50, // Cap resize work to ~20 Hz while dragging/resizing containers
         },
         // Hardware-adaptive quality settings (applied based on GPU capabilities)
         quality: {
             // Settings for different hardware tiers: 'low', 'medium', 'high'
             // Applied automatically based on GPU detected capabilities
-            tier: 'medium', // default, will be updated after hardware detection
-            shadowMapSize: 1024,        // Standard shadow generator resolution
-            iblShadowResolution: 1,     // IBL shadow resolution exponent (0=1024, 1=2048, 2=4096)
-            iblSampleDirections: 4,     // IBL shadow quality
-            shadowBlurKernel: 16,       // Shadow blur amount
-            ssaoEnabled: true,         // Screen Space Ambient Occlusion
+            tier: 'medium',          // Default, will be updated after hardware detection
+            shadowMapSize: 1024,     // Standard shadow generator resolution
+            iblShadowResolution: 1,  // IBL shadow resolution exponent (0=1024, 1=2048, 2=4096)
+            iblSampleDirections: 4,  // IBL shadow quality
+            shadowBlurKernel: 16,    // Shadow blur amount
+            ssaoEnabled: true,       // Screen Space Ambient Occlusion
         },
         look: {
             showroom: {
@@ -378,23 +321,23 @@ export default class BabylonJSController {
         // High-end mobile patterns (recent flagship devices)
         const highEndPatterns = [
             /iPhone (1[4-9]|SE)/i,        // iPhone 14+
-            /iPad Pro/i,                   // iPad Pro
-            /SM-S91[0-9]/i,              // Samsung S21+
-            /SM-S9[0-9]/i,               // Samsung S20+
-            /Pixel [7-9]/i,              // Pixel 7+
-            /OnePlus [8-9|10|11]/i,      // OnePlus 8+
+            /iPad Pro/i,                  // iPad Pro
+            /SM-S91[0-9]/i,               // Samsung S21+
+            /SM-S9[0-9]/i,                // Samsung S20+
+            /Pixel [7-9]/i,               // Pixel 7+
+            /OnePlus [8-9|10|11]/i,       // OnePlus 8+
             /Xiaomi (1[2-4]|Mi 1[1-4])/i, // Xiaomi 12+
-            /Huawei (P50|Mate 4|)/i,     // Huawei P50+
+            /Huawei (P50|Mate 4|)/i,      // Huawei P50+
         ];
         
         // Mid-range patterns
         const midRangePatterns = [
-            /iPhone (1[0-3]|SE)/i,       // iPhone 10-13
+            /iPhone (1[0-3]|SE)/i,        // iPhone 10-13
             /iPad Air/i,                  // iPad Air
-            /SM-A[0-9]/i,                // Samsung A series
-            /Redmi Note/i,               // Redmi Note
-            /Pixel [4-6]/i,              // Pixel 4-6
-            /Moto G/i,                   // Moto G
+            /SM-A[0-9]/i,                 // Samsung A series
+            /Redmi Note/i,                // Redmi Note
+            /Pixel [4-6]/i,               // Pixel 4-6
+            /Moto G/i,                    // Moto G
         ];
         
         const isHighEnd = highEndPatterns.some(p => p.test(userAgent));
@@ -446,13 +389,13 @@ export default class BabylonJSController {
             // Mobile low-end (old phones, budget devices)
             low: {
                 shadowMapSize: 256,              // Very small for speed
-                iblShadowResolution: -1,        // Disable IBL shadows
+                iblShadowResolution: -1,         // Disable IBL shadows
                 iblSampleDirections: 1,          // Minimal sampling
                 shadowBlurKernel: 0,             // No blur
                 ssaoEnabled: false,
                 antialiasingEnabled: false,
-                hardwareScaling: 2.5,           // Aggressive downscaling
-                maxModelResolution: 512,          // Low-res model loading
+                hardwareScaling: 2.5,            // Aggressive downscaling
+                maxModelResolution: 512,         // Low-res model loading
                 environmentTextureSize: 512,
             },
             // Mobile high-end / Tablet / Desktop low
@@ -470,7 +413,7 @@ export default class BabylonJSController {
             // Desktop mid-range / High-end mobile
             high: {
                 shadowMapSize: 1024,
-                iblShadowResolution: 0,          // 1024x1024 - good balance
+                iblShadowResolution: 0,           // 1024x1024 - good balance
                 iblSampleDirections: 4,           // Quality sampling
                 shadowBlurKernel: 8,              // Sharper shadows for product clarity
                 ssaoEnabled: false,
@@ -482,9 +425,9 @@ export default class BabylonJSController {
             // Desktop high-end (RTX, Apple Silicon, etc.)
             ultra: {
                 shadowMapSize: 2048,
-                iblShadowResolution: 1,          // 2048x2048
+                iblShadowResolution: 1,           // 2048x2048
                 iblSampleDirections: 8,           // Maximum quality
-                shadowBlurKernel: 16,            // Preserve clarity over softness
+                shadowBlurKernel: 16,             // Preserve clarity over softness
                 ssaoEnabled: false,
                 antialiasingEnabled: true,
                 hardwareScaling: 1.0,             // Native resolution
@@ -1627,7 +1570,7 @@ export default class BabylonJSController {
             }
         });
     }
-
+  
     /**
      * Applies the showroom tonemapping curve and lighting bias used by the 3D viewer.
      * @private
@@ -2522,6 +2465,40 @@ export default class BabylonJSController {
         assetContainer.lights = [];
     }
 
+    /**
+     * Strips KHR_materials_transmission, KHR_materials_ior and KHR_materials_volume from
+     * environment-container (scene) materials, converting them to simple alpha blending.
+     * Babylon.js cannot render two physical-transmission materials (from separate GLTF
+     * containers) through each other: the scene decorative glass (lamp cups, etc.) is
+     * simplified so the model's physical glass keeps full correct transmission.
+     * @private
+     * @param {AssetContainer} assetContainer
+     * @returns {void}
+     */
+    #assetContainer_simplifyTransmissiveMaterials(assetContainer) {
+        assetContainer.materials?.forEach((mat) => {
+            if (!(mat instanceof PBRMaterial)) return;
+            if (!mat.subSurface?.isRefractionEnabled && !mat.subSurface?.isTranslucencyEnabled) return;
+            this.#simplifyTransmissiveMaterial(mat);
+        });
+    }
+
+    /**
+     * Converts a single PBRMaterial from physical KHR_materials_transmission to simple alpha
+     * blending. Shared helper used by both the at-load simplification and the post-swap pass.
+     * @private
+     * @param {PBRMaterial} mat
+     * @returns {void}
+     */
+    #simplifyTransmissiveMaterial(mat) {
+        const intensity = mat.subSurface.refractionIntensity ?? 1.0;
+        mat.subSurface.isRefractionEnabled = false;
+        mat.subSurface.isTranslucencyEnabled = false;
+        mat.alpha = Math.max(0.28, 1.0 - intensity * 0.65);
+        mat.transparencyMode = PBRMaterial.PBRMATERIAL_ALPHABLEND;
+        markPrefViewerSimplifiedTransmissionMaterial(mat);
+    }
+
     /**
      * Assigns unique ids to every imported camera so Babylon.js does not reuse stale SSAO effects between reloads.
      * @private
@@ -2695,6 +2672,9 @@ export default class BabylonJSController {
                         if (container.state.name === "model" || container.state.name === "environment") {
                             this.#assetContainer_retagCameras(assetContainer);
                         }
+                        if (container.state.name === "environment") {
+                            this.#assetContainer_simplifyTransmissiveMaterials(assetContainer);
+                        }
                         this.#replaceContainer(container, assetContainer);
                         container.state.setSuccess(true);
                     } else {
@@ -3384,4 +3364,4 @@ export default class BabylonJSController {
             this.#requestRender({ frames: 2 });
         }
     }
-}
+}

package/src/localization/translations.js

@@ -3,18 +3,12 @@ export const translations = {
         prefViewer: {
             menu3d: {
                 title: "3D render settings",
-                subtitle: "Toggle visual effects on or off.",
-                pendingLabel: "Pending changes",
+                subtitle: "Modify the visual effects.",
                 actions: {
-                    apply: "Apply",
-                    applying: "Applying...",
                     play: "Play",
                     pause: "Pause",
                 },
-                status: {
-                    error: "Couldn't apply the changes.",
-                },
-                switches: {
+                features: {
                     antiAliasingEnabled: {
                         label: "Antialiasing",
                         helper: "Softens jagged edges and lines.",
@@ -70,18 +64,12 @@ export const translations = {
         prefViewer: {
             menu3d: {
                 title: "Ajustes de render 3D",
-                subtitle: "Activa o desactiva los efectos visuales.",
-                pendingLabel: "Pendiente de aplicar",
+                subtitle: "Modifica los efectos visuales.",
                 actions: {
-                    apply: "Aplicar",
-                    applying: "Aplicando...",
                     play: "Reproducir",
                     pause: "Pausar",
                 },
-                status: {
-                    error: "No se pudo aplicar los cambios.",
-                },
-                switches: {
+                features: {
                     antiAliasingEnabled: {
                         label: "Antialiasing",
                         helper: "Suaviza aristas y líneas.",
@@ -100,7 +88,7 @@ export const translations = {
                     },
                     highlightEnabled: {
                         label: "Resaltado",
-                        helper: "Resaltar elementos animados al pasar el ratón.",
+                        helper: "Resalta elementos animados al pasar el ratón.",
                     },
                     highlightColor: {
                         label: "Color de resaltado",

package/src/material-utils.js

@@ -0,0 +1,72 @@
+import { PBRMaterial } from "@babylonjs/core";
+
+/**
+ * Utilities for classifying and tagging PBR materials by their transparency/transmission mode.
+ * Used by BabylonJSController at load time and by pref-viewer-3d for render-order decisions.
+ */
+
+const PREF_VIEWER_SIMPLIFIED_TRANSMISSION_METADATA_KEY = "prefViewerSimplifiedTransmission";
+
+/**
+ * Tags a PBR material as having been converted from physical KHR_materials_transmission to simple
+ * alpha blending. The tag is stored in `mat.metadata` under an internal key so that downstream
+ * render-order passes can still identify these materials as transparent candidates even after
+ * their `subSurface.isRefractionEnabled` flag has been cleared.
+ *
+ * Returns the same material instance (or the original value when `mat` is falsy) so calls can be
+ * chained.
+ * @param {import("@babylonjs/core").PBRMaterial|null|undefined} mat - Material to tag.
+ * @returns {import("@babylonjs/core").PBRMaterial|null|undefined} The same `mat` value that was passed in.
+ */
+export function markPrefViewerSimplifiedTransmissionMaterial(mat) {
+    if (!mat) {
+        return mat;
+    }
+            
+    mat.metadata = {
+        ...(mat.metadata ?? {}),
+        [PREF_VIEWER_SIMPLIFIED_TRANSMISSION_METADATA_KEY]: true,
+    };
+    return mat;
+}
+
+/**
+ * Returns true when the material uses Babylon.js physical glass rendering — i.e. either
+ * KHR_materials_transmission (refraction) or KHR_materials_translucency is active.
+ *
+ * This is intentionally narrower than `isPrefViewerTransparentRenderOrderMaterial`: it only
+ * matches full physical transmission, not plain alpha blending or simplified environment glass.
+ * @param {import("@babylonjs/core").Material|null|undefined} mat - Material to test.
+ * @returns {boolean}
+ */
+export function isPrefViewerPhysicalGlassMaterial(mat) {
+    return Boolean(mat?.subSurface?.isRefractionEnabled || mat?.subSurface?.isTranslucencyEnabled);
+}
+
+/**
+ * Returns true when a material should be placed in the transparent rendering group (renderingGroupId=1).
+ *
+ * A material qualifies when any of the following is true:
+ * - It is a physical glass material (KHR_materials_transmission / translucency).
+ * - It has been tagged as simplified environment transmission via `markPrefViewerSimplifiedTransmissionMaterial`.
+ * - Its effective alpha is below 1, its `transparencyMode` is alpha-blend or alpha-test-and-blend,
+ *   or it self-reports as needing blending/testing through the Babylon.js material API.
+ * @param {import("@babylonjs/core").Material|null|undefined} mat - Material to test.
+ * @returns {boolean}
+ */
+export function isPrefViewerTransparentRenderOrderMaterial(mat) {
+    if (!mat) {
+        return false;
+    }
+    const isTransmissive = isPrefViewerPhysicalGlassMaterial(mat);
+    const isSimplifiedTransmission = mat.metadata?.[PREF_VIEWER_SIMPLIFIED_TRANSMISSION_METADATA_KEY] === true;
+    const alpha = typeof mat.alpha === "number" ? mat.alpha : 1;
+    const isAlphaBlended =
+        alpha < 1 ||
+        mat.transparencyMode === PBRMaterial.PBRMATERIAL_ALPHABLEND ||
+        mat.transparencyMode === PBRMaterial.PBRMATERIAL_ALPHATESTANDBLEND ||
+        mat.needAlphaBlending?.() === true ||
+        mat.needAlphaTesting?.() === true;
+
+    return Boolean(isTransmissive || isSimplifiedTransmission || isAlphaBlended);
+}

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

@@ -10,28 +10,32 @@ import FileStorage from "./file-storage.js";
  *  - Encapsulates a Babylon.js-powered 3D viewer for displaying models, environments, and materials.
  *  - Manages internal state for containers (model, environment, materials) and options (camera, materials, IBL, render toggles).
  *  - Handles asset loading, configuration, and option updates (camera, materials, IBL) through attributes and public methods.
- *  - Exposes getters/setters for render settings so PrefViewerMenu3D or other UIs can persistently toggle AA/SSAO/IBL/shadows.
+ *  - Exposes getters/setters for render settings so PrefViewerMenu3D or other UIs can toggle AA/SSAO/IBL/shadows,
+ *    hover highlight, and time-of-day lighting.
  *  - Provides API for showing/hiding the viewer, model, and environment, and for downloading assets.
  *  - Emits custom events for loading, loaded, option-setting, and render-setting workflows.
  *
  * Usage:
  *  - Use as a custom HTML element: <pref-viewer-3d ...>
  *  - Configure via attributes (config, options, show-model, show-scene, visible).
- *  - Call getRenderSettings()/applyRenderSettings() to synchronize UI toggles with BabylonJSController persistence.
+ *  - Call getRenderSettings()/applyRenderSettings() to synchronize UI controls with BabylonJSController settings.
  *  - Control viewer state and assets via public methods.
  *
  * Observed Attributes:
  *  - show-model: Show or hide the 3D model ("true"/"false").
  *  - show-scene: Show or hide the 3D environment ("true"/"false").
  *  - visible: Show or hide the entire viewer ("true"/"false").
+ *  - show-animation-menu: Show or hide animation controls in the 3D controller.
+ *  - highlight-color: Hex color used for hover highlight on animated meshes.
+ *  - highlight-enabled: Enable or disable hover highlight ("true"/"false").
  *
  * Public Methods:
  *  - show(): Shows the 3D viewer component.
  *  - hide(): Hides the 3D viewer component.
  *  - load(config): Loads the provided configuration into the viewer.
  *  - setOptions(options): Sets viewer options such as camera, materials, and image-based lighting (IBL).
- *  - getRenderSettings(): Returns the current anti-aliasing, SSAO, IBL, and shadow flags.
- *  - applyRenderSettings(settings): Persists incoming render toggles, reloads if needed, and reports the result.
+ *  - getRenderSettings(): Returns the current render settings snapshot, including highlight and lighting values.
+ *  - applyRenderSettings(settings): Applies render settings, reloading only when a setting requires it.
  *  - showModel(): Shows the 3D model.
  *  - hideModel(): Hides the 3D model.
  *  - showEnvironment(): Shows the 3D environment/scene.
@@ -110,6 +114,7 @@ export default class PrefViewer3D extends HTMLElement {
      * - "show-model": shows or hides the model according to the attribute value ("true"/"false").
      * - "show-scene": shows or hides the scene according to the attribute value ("true"/"false").
      * - "visible": shows or hides the component according to the attribute value ("true"/"false").
+     * - "show-animation-menu", "highlight-color", and "highlight-enabled": forward runtime UI/highlight settings to BabylonJSController.
      */
     attributeChangedCallback(name, _old, value) {
         switch (name) {
@@ -874,8 +879,9 @@ export default class PrefViewer3D extends HTMLElement {
 
     /**
      * Returns the current render settings used by the BabylonJSController.
+     * The snapshot is suitable for hydrating PrefViewerMenu3D controls.
      * @public
-     * @returns {object|null} A shallow copy of the render settings or null if unavailable.
+     * @returns {object|null} A shallow copy of the render settings, including quality toggles, highlight state, and lighting time, or null if unavailable.
      */
     getRenderSettings() {
         if (!this.#babylonJSController) {
@@ -944,10 +950,20 @@ export default class PrefViewer3D extends HTMLElement {
     }
 
     /**
-     * Applies render settings that require reloading the Babylon.js scene.
+     * Applies render settings received from PrefViewerMenu3D or another UI.
+     * Highlight and time-of-day lighting values are pushed directly to BabylonJSController; AA/SSAO/IBL/shadow changes
+     * are scheduled through the render-settings reload path when needed.
      * @public
-     * @param {object} settings - Partial settings for anti-aliasing, SSAO, IBL, and shadows.
-     * @returns {Promise<object>} Resolves with the reload summary.
+     * @param {object} settings - Partial render settings payload.
+     * @param {boolean} [settings.antiAliasingEnabled] - Enables or disables anti-aliasing.
+     * @param {boolean} [settings.ambientOcclusionEnabled] - Enables or disables SSAO.
+     * @param {boolean} [settings.iblEnabled] - Enables or disables image-based lighting.
+     * @param {boolean} [settings.shadowsEnabled] - Enables or disables scene shadows.
+     * @param {boolean|string} [settings.highlightEnabled] - Enables or disables hover highlight; string "false" is normalized to false.
+     * @param {string} [settings.highlightColor] - Hex color used for hover highlight.
+     * @param {number} [settings.lightingTimeOfDay] - Normalized 0..1 time-of-day value.
+     * @param {boolean} [settings.persist=true] - False for transient lighting updates such as playback frames.
+     * @returns {Promise<{changed: boolean, success: boolean, detail?: object, controller?: object}>} Resolves with the apply/reload summary.
      */
     async applyRenderSettings(settings) {
         if (!this.#babylonJSController) {