@preference-sl/pref-viewer 2.17.0-beta.2 → 2.17.0-beta.4

package/README.md

@@ -88,8 +88,8 @@ viewer.setOptions({
     intensity: 1,
     shadows: true,
   },
-  lighting: {
-    timeOfDay: 0.5,
+  render: {
+    lightingTimeOfDay: 0.5,
   },
 });
 ```
@@ -289,7 +289,9 @@ Increasing the factor makes the fitted model smaller. The other axis can have mo
 
 The default orbital camera starts without `lowerBetaLimit` or `upperBetaLimit` and disables upside-down orbiting, whether or not the cube is enabled. ViewCube navigation keeps the camera up direction on world **+Y**, including top/bottom views and subsequent orbiting. Automatic loading preserves authored camera composition and navigation limits; an explicit unlocked cube action may relax incompatible orbit limits and adjust clipping/radius ranges to reach and fit the selected view. Locked cameras retain their view and limits.
 
-Use the mouse wheel over the 3D canvas to zoom an unlocked orbital camera. Babylon's native input applies a radius-proportional increment once, so the same wheel input moves less at a smaller radius. Input wakes idle rendering. This applies to the default and selected unlocked orbital cameras independently of the cube; existing Free/Universal wheel navigation remains unchanged. The internal orbital wheel sensitivity (`wheelDeltaPercentage`) is 0.015. Wheel sensitivity has no public attribute or config option.
+Use the mouse wheel over the 3D canvas to zoom an unlocked orbital camera. The default camera uses Babylon's native `zoomToMouseLocation`: pointing at an off-center detail shifts the target toward that region as you zoom in, with the ViewCube shown or hidden. Selecting any cube preset, including the current view, cancels pending wheel motion and recenters the target on the visible model's world-bounds center using the existing fit. This does not guarantee an exact surface point stays at the same screen pixel.
+
+Babylon's native input applies a radius-proportional increment once, so the same wheel input moves less at a smaller radius. Input wakes idle rendering, which continues until native wheel inertia settles. Named imported orbital cameras retain their existing input settings, and Free/Universal wheel navigation remains unchanged. The internal orbital wheel sensitivity (`wheelDeltaPercentage`) is 0.015. Wheel sensitivity has no public attribute or config option.
 
 The orbital minimum radius adapts to eligible triangle surfaces in the **current visible model assetContainer only**. Hidden, disabled, non-pickable, disposed or zero-visibility meshes do not contribute. Environment meshes are excluded from both hits and raycast traversal, and model replacement/removal cannot retain an obsolete geometry floor. Clear checked paths allow close inspection without a minimum based on overall model bounds.
 
@@ -499,6 +501,23 @@ Render settings are persisted in `localStorage` under the `pref-viewer/render-se
 
 The showroom daylight background uses a shared linear HDR color calibrated with exposure and ACES tone mapping for the current light studio gray target, `#d9d9d9`, in a scene-less view. Both the static look and time-of-day cycle use this same daylight value; the cycle retains its dark night endpoint. Scene geometry can cover the background. The internal `BabylonJSController.config.look.showroom.backgroundDay` value is not a public background-color option and must be recalibrated if tone mapping or exposure changes.
 
