@preference-sl/pref-viewer 2.16.2 → 2.17.0-beta.1

package/src/render-math.js

@@ -1,127 +1,140 @@
 /**
- * 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.
+ * Pure lighting and hardware-scaling calculations without Babylon.js dependencies.
+ * @class RenderMath
  */
-
-/**
- * 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;
+export default class RenderMath {
+    /**
+     * 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.
+     * @public
+     * @static
+     * @param {number} value - The value to clamp.
+     * @returns {number} A number in [0, 1].
+     */
+    static clamp01(value) {
+        if (!Number.isFinite(value)) {
+            return 0.5;
+        }
+        return Math.min(1, Math.max(0, value));
     }
-    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;
-}
+    /**
+     * Linearly interpolates between two values.
+     * The interpolation amount is clamped to [0, 1] before use.
+     * @public
+     * @static
+     * @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`.
+     */
+    static lerp(from, to, amount) {
+        const t = RenderMath.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);
-}
+    /**
+     * 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.
+     * @private
+     * @static
+     * @param {number} x - Input in [0, 1]; clamped internally.
+     * @returns {number} Bell-curve output in [0, 1].
+     */
+    static #bellCurve(x) {
+        const clamped = RenderMath.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,
-    };
-}
+    /**
+     * Returns a unit vector for the given (x, y, z) direction.
+     * Leaves the zero vector unchanged by using a divisor of 1 when its length is zero.
+     * @private
+     * @static
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {{x: number, y: number, z: number}} Normalized direction vector.
+     */
+    static #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 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.
+     * @public
+     * @static
+     * @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()`.
+     */
+    static 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);
+    /**
+     * 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.
+     * @public
+     * @static
+     * @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.
+     */
+    static getLightingCycleProfile(timeOfDay = 0.5) {
+        const normalizedTime = RenderMath.clamp01(timeOfDay);
+        const timeHours = normalizedTime * 24;
+        const sunriseHour = 6.25;
+        const sunsetHour = 20.25;
+        const daylightProgress = RenderMath.clamp01((timeHours - sunriseHour) / (sunsetHour - sunriseHour));
+        const dayFactor = timeHours >= sunriseHour && timeHours <= sunsetHour ? Math.pow(RenderMath.#bellCurve(daylightProgress), 0.88) : 0;
+        const nightFactor = 1 - dayFactor;
+        const solarArc = dayFactor > 0 ? Math.pow(dayFactor, 0.72) : 0;
+        const solarAzimuth = RenderMath.lerp(-Math.PI * 0.82, Math.PI * 0.82, daylightProgress);
+        const solarElevation = RenderMath.lerp(-0.18, 1.18, solarArc);
+        const sunPhase = normalizedTime * Math.PI * 2 - Math.PI / 2;
+        const sunDirection = RenderMath.#normalizeDirection(-Math.cos(sunPhase), -Math.sin(sunPhase), -0.35);
+        const moonDirection = RenderMath.#normalizeDirection(-sunDirection.x, -sunDirection.y, -sunDirection.z);
 
-    return {
-        timeOfDay: normalizedTime,
-        timeHours,
-        sunPhase,
-        solarAzimuth,
-        solarElevation,
-        dayFactor,
-        nightFactor,
-        sunDirection,
-        moonDirection,
-    };
+        return {
+            timeOfDay: normalizedTime,
+            timeHours,
+            sunPhase,
+            solarAzimuth,
+            solarElevation,
+            dayFactor,
+            nightFactor,
+            sunDirection,
+            moonDirection,
+        };
+    }
 }

package/src/styles.js

@@ -150,6 +150,94 @@ export const PrefViewer3DStyles = `
     }
 `;
 
+export const PrefViewerViewCubeStyles = `
+    .pref-viewer-view-cube {
+        --cube-fill-color: #eef0f3;
+        --cube-border-color: #78838f;
+        --cube-border-width: 1.0px;
+        --cube-hover-color: var(--pref-viewer-color-primary, ${PrefViewerStyleVariables.colorPrimary});
+        --cube-hover-opacity: 0.50;
+        --cube-active-color: var(--pref-viewer-color-primary, ${PrefViewerStyleVariables.colorPrimary});
+        --cube-active-opacity: 0.15;
+        --cube-text-font-family: ${PrefViewerStyleVariables.fontFamily};
+        --cube-text-font-size: 9px;
+        --cube-text-color: #29323b;
+        --cube-text-font-weight: 600;
+        --cube-text-letter-spacing: 1.0px;
+    }
+
+    .pref-viewer-view-cube[hidden] {
+        display: none;
+    }
+
+    .pref-viewer-view-cube svg {
+        width: 100%;
+        height: 100%;
+        overflow: visible;
+        pointer-events: none;
+    }
+
+    .pref-viewer-view-cube polygon {
+        stroke-width: var(--cube-border-width);
+    }
+
+    .pref-viewer-view-cube .cube-shell {
+        fill: var(--cube-fill-color);
+        stroke: var(--cube-border-color);
+        pointer-events: none;
+    }
+
+    .pref-viewer-view-cube polygon[data-region] {
+        fill: transparent;
+        stroke: transparent;
+        pointer-events: visiblePainted;
+        cursor: pointer;
+    }
+
+    .pref-viewer-view-cube[data-locked="true"] polygon {
+        cursor: default;
+    }
+
+    .pref-viewer-view-cube polygon[data-current] {
+        fill: var(--cube-active-color);
+        fill-opacity: var(--cube-active-opacity);
+        stroke: transparent;
+    }
+
+    .pref-viewer-view-cube polygon[data-hover] {
+        fill: var(--cube-hover-color);
+        fill-opacity: var(--cube-hover-opacity);
+        stroke: transparent;
+    }
+
+    .pref-viewer-view-cube .hover-outline {
+        display: none;
+        fill: none;
+        stroke: var(--cube-hover-color);
+        stroke-opacity: 1;
+        stroke-width: var(--cube-border-width);
+        pointer-events: none;
+    }
+
+    .pref-viewer-view-cube .hover-outline[data-hover] {
+        display: inline;
+    }
+
+    .pref-viewer-view-cube text {
+        -webkit-user-select: none;
+        user-select: none;
+        pointer-events: none;
+        fill: var(--cube-text-color);
+        font-family: var(--cube-text-font-family);
+        font-size: var(--cube-text-font-size);
+        font-weight: var(--cube-text-font-weight);
+        letter-spacing: var(--cube-text-letter-spacing);
+        text-transform: uppercase;
+        text-anchor: middle;
+        dominant-baseline: middle;
+    }
+`;
+
 export const PrefViewerMenu3DStyles = `
     pref-viewer-menu-3d {
         --font-family: ${PrefViewerStyleVariables.fontFamily};
@@ -203,7 +291,7 @@ export const PrefViewerMenu3DStyles = `
         --slider-bar-border: 1px solid rgba(255, 255, 255, 0.5);
 
         position: absolute;
-        top: var(--toggle-margin);
+        top: var(--pref-viewer-render-menu-top, var(--toggle-margin));
         right: var(--toggle-margin);
         z-index: 1200;
         /* The closed panel keeps its place in the flex column (opacity:0, not display:none), so
@@ -214,6 +302,8 @@ export const PrefViewerMenu3DStyles = `
         pointer-events: none;
 
         font-family: var(--font-family);
+        -webkit-user-select: none;
+        user-select: none;
     }
 
     pref-viewer-menu-3d>.menu-wrapper {
@@ -256,7 +346,7 @@ export const PrefViewerMenu3DStyles = `
 
     pref-viewer-menu-3d>.menu-wrapper>.menu-panel {
         width: var(--panel-width);
-        max-height: 70vh;
+        max-height: min(70vh, calc(var(--pref-viewer-viewport-height, 100vh) - var(--pref-viewer-render-menu-top, var(--toggle-margin)) - 84px));
         overflow-y: auto;
         border-radius: var(--panel-radius);
         background: var(--panel-bg-color);
@@ -820,7 +910,8 @@ export const PrefViewerDialogStyles = `
         justify-content: center;
         background-color: var(--dialog-backdrop-color);
         position: relative;
-        z-index: 1000;
+        /* Cover all viewer overlays, including the 3D render menu (1200). */
+        z-index: 1300;
     }
 
     pref-viewer-dialog>.dialog-wrapper {

package/src/svg-resolver.js

@@ -15,7 +15,7 @@ import { initDb, loadModel } from "./gltf-storage.js";
  *  - Provides a unified API for consumers to obtain SVG content and metadata.
  *
  * Usage:
- *  - Instantiate with an initial SVG state object (required).
+ *  - Instantiate with an optional initial SVG state object.
  *      Example: const resolver = new SVGResolver({ value: "", size: 0, timeStamp: null, update: true });
  *  - Call getSVG(svgConfig) to resolve and update the SVG state.
  *      Example: await resolver.getSVG({ storage: { url: "data:image/svg+xml;base64,..." } });
@@ -78,7 +78,7 @@ export default class SVGResolver {
      * Parse an input that may be a plain SVG string or a data URI (possibly base64).
      * @private
      * @param {string} source - Data URI or raw string to decode/check.
-     * @returns {{value: string|null, size: number}} value when detected/decoded, and size (length of the text string).
+     * @returns {[string|null, number]} Decoded SVG text or null, followed by the source size used for cache comparison.
      */
     #parseSource(source) {
         let value = null;
@@ -210,14 +210,15 @@ export default class SVGResolver {
     /**
      * Resolve and prepare an SVG from multiple storage forms.
      * @public
-     * @param {object|string} svgConfig - Configuration object. Expected shape for storage:
+     * @param {object} svgConfig - Configuration object. Expected shape for storage:
      *   { storage: { url: "<url>" } } // remote URL or data URI (base64 or plain)
      *   { storage: { db: "<db>", table: "<table>", id: "<id>" } } // IndexedDB record
      * @param {object} [svg] - Optional external SVG state object to seed/update. If provided, the resolver
      *   updates this object in-place: { value: string, size: number, timeStamp: string|null, update: boolean }.
      * @returns {Promise<false|{value:string,size:number,timeStamp:string|null,update:boolean}>}
-     *   - Resolves to false when no update is required or on error.
+     *   - Resolves to false when no update is required or the source cannot be decoded/fetched.
      *   - Resolves to the internal SVG state object when an update was prepared.
+     * @throws {Error} Rejects on IndexedDB failures or an absent record in the requested database.
      * @description
      *  - Accepts SVG (base64 or plain string) from IndexedDB (storage.db/table/id), from a data URI (base64 or plain string) (storage.url),
      *    from a remote URL (storage.url) or from direct SVG string (storage.url).