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

package/README.md

@@ -6,6 +6,10 @@
 
 - Native custom elements: `<pref-viewer>`, `<pref-viewer-2d>`, `<pref-viewer-3d>`, `<pref-viewer-dialog>`, and `<pref-viewer-menu-3d>`.
 - Babylon.js-based 3D visualization for glTF and GLB assets.
+- Default-enabled ViewCube with 26 selectable orientations, synchronized camera feedback, smooth model framing and perspective/orthographic support.
+- Model-only, geometry-dependent orbital zoom protection with near-plane sampling, independent of ViewCube visibility.
+- Viewer dialogs above the render menu and ViewCube, with background pointer-input protection.
+- Proportional mouse-wheel zoom for unlocked orbital cameras: increments decrease as the camera approaches its target, using Babylon's native input without an additional viewer zoom increment. Wheel sensitivity is currently an internal setting, not a public attribute or option.
 - 2D SVG drawing support with pan and zoom controls.
 - Unified `<pref-viewer>` wrapper that coordinates 2D, 3D, menu, dialog, localization, and loading lifecycle.
 - Sequential task queue for deterministic config, model, scene, materials, drawing, options, and culture updates.
@@ -92,7 +96,9 @@ viewer.setOptions({
 
 ## Configuration model
 
-The main `config` payload can include model, scene, materials, drawing, options, and culture data.
+The main `config` payload can include model, scene, materials, drawing, options, culture, styles, and boolean `showRenderMenu` / `showViewCube` flags.
+
+When a queued configuration is processed, explicit boolean flags update the corresponding `show-render-menu` and `show-view-cube` attributes before its assets load. Omitted or non-boolean flags preserve the current settings. Explicit processed flags override the corresponding current attributes; subsequent direct attribute changes remain effective. Reapplying an equal attribute value does not recreate the render menu. The same rules apply to `loadConfig(config)`, the `config` property setter and the JSON `config` attribute; flags follow existing task ordering, including during pending asset loads. These fields belong to the root config, alongside `culture` and `styles`.
 
 ```js
 viewer.loadConfig({
@@ -141,10 +147,39 @@ viewer.loadConfig({
     colorPrimary: "#ff6700",
   },
   culture: "en-EN",
+  showRenderMenu: true,
+  showViewCube: true,
   forceReload: false,
 });
 ```
 
+### Overlay visibility
+
+Use boolean values in config and string values in attributes:
+
+```js
+viewer.config = {
+  showRenderMenu: true,
+  showViewCube: false,
+};
+
+// Change only the cube flag; the menu keeps its current setting.
+viewer.loadConfig({ showViewCube: true });
+
+// Direct attribute control remains available after processing config.
+viewer.setAttribute("show-view-cube", "false");
+viewer.setAttribute("show-render-menu", "true");
+```
+
+```html
+<pref-viewer
+  mode="3d"
+  config='{"showRenderMenu":true,"showViewCube":false}'
+></pref-viewer>
+```
+
+Both overlays are enabled by default in 3D when their attributes are absent. Use explicit `"true"`/`"false"` strings for attributes: the menu accepts an absent attribute or literal `"true"` as enabled, whereas only literal `"false"` disables the cube. A config value such as `"false"` is a string and does not change visibility.
+
 ## Asset storage descriptors
 
 Storage descriptors are passed through `model.storage`, `scene.storage`, `materials.storage`, or `drawing.storage`.
@@ -198,16 +233,75 @@ Storage descriptors are passed through `model.storage`, `scene.storage`, `materi
 | `mode` | Viewer mode: `3d` or `2d`. Defaults to `3d`. |
 | `show-model` | Shows or hides the current 3D model. Use `true` or `false`. |
 | `show-scene` | Shows or hides the current 3D scene/environment. Use `true` or `false`. |
-| `show-render-menu` | Shows or hides the floating 3D render settings menu. Defaults to visible. |
+| `show-render-menu` | Shows the floating 3D render settings menu when absent or `"true"`; `"false"` hides it. Also configurable through boolean `config.showRenderMenu`. See [ViewCube layout](#viewcube-layout-and-lifecycle). |
+| `show-view-cube` | Shows the orientation cube in 3D. Enabled by default; only literal `"false"` disables it. Also configurable through boolean `config.showViewCube`. Runtime toggles preserve loaded assets and camera state. See [ViewCube](#viewcube). |
 | `styles` | JSON string with supported style overrides. Currently supports `colorPrimary`, applies it as `--pref-viewer-color-primary`, updates `PrefViewerStyleVariables.colorPrimary`, and persists it in `localStorage`. |
 
+## ViewCube
+
+The ViewCube reflects the effective active camera orientation and offers **26 views: six faces, twelve edges and eight corners**. Click any region to change orientation smoothly and refit the model assetContainer. Every accepted click refits, even when selecting the current orientation: previous pan, framing and zoom are discarded. Environment geometry is excluded from this fit; only visible, enabled model meshes with valid geometry contribute to bounds. Hidden or disabled model geometry, including auxiliary walls/floors hidden by viewer options, does not enlarge the fit.
+
+The active camera retains its identity and perspective or orthographic projection. Navigation supports Babylon ArcRotateCamera, FreeCamera and UniversalCamera, including supported parent transforms. Other camera classes, locked cameras and active XR tracked cameras are display-only. Selection does nothing when usable model bounds, a supported camera or positive viewport dimensions are unavailable.
+
+### Orientation and feedback
+
+The inner view is the principal model view. English ViewCube labels use `Inner` and `Outer` (displayed as `INNER` and `OUTER`); Spanish labels remain `Interior` and `Exterior`. Accessible names and combined edge/corner labels use the same localized terms. Face names use this world-axis convention:
+
+| Direction | World axis | Reference |
+| --- | --- | --- |
+| Inner / Front | +Z | Looks toward the model from +Z. |
+| Outer / Back | -Z | Looks toward the model from -Z. |
+| Left | +X | Left relative to the inner view. |
+| Right | -X | Right relative to the inner view. |
+| Top / Superior | +Y | Looks down toward the model. |
+| Bottom / Inferior | -Y | Looks up toward the model. |
+
+The cube has sharp edges without chamfers. Edge regions appear as prism strips on both adjacent faces, with boundaries parallel to the edge; corner regions appear as small cubes. All visible surfaces belonging to an edge or corner select the same orientation.
+
+Hover uses `styles.colorPrimary`, backed by `PrefViewerStyleVariables.colorPrimary`, with **50% fill opacity** and fully opaque borders around the complete clickable region. Face hover fills only its central clickable area, excluding edge/corner regions. The angularly nearest of the 26 views has **15% primary-color fill** and no highlighted border; hover takes precedence until the pointer leaves. Primary-color and culture changes update the existing overlay. There are no region tooltips; visible face labels use uppercase lettering and increased letter spacing for readability; accessible region names remain localized.
+
+Cube perspective follows the active camera's projection and FOV. Mouse movement changes feedback without rebuilding SVG geometry; camera pose/projection changes update the projected geometry. The cube remains independent of model zoom and does not add Babylon scene meshes or appear in exports.
+
+### ViewCube layout and lifecycle
+
+The cube stays at **top 0px / right 0px**. When both overlays are enabled, the render-menu top equals the **measured cube SVG viewport height** and updates when that size changes. The maximum cube viewport is 100 × 100 CSS pixels and shrinks to fit smaller scene viewports; the menu offset is measured, not fixed to that value. Without the cube, the menu returns to its style-defined default top. The cube remains below the menu's layer, and viewer modals cover both.
+
+Cube resources are created only while enabled in a visible 3D view. Disabling it or switching to 2D releases its overlay, listeners, observers and pending transition. Reactivation uses the current camera without reloading assets. Layout subscriptions connect before activation and are removed when inactive or disconnected.
+
+Rapid selections retarget the transition from the displayed pose. Canvas pointer/wheel/key interaction, resize, projection change, camera/model replacement, locking, disabling or disposal cancels pending navigation; unlocking/reactivation does not replay it. Transitions use the existing demand-rendering scheduler and release their activity when finished without stopping unrelated model animations.
+
+## 3D camera and wheel zoom
+
+The default orbital camera starts on the **Inner (+Z)** side before the ViewCube is created, so the loading indicator does not first show Outer and then switch to Inner when model framing completes. The initial fit uses the same model bounds and projection-aware calculation as the ViewCube, with the shared framing factor (`BabylonJSController.config.camera.fitMarginFactor`) of 0.15. The resulting fit matches a cube destination for the same orientation, projection and canvas dimensions; the initial orientation is exact Inner, with no elevation, so selecting Inner immediately after loading preserves the view. The initial fit preserves its orbit angles; later model reloads preserve the user's current orientation. Explicitly selected cameras from the model or environment retain their authored view, which may differ from Inner.
+
+The shared internal setting `BabylonJSController.config.camera.fitMarginFactor` accepts finite values from **0 to 0.5, inclusive**. It reserves a total fraction of the viewport along the limiting axis; the model's projected bounding envelope can occupy `1 - fitMarginFactor` of that axis. It is applied when automatic or ViewCube framing runs, rather than continuously changing the current zoom.
+
+| fitMarginFactor | Space available for the model | Margin at each opposing edge of the limiting axis |
+| --- | --- | --- |
+| 0 | 100% | 0% |
+| 0.1 | 90% | 5% |
+| 0.15 (default) | 85% | 7.5% |
+| 0.5 | 50% | 25% |
+
+Increasing the factor makes the fitted model smaller. The other axis can have more free space because framing preserves aspect ratio. The calculation uses visible model world bounds; the actual silhouette may occupy less space, and near-plane safety can require extra clearance. Invalid values leave the existing camera framing unchanged. This setting replaces the internal `fitFactor` name and its previous semantics; it is not a property of the public viewer `config` object.
+
+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.
+
+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.
+
+For the default camera with a visible model, the near clipping plane moves closer to the eye as the radius decreases: `minZ` is capped at `max(0.00001, abs(radius) * 0.001)`, retaining any smaller existing positive value. The plane stays in front of the eye; `maxZ`, FOV and projection mode remain unchanged. Imported cameras retain their clipping configuration, and locks/XR/explicit cube transitions preserve their existing policy. Protection samples the updated projection and accounts for near-plane depth and a small safety margin. Perspective samples the center, edge midpoints and corners of the near-plane footprint; orthographic uses the center probe with near-depth clearance. Large inward steps and inertia are constrained at detected surfaces, while outward retreat remains possible. If a checked near-plane point is already inside a closed model mesh, recovery finds its outward triangle-surface exit even when the previous radius is equally short. Empty gaps within mesh bounds are not treated as solids; environment meshes are never queried during recovery. The geometry guard changes radius rather than moving or constraining the target and preserves projection mode; adaptive default-camera near depth is handled separately. Authored minimum-radius constraints remain respected and are restored when releasing a camera. Explicit cube transitions temporarily suspend the geometry floor so the requested model fit can complete; protection resumes afterward.
+
+These are sampled ray checks, not continuous volume collision. Small surfaces between probes, open/non-manifold geometry and custom/deformed rigs are not guaranteed to be protected. Interior-point recovery assumes closed meshes. In extreme close-up or grazing-angle views, small parts between the samples may still show minor edge clipping; this is a known limitation of the sampled protection. It does not guarantee clipping-free inspection of every surface. Orthographic protection does not sample the complete near-plane area.
+
 ## Public methods
 
 ### Loading and configuration
 
 | Method | Description |
 | --- | --- |
-| `loadConfig(config)` | Queues a full configuration update. Accepts an object or JSON string with model, scene, materials, drawing, options, culture, styles, and visibility descriptors. |
+| `loadConfig(config)` | Queues a full configuration update. Accepts an object or JSON string with model, scene, materials, drawing, options, culture, styles, boolean showRenderMenu/showViewCube flags, and visibility descriptors. |
 | `loadModel(model)` | Queues a model update. |
 | `loadScene(scene)` | Queues a scene/environment update. |
 | `loadMaterials(materials)` | Queues a materials update. |
@@ -265,12 +359,14 @@ Selection colors are rendered through disposable SVG clones; the loaded base SVG
 
 | Method | Description |
 | --- | --- |
-| `openDialog(title, content, footer)` | Opens a viewer dialog. |
+| `openDialog(title, content, footer)` | Opens a modal above viewer content, including the render menu and ViewCube. Its backdrop intercepts background pointer input. Returns the dialog element on success or `null` if opening fails. |
 | `closeDialog()` | Closes the active viewer dialog. |
 | `downloadModelGLB()` / `downloadModelGLTF()` / `downloadModelUSDZ()` | Exports the current model. |
 | `downloadSceneGLB()` / `downloadSceneGLTF()` / `downloadSceneUSDZ()` | Exports the current scene/environment. |
 | `downloadModelAndSceneGLB()` / `downloadModelAndSceneGLTF()` / `downloadModelAndSceneUSDZ()` | Exports the combined model and scene. |
 
+All viewer dialogs share this priority, including the model-download dialog opened with **Ctrl+Alt+D** while the 3D canvas receives keyboard input. Existing backdrop dismissal remains available: a click over a covered control may close the dialog, but does not also activate that control. Closing the dialog restores access to the underlying controls.
+
 ## Public properties
 
 ### Setters
@@ -279,7 +375,7 @@ These setters are convenience bridges for framework bindings and property-based
 
 | Property | Description |
 | --- | --- |
-| `config` | Forwards to `loadConfig(value)`. |
+| `config` | Forwards an object or JSON string to `loadConfig(value)`, including boolean overlay flags with the same queue ordering and omission rules. |
 | `model` | Forwards to `loadModel(value)`. |
 | `scene` | Forwards to `loadScene(value)`. |
 | `materials` | Forwards to `loadMaterials(value)`. |
@@ -339,7 +435,7 @@ The component emits custom events so host applications can integrate loading ind
 
 ### Internal Listeners
 
-`<pref-viewer>` listens to `pref-viewer-2d-viewport-changed` from `<pref-viewer-2d>`, `pref-viewer-3d-loaded` and `pref-viewer-3d-error` from `<pref-viewer-3d>`, and `pref-viewer-3d-render-settings-change-requested` from `<pref-viewer-menu-3d>`. `BabylonJSController` listens to `pref-viewer-3d-animation-changed` from the nearest `<pref-viewer-3d>` host.
+`<pref-viewer>` listens to `pref-viewer-2d-viewport-changed` from `<pref-viewer-2d>`, `pref-viewer-3d-loaded` and `pref-viewer-3d-error` from `<pref-viewer-3d>`, and `pref-viewer-3d-render-settings-change-requested` from `<pref-viewer-menu-3d>`. `BabylonJSController` listens to `pref-viewer-3d-animation-changed` from the nearest `<pref-viewer-3d>` host. The root also conditionally subscribes to the internal, non-bubbling `view-cube-layout` event while the cube is active in 3D. It carries measured layout dimensions for the render menu and is not a new public root event.
 
 Example:
 
@@ -403,6 +499,8 @@ viewer.setStyles({
 });
 ```
 
+The ViewCube uses this same primary color for its hover and active-orientation feedback. Changing `colorPrimary` through `styles` or `config` attributes, `setStyles`, or `loadConfig({ styles })` also updates animation-opening highlight color, including an opening currently highlighted, without reloading the model or changing whether highlighting is enabled. The render menu color control stays synchronized. Persisted primary styles are applied to highlights when the viewer connects. `options.render.highlightColor` can still set an explicit highlight color; a later primary-style update replaces it.
+
 Only `colorPrimary` is currently supported. The value updates `PrefViewerStyleVariables.colorPrimary`, is exposed on the host as `--pref-viewer-color-primary`, and is persisted in `localStorage` under `pref-viewer/styles`. Persisted styles are restored when a new `<pref-viewer>` instance is created and connected.
 
 ## Localization
@@ -440,7 +538,39 @@ Start the local playground:
 npm start
 ```
 
-The playground is available from `playground/index.html` and serves the project through `http-server` after bundling the local source.
+The playground is available from `playground/index.html` at `http://localhost:8080/` and serves the project through `http-server` after bundling the local source. Use it for manual ViewCube, wheel-zoom and modal checks with representative model/environment assets. The separate ViewCube test HTML/script and its generated fixture bundle have been removed; automated tests remain.
+
+### Camera implementation and maintenance
+
+- `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-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.
+
+ViewCube class members are ordered as properties, constructor, static methods, private methods and public methods/getters. New classes and new/modified methods carry JSDoc describing their parameters, return values and current lifecycle/side effects. JavaScript `if` and `for` bodies always use braces, including single-statement bodies. Focused tests live in `tests/babylonjs-camera-framing.test.js`, `tests/babylonjs-view-cube-controller.test.js`, `tests/babylonjs-camera-zoom-controller.test.js`, `tests/babylonjs-controller-wheel.test.js` and `tests/pref-viewer.test.js`. Browser checks in the existing playground remain necessary for visual projection, hover regions and modal stacking.
+
+### ViewCube SVG style maintenance
+
+The following variables are defined in the root rule of `PrefViewerViewCubeStyles` in `src/styles.js`. They centralize defaults for future stylesheet changes; they are not additional properties supported by `setStyles` or `config.styles`.
+
+| CSS variable | Default |
+| --- | --- |
+| `--cube-fill-color` | `#eef0f3` |
+| `--cube-border-color` | `#78838f` |
+| `--cube-border-width` | `1.0px` in the SVG coordinate system; also used by the hover outline |
+| `--cube-hover-color` | Shared primary color; used by the fill and opaque outline |
+| `--cube-hover-opacity` | `0.50` fill opacity |
+| `--cube-active-color` | Shared primary color |
+| `--cube-active-opacity` | `0.15` fill opacity |
+| `--cube-text-font-family` | `Arial, sans-serif` |
+| `--cube-text-font-size` | `9px` |
+| `--cube-text-color` | `#29323b` |
+| `--cube-text-font-weight` | `600` |
+| `--cube-text-letter-spacing` | `1.0px` |
+
+Both feedback colors default to `var(--pref-viewer-color-primary, ...)`, preserving supported runtime primary-color updates. Text size and spacing apply in the SVG coordinate system and scale with its viewport. Active-view borders remain transparent; hover borders remain fully opaque regardless of fill opacity. Geometry and input behavior remain owned by the controller.
 
 ## Package scripts
 

package/index.d.ts

@@ -29,6 +29,12 @@ export interface PrefViewerAsset {
 
 /** Payload for `loadConfig`. Pass the object; a JSON string is also accepted. */
 export interface PrefViewerConfig {
+  /** Sets show-render-menu when supplied; omission preserves the current attribute. */
+  showRenderMenu?: boolean;
+  /** Sets show-view-cube when supplied; omission preserves the current attribute. */
+  showViewCube?: boolean;
+  culture?: string;
+  styles?: Record<string, unknown> | string;
   model?: PrefViewerAsset;
   scene?: PrefViewerAsset;
   materials?: PrefViewerAsset;
@@ -250,6 +256,7 @@ export declare class PrefViewer extends HTMLElement {
   /** Convenience wrapper for `setOptions({ ibl })`. False when the payload is unusable. */
   setIBL(ibl: Record<string, unknown> | string): boolean | void;
   /** Runtime style overrides; currently `{ colorPrimary }`. False when unusable. */
+  /** Updates primary UI and animation-opening highlight color, including an active highlight. */
   setStyles(styles: Record<string, unknown> | string): boolean | void;
   /** 3D runtime diagnostics, or null before the 3D component exists. */
   getDebugInfo(): Record<string, unknown> | null;
@@ -350,6 +357,8 @@ export interface PrefViewerAttributes {
   "show-model"?: boolean | "true" | "false";
   "show-scene"?: boolean | "true" | "false";
   "show-render-menu"?: boolean | "true" | "false";
+  /** Enable the orientation cube in 3D (default: true); false releases its overlay resources. */
+  "show-view-cube"?: boolean | "true" | "false";
 }
 
 /** <pref-viewer mode="3d" style="display:block; width:100%; height:600px" /> */

package/package.json

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

package/src/babylonjs-camera-framing.js

@@ -0,0 +1,171 @@
+import { Matrix, Quaternion, Vector3 } from "@babylonjs/core/Maths/math.vector.js";
+import BabylonJSController from "./babylonjs-controller.js";
+
+/**
+ * Supported camera adapters; the host keeps ownership of their lifecycle.
+ * @typedef {import("@babylonjs/core").ArcRotateCamera|import("@babylonjs/core").FreeCamera|import("@babylonjs/core").UniversalCamera} FramingCamera
+ */
+
+/**
+ * Model-only world bounds used for framing.
+ * @typedef {Object} CameraFramingBounds
+ * @property {Vector3} center - World-space bounding-box center.
+ * @property {number} radius - Half the bounding-box diagonal.
+ * @property {Vector3[]} corners - Eight world-space bounding-box corners.
+ */
+
+/**
+ * Destination framing shared by the camera adapters.
+ * @typedef {Object} CameraFramingFit
+ * @property {Vector3} target - Model center in world space.
+ * @property {number} distance - Destination camera-to-target world distance.
+ * @property {Quaternion} rotation - Destination world orientation.
+ * @property {number} halfWidth - Orthographic horizontal half-extent.
+ * @property {number} halfHeight - Orthographic vertical half-extent.
+ * @property {number} radius - Model bounds radius used for clipping adjustments.
+ */
+
+/**
+ * BabylonJSCameraFraming - Calculates model-only world bounds and projection-aware camera fits.
+ *
+ * Stateless utilities shared by camera navigation controllers. Destination calculations preserve
+ * the camera and its projection; callers apply the returned pose and orthographic extents.
+ * Reads the shared camera margin at call time and does not own assets or rendering resources.
+ * @class
+ */
+export default class BabylonJSCameraFraming {
+
+    /**
+     * Checks that all three vector components are finite numbers.
+     * @private
+     * @static
+     * @param {Vector3|null|undefined} v - Candidate vector.
+     * @returns {boolean|null|undefined} True for usable coordinates; otherwise false or the absent input.
+     */
+    static #finiteVector(v) {
+        return v && [v.x, v.y, v.z].every(Number.isFinite);
+    }
+
+    /**
+     * Computes model-only world bounds from visible, enabled meshes with valid geometry.
+     * Updates mesh world matrices; never includes an environment container implicitly.
+     * @public
+     * @static
+     * @param {import("@babylonjs/core").AssetContainer|null|undefined} container - Model asset container.
+     * @returns {CameraFramingBounds|null} Bounds and eight corners, or null for missing/degenerate geometry.
+     */
+    static getModelBounds(container) {
+        let min = null;
+        let max = null;
+        for (const mesh of container?.meshes ?? []) {
+            if ((mesh?.getTotalVertices?.() ?? 0) <= 0 || mesh.isDisposed?.() || mesh.isEnabled?.() === false || mesh.isVisible === false || mesh.visibility <= 0) {
+                continue;
+            }
+            mesh.computeWorldMatrix(true);
+            const box = mesh.getBoundingInfo?.()?.boundingBox;
+            if (!BabylonJSCameraFraming.#finiteVector(box?.minimumWorld) || !BabylonJSCameraFraming.#finiteVector(box?.maximumWorld)) {
+                continue;
+            }
+            min = min ? Vector3.Minimize(min, box.minimumWorld) : box.minimumWorld.clone();
+            max = max ? Vector3.Maximize(max, box.maximumWorld) : box.maximumWorld.clone();
+        }
+        if (!min || !max) {
+            return null;
+        }
+        const radius = Vector3.Distance(min, max) / 2;
+        if (!Number.isFinite(radius) || radius <= 0) {
+            return null;
+        }
+        const corners = [];
+        for (const x of [min.x, max.x]) {
+            for (const y of [min.y, max.y]) {
+                for (const z of [min.z, max.z]) {
+                    corners.push(new Vector3(x, y, z));
+                }
+            }
+        }
+        return { center: Vector3.Center(min, max), radius, corners };
+    }
+
+    /**
+     * Checks whether the camera has a supported navigation adapter.
+     * @public
+     * @static
+     * @param {import("@babylonjs/core").Camera|null|undefined} camera - Camera to inspect.
+     * @returns {boolean} Whether it is an ArcRotateCamera, FreeCamera or UniversalCamera.
+     */
+    static isCameraSupported(camera) {
+        return ["ArcRotateCamera", "FreeCamera", "UniversalCamera"].includes(camera?.getClassName?.());
+    }
+
+    /**
+     * Builds a destination view basis using world +Y as up and the scene handedness.
+     * Applies a minimal horizontal offset at the poles to avoid a singular look-at matrix.
+     * @private
+     * @static
+     * @param {Vector3} direction - World-space direction from the target towards the camera.
+     * @param {boolean} rightHanded - Whether the scene uses right-handed coordinates.
+     * @returns {{view: Matrix, rotation: Quaternion}} View matrix and world orientation.
+     */
+    static #viewBasis(direction, rightHanded) {
+        // A tiny pole offset avoids a singular look-at while keeping world +Y as camera up.
+        const eye = direction.clone();
+        if (eye.x * eye.x + eye.z * eye.z < 1e-12) {
+            eye.z = 0.0001;
+        }
+        const view = (rightHanded ? Matrix.LookAtRH : Matrix.LookAtLH)(eye.normalize(), Vector3.Zero(), Vector3.Up());
+        const rotation = Quaternion.Identity();
+        view.clone().invert().decompose(undefined, rotation);
+        return { view, rotation };
+    }
+
+    /**
+     * Calculates destination framing from model corners without modifying the camera.
+     * Uses BabylonJSController.config.camera.fitMarginFactor as the total free viewport fraction.
+     * A factor of 0.1 leaves 90% available, reserving 5% at each opposing edge of the limiting axis.
+     * Preserves projection, including horizontal-fixed FOV. The factor must be finite and in [0, 0.5].
+     * Fits projected world-box corners; minimum near clearance can increase the requested inset.
+     * @public
+     * @static
+     * @param {FramingCamera} camera - Active supported camera.
+     * @param {CameraFramingBounds|null} bounds - Model-only world bounds.
+     * @param {Vector3} direction - Selected preset direction towards the observer.
+     * @param {{width: number, height: number}} viewport - Scene viewport dimensions in pixels.
+     * @returns {CameraFramingFit|null} Destination fit, or null when navigation inputs are unusable.
+     */
+    static calculateCameraFit(camera, bounds, direction, viewport) {
+        if (!bounds || !BabylonJSCameraFraming.isCameraSupported(camera) || !(viewport?.width > 0 && viewport?.height > 0)) {
+            return null;
+        }
+        const aspect = viewport.width / viewport.height;
+        const basis = BabylonJSCameraFraming.#viewBasis(direction, camera.getScene().useRightHandedSystem);
+        // Transform normals: discard the look-at matrix translation for offsets about the model center.
+        const points = bounds.corners.map((p) => Vector3.TransformNormal(p.subtract(bounds.center), basis.view));
+        const marginFactor = BabylonJSController.config.camera.fitMarginFactor;
+        if (!Number.isFinite(marginFactor) || marginFactor < 0 || marginFactor > 0.5) {
+            return null;
+        }
+        const available = 1 - marginFactor;
+        let distance = camera.mode === 1 ? bounds.radius * 1.01 : 0;
+        let halfWidth = 0;
+        let halfHeight = 0;
+        const tan = Math.tan(camera.fov / 2);
+        const tanX = camera.fovMode === 1 ? tan : tan * aspect;
+        const tanY = camera.fovMode === 1 ? tan / aspect : tan;
+        if (camera.mode !== 1 && (!(tanX > 0) || !(tanY > 0) || !Number.isFinite(tanX + tanY))) {
+            return null;
+        }
+        for (const p of points) {
+            halfWidth = Math.max(halfWidth, Math.abs(p.x) / available);
+            halfHeight = Math.max(halfHeight, Math.abs(p.y) / available);
+            // p.z is positive towards the observer in RH, negative in LH.
+            const towardObserver = camera.getScene().useRightHandedSystem ? p.z : -p.z;
+            if (camera.mode !== 1) {
+                distance = Math.max(distance, towardObserver + Math.max(bounds.radius * 0.001, 0.00001), towardObserver + Math.abs(p.x) / (tanX * available), towardObserver + Math.abs(p.y) / (tanY * available));
+            }
+        }
+        halfHeight = Math.max(halfHeight, halfWidth / aspect, bounds.radius * 0.001);
+        halfWidth = halfHeight * aspect;
+        return { target: bounds.center.clone(), distance, rotation: basis.rotation, halfWidth, halfHeight, radius: bounds.radius };
+    }
+}