+## Environment map and scene lights
+
+`options.ibl.url` accepts two formats, chosen by the URL's extension (query and hash ignored):
+
+| Extension | Loaded as | Notes |
+| --- | --- | --- |
+| `.env` | Prefiltered Babylon environment (`CubeTexture.CreateFromPrefilteredData`) | No prefiltering in the browser; a 4K environment is typically under 1 MB. |
+| anything else | Radiance HDR (`HDRCubeTexture`) | Prefiltered on load, which costs time and memory for large files. |
+
+Either file is downloaded once, cached in IndexedDB, and reused across reloads.
+
+Directional and spot lights that come with the scene glTF (`KHR_lights_punctual`) cast shadows when `render.shadowsEnabled` is `true` and `ibl.shadows` is off, alongside the built-in light's. Every scene and model mesh casts unless its node sets `extras.castShadows: false`, and receives unless it sets `extras.receiveShadows: false`. A light's shadow darkness comes from its node's `extras.shadowDarkness`, from `0` (black) to `1` (no shadow), and is `0.5` when absent:
+
+```json
+{ "name": "Sun", "rotation": [-0.5, 0, 0, 0.866], "extras": { "shadowDarkness": 0.15 }, "extensions": { "KHR_lights_punctual": { "light": 0 } } }
+```
+
 ## Runtime styles
 
 Runtime styles can be passed through the `styles` attribute, the `styles` property setter, `setStyles(styles)`, or `loadConfig({ styles })`.
@@ -571,6 +590,7 @@ Focused regressions for this work live in `tests/babylonjs-selection-controller.
 - `src/babylonjs-view-cube-controller.js`: dedicated `BabylonJSViewCubeController` for SVG regions, orientation/projection feedback, transitions and cleanup. It delegates model bounds and destination-fit calculations to BabylonJSCameraFraming. Cube-only helpers and constants remain private; region generation remains a public static utility. Its constructor JSDoc documents the host object and callbacks.
 - `src/babylonjs-camera-framing.js`: stateless `BabylonJSCameraFraming` with static `getModelBounds`, `calculateCameraFit` and `isCameraSupported` utilities. Bounds use only visible, enabled geometry in the supplied model container; fit calculations preserve camera state and projection, use the shared camera margin and return a destination for the caller to apply. Default-camera automatic fitting uses these same utilities, preserving the current orientation and applying the destination immediately.
 - `src/babylonjs-camera-zoom-controller.js`: independent `BabylonJSCameraZoomController` for model-only dynamic radius protection and authored-floor restoration. It works without cube resources.
+- `src/babylonjs-camera-wheel-motion.js`: internal boundary for inspecting and cancelling the coupled native wheel inertia during rendering, geometry protection and camera lifecycle changes. Babylon computes the zoom; this boundary isolates version-sensitive native input state.
 - `src/babylonjs-controller.js`: owns the scene, active camera, containers, native wheel settings and render scheduler; coordinates both controllers.
 - `src/styles.js`: exports `PrefViewerViewCubeStyles`, imported by the cube controller. The SVG stylesheet uses multiline CSS and scoped variables for the main visual properties; no JSDoc is required for this styles constant.
 - `src/pref-viewer-3d.js` and `src/pref-viewer.js`: bridge lazy visibility, queued config, localization and measured menu layout. The root stores the layout callback in `#handlers` and removes its listener during teardown. Shared styles place dialogs above viewer overlays.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "2.17.0-beta.2",
