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

package/src/file-storage.js

@@ -129,10 +129,6 @@ export default class FileStorage {
     #minimumFreeSpaceRatio = 0.05; // try to keep at least 5% of quota free
     #maxQuotaEvictionRetries = 5; // max retries after quota error
     #lastCleanupAt = 0; // timestamp of last automatic cleanup run
-    // In-memory blob cache — eliminates repeated IDB round-trips for the same URI within a session.
-    // Keyed by URI; values are normalized records (blob kept in RAM). Avoids both the readonly read
-    // and the readwrite #touchFile transaction on every getURL() call during #replaceSceneURIAsync.
-    #memoryCache = new Map();
 
     constructor(dbName = "FilesDB", osName = "FilesObjectStore") {
         this.dbName = dbName; // database name
@@ -262,7 +258,6 @@ export default class FileStorage {
         const store = transaction.objectStore(this.osName);
         keys.forEach((key) => {
             store.delete(key);
-            this.#memoryCache.delete(String(key));
         });
         await transaction.done;
         return keys.length;
@@ -613,7 +608,6 @@ export default class FileStorage {
                 const store = transaction.objectStore(this.osName);
                 const result = await store.put(record, uri);
                 await transaction.done;
-                this.#memoryCache.set(uri, record);
                 return result;
             } catch (error) {
                 if (!this.#isQuotaExceededError(error) || attempt === this.#maxQuotaEvictionRetries) {
@@ -641,19 +635,6 @@ export default class FileStorage {
      *   - false: if the database could not be opened (IndexedDB unsupported or open failure)
      */
     async #getFile(uri, { touch = true, allowExpired = false } = {}) {
-        // In-memory cache hit: skip IDB entirely, update lastAccess in RAM only.
-        const inMemory = this.#memoryCache.get(uri);
-        if (inMemory) {
-            if (!allowExpired && this.#isExpired(inMemory)) {
-                this.#memoryCache.delete(uri);
-            } else {
-                if (touch) {
-                    inMemory.lastAccess = this.#now();
-                }
-                return inMemory;
-            }
-        }
-
         if (this.#db === undefined) {
             this.#db = await this.#openDB();
         }
@@ -670,68 +651,13 @@ export default class FileStorage {
             await this.#deleteKeys([uri]);
             return undefined;
         }
-        this.#memoryCache.set(uri, record);
         if (touch) {
-            // Fire-and-forget: don't block the caller on a readwrite IDB transaction just to update lastAccess.
-            void this.#touchFile(uri, record);
+            await this.#touchFile(uri, record);
             record.lastAccess = this.#now();
         }
         return record;
     }
 
-    /**
-     * Retrieves multiple file records from the in-memory cache and IDB in a single readonly
-     * transaction, populating the in-memory cache for all hits.
-     * @private
-     * @param {string[]} uris - URIs to look up.
-     * @returns {Promise<Map<string, object>>} Map of uri → normalized record for found entries.
-     */
-    async #getFileBatch(uris) {
-        const resultMap = new Map();
-        if (!uris.length) return resultMap;
-
-        const idbMisses = [];
-        for (const uri of uris) {
-            const cached = this.#memoryCache.get(uri);
-            if (cached) {
-                if (this.#isExpired(cached)) {
-                    this.#memoryCache.delete(uri);
-                    idbMisses.push(uri);
-                } else {
-                    resultMap.set(uri, cached);
-                }
-            } else {
-                idbMisses.push(uri);
-            }
-        }
-
-        if (!idbMisses.length) return resultMap;
-
-        if (this.#db === undefined) {
-            this.#db = await this.#openDB();
-        }
-        if (this.#db === null) return resultMap;
-
-        // One readonly transaction for all IDB misses — single lock acquisition vs N transactions.
-        const tx = this.#db.transaction(this.osName, "readonly");
-        const store = tx.objectStore(this.osName);
-        const rawRecords = await Promise.all(idbMisses.map((uri) => store.get(uri)));
-
-        const now = this.#now();
-        idbMisses.forEach((uri, i) => {
-            const record = this.#normalizeRecord(rawRecords[i]);
-            if (!record) return;
-            if (this.#isExpired(record, now)) {
-                void this.#deleteKeys([uri]);
-                return;
-            }
-            this.#memoryCache.set(uri, record);
-            resultMap.set(uri, record);
-        });
-
-        return resultMap;
-    }
-
     /**
      * ---------------------------
      * Public methods
@@ -756,44 +682,6 @@ export default class FileStorage {
         return storedFile ? URL.createObjectURL(storedFile.blob) : (await this.#getServerFileTimeStamp(uri)) ? uri : false;
     }
 
-    /**
-     * Resolve multiple URIs to object URLs in a single IDB batch transaction.
-     * Hits in-memory cache first, then IDB in one transaction, then falls back to individual
-     * server downloads for any URIs not found. Returns a Map<uri, objectURL|uri>.
-     * @public
-     * @param {string[]} uris - URIs to resolve.
-     * @returns {Promise<Map<string, string>>} Map of uri → resolved URL (blob: or original URI).
-     */
-    async getURLBatch(uris) {
-        if (!uris.length) return new Map();
-        if (!this.#supported) {
-            return new Map(uris.map((uri) => [uri, uri]));
-        }
-        await this.#runCleanupIfDue();
-        const records = await this.#getFileBatch(uris);
-        const urlMap = new Map();
-        const serverFetches = [];
-
-        for (const uri of uris) {
-            const record = records.get(uri);
-            if (record?.blob) {
-                urlMap.set(uri, URL.createObjectURL(record.blob));
-            } else {
-                serverFetches.push(uri);
-            }
-        }
-
-        // For URIs absent from IDB, fall back to individual get() which downloads and caches them.
-        await Promise.all(
-            serverFetches.map(async (uri) => {
-                const url = await this.getURL(uri);
-                if (url) urlMap.set(uri, url);
-            })
-        );
-
-        return urlMap;
-    }
-
     /**
      * Get the cached or server Last-Modified timestamp for a file.
      * @public
@@ -874,18 +762,10 @@ export default class FileStorage {
         }
         if (!storedFile) {
             const fileToStore = await this.#getServerFile(uri);
-            if (fileToStore) {
-                // Populate in-memory cache immediately after download so subsequent calls
-                // within this session are instant — even if the IDB write fails later.
-                const freshRecord = this.#createRecordFromFile(fileToStore);
-                if (freshRecord) {
-                    this.#memoryCache.set(uri, freshRecord);
-                }
-                if (!!(await this.#putFile(fileToStore, uri))) {
-                    storedFile = await this.#getFile(uri);
-                } else {
-                    storedFile = freshRecord ?? fileToStore;
-                }
+            if (fileToStore && !!(await this.#putFile(fileToStore, uri))) {
+                storedFile = await this.#getFile(uri);
+            } else {
+                storedFile = fileToStore;
             }
         }
         return storedFile;
@@ -921,6 +801,5 @@ export default class FileStorage {
             } catch {}
         }
         this.#db = undefined;
-        this.#memoryCache.clear();
     }
 }

package/src/gltf-resolver.js

@@ -82,27 +82,27 @@ export default class GLTFResolver {
      *   - If parsing fails, returns a Blob with MIME type "model/gltf-binary" and extension ".glb".
      *   - If decoding fails, returns nulls for blob and extension.
      */
-    async #decodeBase64(base64) {
+    #decodeBase64(base64) {
         const [, payload] = base64.split(",");
         const raw = payload || base64;
-        const size = raw.length;
-
-        // Detect format from first base64 chars — O(1), no full decode needed.
-        // GLB magic bytes 0x676c5446 ("glTF") encode to "Z2x" in base64.
-        // GLTF JSON always starts with '{' (0x7B), which encodes to "ey" in base64.
-        const isGlb = raw.startsWith("Z2x");
-        const extension = isGlb ? ".glb" : ".gltf";
-        const type = isGlb ? "model/gltf-binary" : "model/gltf+json";
-
+        let decoded = "";
         let blob = null;
+        let extension = null;
+        let size = raw.length;
         try {
-            // Native browser decode: runs in C++ off the JS call stack, does not block the
-            // main thread. Avoids the per-character Uint8Array loop and the full JSON.parse
-            // that the previous sync implementation used to detect the file type.
-            blob = await fetch(`data:${type};base64,${raw}`).then((r) => r.blob());
+            decoded = atob(raw);
         } catch {
-            return { blob: null, extension: null, size };
+            return { blob, extension, size };
         }
+        let isJson = false;
+        try {
+            JSON.parse(decoded);
+            isJson = true;
+        } catch {}
+        extension = isJson ? ".gltf" : ".glb";
+        const type = isJson ? "model/gltf+json" : "model/gltf-binary";
+        const array = Uint8Array.from(decoded, (c) => c.charCodeAt(0));
+        blob = new Blob([array], { type });
         return { blob, extension, size };
     }
 
@@ -138,27 +138,6 @@ export default class GLTFResolver {
         return typeof url === "string" && url.startsWith("blob:");
     }
 
-    /**
-     * Check whether a source should be treated as embedded base64/data URI.
-     * @private
-     * @param {string} source - Value to test.
-     * @returns {boolean} True when the source is a data URI or raw base64 payload.
-     */
-    #isEmbeddedBase64Source(source) {
-        if (typeof source !== "string") {
-            return false;
-        }
-        const normalized = source.trim();
-        if (!normalized) {
-            return false;
-        }
-        if (normalized.startsWith("data:")) {
-            return true;
-        }
-        // Raw base64 payloads use the standard alphabet and have no URL separators.
-        return /^[A-Za-z0-9+/=_-]+$/.test(normalized);
-    }
-
     /**
      * Collects asset entries that have an external URI (non-data URI) and stores a normalized absolute or relative-resolved URI for later replacement.
      * @private
@@ -225,19 +204,17 @@ export default class GLTFResolver {
             assetContainerJSON.images.forEach((asset, index, array) => this.#saveAssetData(asset, index, array, sceneURLBase, arrayOfAssetsWithURI));
         }
 
-        // Batch-resolve all asset URIs in a single IDB transaction to avoid per-URI transaction
-        // overhead. Falls back to individual getURL() for URIs not found in IDB.
-        const urisToResolve = arrayOfAssetsWithURI.map((asset) => asset.uri);
-        const urlMap = await this.#fileStorage.getURLBatch(urisToResolve);
-        arrayOfAssetsWithURI.forEach((asset) => {
-            const resolvedUrl = urlMap.get(asset.uri);
-            if (resolvedUrl) {
-                asset.parent[asset.index].uri = resolvedUrl;
-                if (this.#isBlobURL(resolvedUrl)) {
-                    objectURLs.push(resolvedUrl);
+        // Replace parallel URIs so that if files are not stored yet, they are downloaded in parallel
+        const promisesArray = arrayOfAssetsWithURI.map(async (asset) => {
+            const uri = await this.#fileStorage.getURL(asset.uri);
+            if (uri) {
+                asset.parent[asset.index].uri = uri;
+                if (this.#isBlobURL(uri)) {
+                    objectURLs.push(uri);
                 }
             }
         });
+        await Promise.all(promisesArray);
     }
 
     /**
@@ -293,9 +270,7 @@ export default class GLTFResolver {
 
         if (storage.db && storage.table && storage.id) {
             await this.#initializeStorage(storage.db, storage.table);
-            const tIdb = performance.now();
             const object = await loadModel(storage.id, storage.table);
-            console.log(`[perf][gltf:${storage.id}] IDB read ${Math.round(performance.now() - tIdb)}ms`);
             if (!object || !object.data || !object.timeStamp || !object.size) {
                 return false;
             }
@@ -315,21 +290,12 @@ export default class GLTFResolver {
         }
 
         let file = null;
-        let blob = null;
-        let extension = null;
-        let size = 0;
-        if (this.#isEmbeddedBase64Source(source)) {
-            const tDecode = performance.now();
-            ({ blob, extension, size } = await this.#decodeBase64(source));
-            console.log(`[perf][gltf:${storage.id ?? "url"}] decode(${extension}) ${Math.round(performance.now() - tDecode)}ms`);
-        }
+        let { blob, extension, size } = this.#decodeBase64(source);
 
         if (blob && extension) {
             if (extension === ".gltf") {
                 const assetContainerJSON = JSON.parse(await blob.text());
-                const tReplace = performance.now();
                 await this.#replaceSceneURIAsync(assetContainerJSON, source, objectURLs);
-                console.log(`[perf][gltf:${storage.id ?? "url"}] replaceURIs ${Math.round(performance.now() - tReplace)}ms (${objectURLs.length} assets)`);
                 source = `data:${JSON.stringify(assetContainerJSON)}`;
             } else {
                 file = new File([blob], `file${extension}`, {

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.
@@ -62,7 +66,6 @@ import FileStorage from "./file-storage.js";
  * Events:
  *  - "scene-loading": Dispatched when a loading operation starts.
  *  - "scene-loaded": Dispatched when a loading operation completes.
- *  - "model-first-painted": Dispatched when the model-only preview has actually painted a frame.
  *  - "scene-setting-options": Dispatched when viewer options are being set.
  *  - "scene-set-options": Dispatched when viewer options have been set.
  *
@@ -77,7 +80,6 @@ export default class PrefViewer3D extends HTMLElement {
     #isLoaded = false;
     #isVisible = false;
     #lastLoadTimestamp = undefined;
-    #suppressVisibilityAttributeCallback = false;
 
     #wrapper = null;
     #canvas = null;
@@ -112,11 +114,9 @@ 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) {
-        if (this.#suppressVisibilityAttributeCallback && (name === "show-model" || name === "show-scene")) {
-            return;
-        }
         switch (name) {
             case "show-model":
                 if (_old === value) {
@@ -721,62 +721,6 @@ export default class PrefViewer3D extends HTMLElement {
         return { success: someSetted, detail: detail };
     }
 
-    /**
-     * Loads the model container independently in the background while the render loop keeps running.
-     * Merges the model into the scene atomically when ready, without stopping camera-dependent effects.
-     * @public
-     * @param {object} payload - Model payload with storage pointer and optional timestamp.
-     * @returns {Promise<{success: boolean, error: any, loadedContainers: string[]}>}
-     */
-    async loadModelIndependent(payload) {
-        if (!this.#babylonJSController) {
-            return { success: false, error: "Controller not initialized", loadedContainers: [] };
-        }
-        // #checkNeedToUpdateContainers passed as callback — called AFTER any in-progress #loadContainers
-        // finishes so the scene load doesn't also pick up and consume the model container.
-        return await this.#babylonJSController.loadContainerIndependent("model", () => {
-            this.#checkNeedToUpdateContainers({ model: payload });
-        }, { loadSessionId: payload?.loadSessionId ?? null });
-    }
-
-    /**
-     * Loads the environment/scene container independently in the background, in parallel with any
-     * ongoing model load. Applies IBL (HDR) if the scene payload includes an ibl property.
-     * Dispatches "scene-loading" and "scene-loaded" (or "scene-error") events directly.
-     * @public
-     * @param {object|string} scene - Scene payload: { storage, ibl?, visible? }
-     * @returns {Promise<{success: boolean, error: any, loadedContainers: string[]}>}
-     */
-    async loadSceneIndependent(scene) {
-        if (!this.#babylonJSController) {
-            return { success: false, error: "Controller not initialized", loadedContainers: [] };
-        }
-        // Pre-mark IBL as pending before entering loadContainerIndependent — the onReady callback
-        // is synchronous so async IBL resolution must happen here, not inside it.
-        if (scene?.ibl !== undefined) {
-            await this.#checkNeedToUpdateIBL({ ibl: scene.ibl });
-        }
-        return await this.#babylonJSController.loadContainerIndependent("environment", () => {
-            this.#checkNeedToUpdateContainers({ scene });
-        });
-    }
-
-    /**
-     * Loads the materials container independently in the background, in parallel with any
-     * ongoing model or environment load.
-     * @public
-     * @param {object|string} materials - Materials payload: { storage }
-     * @returns {Promise<{success: boolean, error: any, loadedContainers: string[]}>}
-     */
-    async loadMaterialsIndependent(materials) {
-        if (!this.#babylonJSController) {
-            return { success: false, error: "Controller not initialized", loadedContainers: [] };
-        }
-        return await this.#babylonJSController.loadContainerIndependent("materials", () => {
-            this.#checkNeedToUpdateContainers({ materials });
-        });
-    }
-
     /**
      * Shows the 3D model within the viewer.
      * @public
@@ -825,31 +769,6 @@ export default class PrefViewer3D extends HTMLElement {
         this.#babylonJSController.setContainerVisibility("environment", false);
     }
 
-    /**
-     * Reflects the current visibility of a container without re-triggering the command queue.
-     * Used by BabylonJSController when the visibility change originated from the renderer itself.
-     * @public
-     * @param {string} name - Container name ("model" or "environment").
-     * @param {boolean} isVisible - Whether the container should be reflected as visible.
-     * @returns {void}
-     */
-    syncVisibility(name, isVisible) {
-        const attrName = name === "model" ? "show-model" : name === "environment" ? "show-scene" : null;
-        if (!attrName) {
-            return;
-        }
-        const nextValue = isVisible ? "true" : "false";
-        if (this.getAttribute(attrName) === nextValue) {
-            return;
-        }
-        this.#suppressVisibilityAttributeCallback = true;
-        try {
-            this.setAttribute(attrName, nextValue);
-        } finally {
-            this.#suppressVisibilityAttributeCallback = false;
-        }
-    }
-
     /**
      * Downloads the current 3D model as a GLB file.
      * @public
@@ -960,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) {
@@ -1030,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) {
@@ -1101,22 +1031,4 @@ export default class PrefViewer3D extends HTMLElement {
     get isVisible() {
         return this.#isVisible;
     }
-
-    /**
-     * Forces the active camera to frame the visible model.
-     * @public
-     * @returns {boolean}
-     */
-    focusModel() {
-        return this.#babylonJSController?.focusModel?.() ?? false;
-    }
-
-    /**
-     * Returns a debug snapshot of the internal 3D state, including camera data.
-     * @public
-     * @returns {object|null}
-     */
-    getDebugState() {
-        return this.#babylonJSController?.getDebugState?.() ?? null;
-    }
 }