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

package/src/pref-viewer.js

@@ -66,7 +66,6 @@ export default class PrefViewer extends HTMLElement {
     #cultureList = SUPPORTED_LOCALES;
     #culture = "";
     #cultureSuppressAttribute = false;
-    #suppressVisibilityAttributeCallback = false;
 
     // References to internal components
     #wrapper = null;
@@ -121,9 +120,6 @@ export default class PrefViewer extends HTMLElement {
      * @returns {void}
      */
     attributeChangedCallback(name, _old, value) {
-        if (this.#suppressVisibilityAttributeCallback && (name === "show-model" || name === "show-scene")) {
-            return;
-        }
         switch (name) {
             case "config":
                 this.loadConfig(value);
@@ -480,10 +476,10 @@ export default class PrefViewer extends HTMLElement {
     }
 
     /**
-     * Applies render toggles via PrefViewer3D, showing progress in the menu and resyncing on completion.
-     * When no changes occur, the menu is simply refreshed to match the controller snapshot.
+     * Applies render settings via PrefViewer3D.
+     * Reload-capable toggles lock the menu while they run; partial highlight/lighting updates are forwarded immediately.
      * @private
-     * @param {object} settings - Partial render settings (AA, SSAO, IBL, shadows) requested by the menu.
+     * @param {object} settings - Partial render settings requested by the menu.
      * @returns {Promise<void>}
      */
     async #applyRenderSettings(settings) {
@@ -631,47 +627,20 @@ export default class PrefViewer extends HTMLElement {
     /**
      * Handles the completion of a 3D loading operation.
      * Updates loading state, sets attributes, dispatches a "scene-loaded" event, and processes the next task.
-     * Dispatches granular container events ("model-loaded", "environment-loaded", "materials-loaded")
-     * for each successfully loaded container before firing "scene-loaded".
-     * The independent model path may additionally emit "model-first-painted" when the first painted
-     * frame is acknowledged by the Babylon controller.
      * @private
      * @param {object} [detail] - Optional details to include in the event.
-     * @param {string[]} [detail.loadedContainers] - Names of containers that loaded successfully.
      * @returns {void}
      */
     #on3DLoaded(detail) {
         this.#isLoaded = true;
         this.#isLoading = false;
-
+        
         this.#menu3DSyncSettings();
         this.#menu3DUpdateSwitchAvailability();
 
         this.removeAttribute("loading-3d");
         this.setAttribute("loaded-3d", "");
 
-        // Dispatch granular container events before the aggregate "scene-loaded".
-        // This lets consumers react as soon as individual assets are ready without
-        // waiting for the full scene-loaded signal.
-        const granularEventMap = {
-            model: "model-loaded",
-            environment: "environment-loaded",
-            materials: "materials-loaded",
-        };
-        if (Array.isArray(detail?.loadedContainers)) {
-            const granularEventOptions = {
-                bubbles: true,
-                cancelable: false,
-                composed: true,
-            };
-            detail.loadedContainers.forEach((containerName) => {
-                const eventName = granularEventMap[containerName];
-                if (eventName) {
-                    this.dispatchEvent(new CustomEvent(eventName, granularEventOptions));
-                }
-            });
-        }
-
         const customEventOptions = {
             bubbles: true,
             cancelable: true,
@@ -1152,78 +1121,6 @@ export default class PrefViewer extends HTMLElement {
         this.#addTaskToQueue(model, "model");
     }
 
-    /**
-     * Loads the model container in parallel with any ongoing scene load, bypassing the task queue.
-     * Dispatches "model-loading", "model-first-painted", and "model-loaded" events directly.
-     * @public
-     * @param {object|string} model - Model payload with storage pointer.
-     * @returns {Promise<void>}
-     */
-    async loadModelParallel(model) {
-        model = typeof model === "string" ? JSON.parse(model) : model;
-        if (!model || !this.#component3D) return;
-        const eventOptions = { bubbles: true, cancelable: false, composed: true };
-        this.dispatchEvent(new CustomEvent("model-loading", eventOptions));
-        try {
-            const detail = await this.#component3D.loadModelIndependent(model);
-            if (detail?.success) {
-                this.dispatchEvent(new CustomEvent("model-loaded", { ...eventOptions, detail }));
-            } else {
-                this.dispatchEvent(new CustomEvent("model-error", { ...eventOptions, detail }));
-            }
-        } catch (error) {
-            this.dispatchEvent(new CustomEvent("model-error", { ...eventOptions, detail: { error } }));
-        }
-    }
-
-    /**
-     * Loads the environment/scene container in parallel with any ongoing model load, bypassing the
-     * task queue. Dispatches "scene-loading" and "scene-loaded" (or "scene-error") events directly.
-     * @public
-     * @param {object|string} scene - Scene payload: { storage, ibl?, visible? }
-     * @returns {Promise<void>}
-     */
-    async loadSceneParallel(scene) {
-        scene = typeof scene === "string" ? JSON.parse(scene) : scene;
-        if (!scene || !this.#component3D) return;
-        const eventOptions = { bubbles: true, cancelable: false, composed: true };
-        this.dispatchEvent(new CustomEvent("scene-loading", eventOptions));
-        try {
-            const detail = await this.#component3D.loadSceneIndependent(scene);
-            if (detail?.success) {
-                this.dispatchEvent(new CustomEvent("scene-loaded", { ...eventOptions, detail }));
-            } else {
-                this.dispatchEvent(new CustomEvent("scene-error", { ...eventOptions, detail }));
-            }
-        } catch (error) {
-            this.dispatchEvent(new CustomEvent("scene-error", { ...eventOptions, detail: { error } }));
-        }
-    }
-
-    /**
-     * Loads the materials container in parallel with any ongoing model or environment load,
-     * bypassing the task queue. Dispatches "materials-loading" and "materials-loaded" events.
-     * @public
-     * @param {object|string} materials - Materials payload: { storage }
-     * @returns {Promise<void>}
-     */
-    async loadMaterialsParallel(materials) {
-        materials = typeof materials === "string" ? JSON.parse(materials) : materials;
-        if (!materials || !this.#component3D) return;
-        const eventOptions = { bubbles: true, cancelable: false, composed: true };
-        this.dispatchEvent(new CustomEvent("materials-loading", eventOptions));
-        try {
-            const detail = await this.#component3D.loadMaterialsIndependent(materials);
-            if (detail?.success) {
-                this.dispatchEvent(new CustomEvent("materials-loaded", { ...eventOptions, detail }));
-            } else {
-                this.dispatchEvent(new CustomEvent("materials-error", { ...eventOptions, detail }));
-            }
-        } catch (error) {
-            this.dispatchEvent(new CustomEvent("materials-error", { ...eventOptions, detail: { error } }));
-        }
-    }
-
     /**
      * Loads a scene/environment object or JSON string and adds it to the task queue.
      * @public
@@ -1368,31 +1265,6 @@ export default class PrefViewer extends HTMLElement {
         this.#addTaskToQueue(config, "visibility");
     }
 
-    /**
-     * Reflects the current visibility of a container without feeding the task queue.
-     * Used by the Babylon controller to keep host attributes in sync with renderer state.
-     * @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;
-        }
-    }
-
     /**
      * Centers the 2D drawing view in the viewer.
      * @public
@@ -1647,22 +1519,4 @@ export default class PrefViewer extends HTMLElement {
     get isMode3D() {
         return this.#mode === "3d";
     }
-
-    /**
-     * Forces the 3D camera to frame the current model, when supported.
-     * @public
-     * @returns {boolean}
-     */
-    focusModel() {
-        return this.#component3D?.focusModel?.() ?? false;
-    }
-
-    /**
-     * Exposes a debug snapshot of the 3D runtime when available.
-     * @public
-     * @returns {object|null}
-     */
-    getDebugState() {
-        return this.#component3D?.getDebugState?.() ?? null;
-    }
 }

package/src/render-math.js

@@ -0,0 +1,127 @@
+/**
+ * Pure math utilities used by the lighting cycle and hardware scaling logic.
+ * No Babylon.js imports — safe to use in Node/SSR environments and in tests without mocks.
+ */
+
+/**
+ * Clamps a number to the [0, 1] range.
+ * Returns 0.5 for non-finite inputs (NaN, ±Infinity) so callers get a safe mid-point fallback.
+ * @param {number} value - The value to clamp.
+ * @returns {number} A number in [0, 1].
+ */
+export function clamp01(value) {
+    if (!Number.isFinite(value)) {
+        return 0.5;
+    }
+    return Math.min(1, Math.max(0, value));
+}
+
+/**
+ * Linearly interpolates between two values.
+ * The interpolation amount is clamped to [0, 1] before use.
+ * @param {number} from - Start value (returned when amount ≤ 0).
+ * @param {number} to - End value (returned when amount ≥ 1).
+ * @param {number} amount - Blend factor in [0, 1].
+ * @returns {number} Interpolated value between `from` and `to`.
+ */
+export function lerp(from, to, amount) {
+    const t = clamp01(amount);
+    return from + (to - from) * t;
+}
+
+/**
+ * Evaluates a bell-curve (half sine arc) over [0, 1].
+ * Returns 0 at both endpoints and 1 at the midpoint (x = 0.5).
+ * Used to model the intensity rise and fall of sunlight across the day.
+ * @param {number} x - Input in [0, 1]; clamped internally.
+ * @returns {number} Bell-curve output in [0, 1].
+ */
+function bellCurve(x) {
+    const clamped = clamp01(x);
+    return Math.sin(clamped * Math.PI);
+}
+
+/**
+ * Returns a unit vector for the given (x, y, z) direction.
+ * Falls back to the original vector with length 1 when the input is the zero vector.
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {{x: number, y: number, z: number}} Normalized direction vector.
+ */
+function normalizeDirection(x, y, z) {
+    const length = Math.hypot(x, y, z) || 1;
+    return {
+        x: x / length,
+        y: y / length,
+        z: z / length,
+    };
+}
+
+/**
+ * Computes the Babylon.js `hardwareScalingLevel` needed to render at the requested base
+ * resolution on a HiDPI display.
+ *
+ * Babylon's hardware scaling is the inverse of the device pixel ratio: a level of 0.5 on a
+ * 2× display renders at native resolution. This helper applies the base scaling factor (which
+ * may already downscale for performance on low-end hardware) on top of the device pixel ratio.
+ *
+ * Both inputs are validated and fall back to 1 when zero, negative, or non-finite.
+ * @param {number} [baseScaling=1] - Desired base scaling level (1 = full resolution, >1 = downscaled).
+ * @param {number} [pixelRatio=1] - Device pixel ratio (`window.devicePixelRatio`).
+ * @returns {number} Hardware scaling level to pass to `engine.setHardwareScalingLevel()`.
+ */
+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;
+}
+
+/**
+ * Computes a lighting profile for a given time of day, used to drive the scene's directional
+ * lights, environment intensity, and tonemapping curve.
+ *
+ * The model follows a simplified solar arc: sunrise at 06:15 and sunset at 20:15 (fractional
+ * hours). Day factor peaks at solar noon and falls to zero outside daylight hours. Sun and moon
+ * directions are antipodal unit vectors derived from the sun phase angle.
+ * @param {number} [timeOfDay=0.5] - Normalized time in [0, 1] where 0 = midnight and 1 = next midnight.
+ *   Values outside [0, 1] are clamped.
+ * @returns {{
+ *   timeOfDay: number,
+ *   timeHours: number,
+ *   sunPhase: number,
+ *   solarAzimuth: number,
+ *   solarElevation: number,
+ *   dayFactor: number,
+ *   nightFactor: number,
+ *   sunDirection: {x: number, y: number, z: number},
+ *   moonDirection: {x: number, y: number, z: number}
+ * }} Lighting profile snapshot for the requested time.
+ */
+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,
+    };
+}