+    "version": "2.17.0-beta.4",
     "description": "Web Component to preview GLTF models with Babylon.js",
     "author": "Alex Moreno Palacio <amoreno@preference.es>",
     "scripts": {

package/src/babylonjs-camera-wheel-motion.js

@@ -0,0 +1,54 @@
+/**
+ * Bridges native mouse-location wheel inertia to the viewer's render and navigation lifecycle.
+ * Babylon 9.11 keeps coupled pan/radius inertia on its wheel input, outside the public
+ * camera offsets. Keep that version-sensitive access here; Babylon still computes all zoom.
+ */
+export default class BabylonJSCameraWheelMotion {
+    /**
+     * Returns the active native mouse-location input, without creating or replacing inputs.
+     * @param {object|null|undefined} camera - Camera to inspect.
+     * @returns {object|null} Native input when its mouse-location mode is enabled.
+     */
+    static #input(camera) {
+        const input = camera?.inputs?.attached?.mousewheel;
+        return input?.zoomToMouseLocation ? input : null;
+    }
+
+    /**
+     * Detects the complete native inertia tail, including pan without a public radius offset.
+     * @param {object|null|undefined} camera - Camera to inspect.
+     * @returns {boolean} Whether native wheel motion is pending.
+     */
+    static isMoving(camera) {
+        const input = this.#input(camera);
+        return Boolean(input && (Math.abs(input._zoomToMouseRadiusOffset || 0) > 0 || input._inertialPanning?.lengthSquared() > 0));
+    }
+
+    /**
+     * Stops coupled inward motion when geometry protection clamps the camera.
+     * @param {object|null|undefined} camera - Camera constrained by the geometry guard.
+     * @returns {void}
+     */
+    static stopInward(camera) {
+        if (this.#input(camera)?._zoomToMouseRadiusOffset > 0) {
+            this.cancel(camera);
+        }
+    }
+
+    /**
+     * Cancels native wheel inertia and invalidates its old focal plane without altering orbit/pan inputs.
+     * @param {object|null|undefined} camera - Camera being reframed, deactivated or disposed.
+     * @returns {void}
+     */
+    static cancel(camera) {
+        const input = this.#input(camera);
+        if (!input) {
+            return;
+        }
+        if (typeof input._zoomToMouseRadiusOffset === "number") {
+            input._zoomToMouseRadiusOffset = 0;
+        }
+        input._inertialPanning?.setAll(0);
+        input._hitPlane = null;
+    }
+}

package/src/babylonjs-camera-zoom-controller.js

@@ -2,6 +2,7 @@ import { Camera } from "@babylonjs/core/Cameras/camera.js";
 import { ArcRotateCamera } from "@babylonjs/core/Cameras/arcRotateCamera.js";
 import { Ray } from "@babylonjs/core/Culling/ray.js";
 import { Vector3 } from "@babylonjs/core/Maths/math.vector.js";
+import BabylonJSCameraWheelMotion from "./babylonjs-camera-wheel-motion.js";
 
 /**
  * Maintains a geometry-dependent orbital zoom floor without moving the camera target.
@@ -245,6 +246,9 @@ export default class BabylonJSCameraZoomController {
         const length = Math.max(basis.distance, this.#previousDistance);
         const minimum = Math.max(this.#originalLimit ?? 0, this.#minimumDistance(basis, length) / basis.scale);
         camera.lowerRadiusLimit = minimum;
+        if (camera.radius <= minimum) {
+            BabylonJSCameraWheelMotion.stopInward(camera);
+        }
         if (camera.radius < minimum) {
             camera.radius = minimum;
             if (camera.inertialRadiusOffset > 0) {

package/src/babylonjs-controller.js

@@ -1,4 +1,4 @@
-import { ArcRotateCamera, AssetContainer, BRDFTextureTools, Camera, Color3, Color4, DefaultRenderingPipeline, DirectionalLight, Engine, FreeCamera, HDRCubeTexture, HemisphericLight, IblShadowsRenderPipeline, ImageProcessingConfiguration, LoadAssetContainerAsync, Material, Matrix, MeshBuilder, PBRMaterial, PointerEventTypes, PointLight, RenderTargetTexture, Scene, ShadowGenerator, SpotLight, SSAORenderingPipeline, Texture, Tools, UniversalCamera, Vector3, WebXRDefaultExperience, WebXRFeatureName, WebXRSessionManager, WebXRState, WhenTextureReadyAsync } from "@babylonjs/core";
+import { ArcRotateCamera, AssetContainer, BRDFTextureTools, Camera, Color3, Color4, CubeTexture, DefaultRenderingPipeline, DirectionalLight, Engine, FreeCamera, HDRCubeTexture, HemisphericLight, IblShadowsRenderPipeline, ImageProcessingConfiguration, LoadAssetContainerAsync, Material, Matrix, MeshBuilder, PBRMaterial, PointerEventTypes, PointLight, RenderTargetTexture, Scene, ShadowGenerator, SpotLight, SSAORenderingPipeline, Texture, Tools, UniversalCamera, Vector3, WebXRDefaultExperience, WebXRFeatureName, WebXRSessionManager, WebXRState, WhenTextureReadyAsync } from "@babylonjs/core";
 import { DracoCompression } from "@babylonjs/core/Meshes/Compression/dracoCompression.js";
 import "@babylonjs/loaders";
 import "@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression.js";
@@ -11,6 +11,7 @@ import BabylonJSAnimationController from "./babylonjs-animation-controller.js";
 import BabylonJSViewCubeController from "./babylonjs-view-cube-controller.js";
 import BabylonJSCameraFraming from "./babylonjs-camera-framing.js";
 import BabylonJSCameraZoomController from "./babylonjs-camera-zoom-controller.js";
+import BabylonJSCameraWheelMotion from "./babylonjs-camera-wheel-motion.js";
 import BabylonJSSelectionController from "./babylonjs-selection-controller.js";
 import OpeningAnimation from "./babylonjs-animation-opening.js";
 import I18n from "./localization/i18n.js";
@@ -838,7 +839,7 @@ export default class BabylonJSController {
      */
     #isArcRotateCameraInMotion(camera) {
         const EPSILON = 0.00001;
-        return Math.abs(camera?.inertialAlphaOffset || 0) > EPSILON || Math.abs(camera?.inertialBetaOffset || 0) > EPSILON || Math.abs(camera?.inertialRadiusOffset || 0) > EPSILON || Math.abs(camera?.inertialPanningX || 0) > EPSILON || Math.abs(camera?.inertialPanningY || 0) > EPSILON;
+        return BabylonJSCameraWheelMotion.isMoving(camera) || Math.abs(camera?.inertialAlphaOffset || 0) > EPSILON || Math.abs(camera?.inertialBetaOffset || 0) > EPSILON || Math.abs(camera?.inertialRadiusOffset || 0) > EPSILON || Math.abs(camera?.inertialPanningX || 0) > EPSILON || Math.abs(camera?.inertialPanningY || 0) > EPSILON;
     }
 
     /**
@@ -1076,6 +1077,7 @@ export default class BabylonJSController {
         this.#camera.lowerBetaLimit = null;
         this.#camera.allowUpsideDown = false;
         this.#camera.wheelDeltaPercentage = BabylonJSController.config.camera.wheelDeltaPercentage;
+        this.#camera.zoomToMouseLocation = true;
         this.#camera.lowerRadiusLimit = null;
         this.#camera.upperRadiusLimit = 20;
         this.#camera.metadata = { locked: false };
@@ -1332,7 +1334,7 @@ export default class BabylonJSController {
      * @returns {Promise<boolean>} Returns true if the environment texture was changed, false if it was already up to date or failed to load.
      * @description
      * Lifecycle implemented here:
-     * 1. If `options.ibl.cachedUrl` exists, create `HDRCubeTexture` from it.
+     * 1. If `options.ibl.cachedUrl` exists, create `HDRCubeTexture` from it (a prefiltered `CubeTexture` when `options.ibl.url` is a `.env`).
      * 2. Wait for readiness, clone it into `#hdrTexture` for reuse.
      * 3. Call `options.ibl.consumeCachedUrl(true)` to revoke temporary object URLs and clear `cachedUrl`.
      * 4. On following reloads, if `options.ibl.valid === true` and no `cachedUrl` is present, use `#hdrTexture.clone()`.
@@ -1346,8 +1348,13 @@ export default class BabylonJSController {
         let hdrTexture = null;
         if (this.#options.ibl?.cachedUrl) {
             const hdrTextureURI = this.#options.ibl.cachedUrl;
-            const envTextureSize = BabylonJSController.config.quality.environmentTextureSize || 1024;
-            hdrTexture = new HDRCubeTexture(hdrTextureURI, this.#scene, envTextureSize, false, false, false, true, undefined, undefined, false, true, true);
+            if (/\.env$/i.test(String(this.#options.ibl.url ?? "").split(/[?#]/)[0])) {
+                // The cached file is a blob: URL with no extension, so the loader is told it is a .env.
+                hdrTexture = CubeTexture.CreateFromPrefilteredData(hdrTextureURI, this.#scene, ".env");
+            } else {
+                const envTextureSize = BabylonJSController.config.quality.environmentTextureSize || 1024;
+                hdrTexture = new HDRCubeTexture(hdrTextureURI, this.#scene, envTextureSize, false, false, false, true, undefined, undefined, false, true, true);
+            }
         } else if (this.#hdrTexture && this.#options.ibl?.valid === true) {
             hdrTexture = this.#hdrTexture.clone();
         } else {
@@ -1584,7 +1591,7 @@ export default class BabylonJSController {
             return generator.getLight()?.name === "PrefViewerDirLight";
         });
 
-        this.#containers.environment?.AssetContainer?.lights.forEach((light) => {
+        this.#containers.environment?.assetContainer?.lights.forEach((light) => {
             // Only shadows for DirectionalLight and SpotLight types
             if (!(light instanceof DirectionalLight || light instanceof SpotLight)) {
                 return;
@@ -1593,7 +1600,9 @@ export default class BabylonJSController {
             const shadowGenerator = new ShadowGenerator(1024, light);
             shadowGenerator.useBlurExponentialShadowMap = true;
             shadowGenerator.blurKernel = 16;
-            shadowGenerator.darkness = 0.5;
+            // KHR_lights_punctual parents the light to its glTF node, which carries the node's extras.
+            const extrasShadowDarkness = light.parent?.metadata?.gltf?.extras?.shadowDarkness;
+            shadowGenerator.darkness = typeof extrasShadowDarkness === "number" && Number.isFinite(extrasShadowDarkness) ? Math.min(Math.max(extrasShadowDarkness, 0), 1) : 0.5;
             shadowGenerator.bias = 0.0005;
             shadowGenerator.normalBias = 0.02;
             shadowGenerator.getShadowMap().refreshRate = RenderTargetTexture.REFRESHRATE_RENDER_ONCE;
@@ -2656,6 +2665,8 @@ export default class BabylonJSController {
                 cameraState.setSuccess(true);
             }
         }
+        BabylonJSCameraWheelMotion.cancel(this.#scene.activeCamera);
+        BabylonJSCameraWheelMotion.cancel(camera);
         this.#applyShowroomCameraFraming(camera);
         this.#fitDefaultCameraToModel(camera);
         this.#scene.activeCamera?.detachControl();
@@ -3458,6 +3469,8 @@ export default class BabylonJSController {
      * @returns {Promise<void>}
      */
     async disable() {
+        BabylonJSCameraWheelMotion.cancel(this.#scene?.activeCamera);
+        BabylonJSCameraWheelMotion.cancel(this.#camera);
         this.#cameraZoom?.dispose();
         this.#cameraZoom = null;
         this.#viewCubeSuspended = true;

package/src/babylonjs-view-cube-controller.js

@@ -3,6 +3,7 @@ import { PrefViewerViewCubeStyles } from "./styles.js";
 import I18n from "./localization/i18n.js";
 import BabylonJSController from "./babylonjs-controller.js";
 import BabylonJSCameraFraming from "./babylonjs-camera-framing.js";
+import BabylonJSCameraWheelMotion from "./babylonjs-camera-wheel-motion.js";
 
 /**
  * @typedef {import("./babylonjs-camera-framing.js").FramingCamera} ViewCubeCamera
@@ -395,6 +396,7 @@ export default class BabylonJSViewCubeController {
      * @returns {void}
      */
     #clearInertia(camera) {
+        BabylonJSCameraWheelMotion.cancel(camera);
         for (const key of ["inertialAlphaOffset", "inertialBetaOffset", "inertialRadiusOffset", "inertialPanningX", "inertialPanningY"]) {
             if (key in camera) {
                 camera[key] = 0;