@preference-sl/pref-viewer 2.18.0 → 3.0.0-beta.1

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

@@ -0,0 +1,1012 @@
+import BabylonJSCameraWheelMotion from "./babylonjs-camera-wheel-motion.js";
+import { Matrix, Quaternion, Vector3 } from "@babylonjs/core/Maths/math.vector.js";
+import { PrefViewerViewCubeStyles } from "./styles.js";
+import I18n from "./localization/i18n.js";
+import BabylonJSController from "./babylonjs-controller.js";
+import BabylonJSCameraFraming from "./babylonjs-camera-framing.js";
+
+/**
+ * @typedef {import("./babylonjs-camera-framing.js").FramingCamera} ViewCubeCamera
+ */
+
+/**
+ * @typedef {import("./babylonjs-camera-framing.js").CameraFramingBounds} ViewCubeBounds
+ */
+
+/**
+ * One planar surface of a sharp-cube interaction region.
+ * @typedef {Object} ViewCubeSurface
+ * @property {Vector3} normal - Outward cube-local normal.
+ * @property {Vector3[]} vertices - Four cube-local polygon vertices.
+ */
+
+/**
+ * Face, edge or corner orientation preset and its clickable geometry.
+ * @typedef {Object} ViewCubeRegion
+ * @property {string} id - Comma-separated signed axes identifying the preset.
+ * @property {Vector3} direction - Normalized direction from target toward observer.
+ * @property {"face"|"edge"|"corner"} kind - Interaction region category.
+ * @property {ViewCubeSurface[]} surfaces - One, two or three clickable planar surfaces.
+ * @property {ViewCubeSurface} [outline] - Full shell face, supplied only for face presets.
+ */
+
+/**
+ * @typedef {import("./babylonjs-camera-framing.js").CameraFramingFit} ViewCubeFit
+ */
+
+/**
+ * World-space pose snapshot for transition interpolation.
+ * @typedef {Object} ViewCubePose
+ * @property {Vector3} position - World-space camera position.
+ * @property {Quaternion} rotation - World-space camera orientation.
+ * @property {Vector3} target - Effective world-space target.
+ * @property {number} distance - Positive camera-to-target world distance.
+ * @property {number|null} left - Current orthographic left extent.
+ * @property {number|null} right - Current orthographic right extent.
+ * @property {number|null} bottom - Current orthographic bottom extent.
+ * @property {number|null} top - Current orthographic top extent.
+ */
+
+/**
+ * Virtual camera inputs used to project cube surfaces into SVG.
+ * @typedef {Object} ViewCubeProjection
+ * @property {Matrix} view - Cube-local to virtual camera rotation matrix.
+ * @property {boolean} perspective - Whether to apply perspective scaling.
+ * @property {number} depthSign - Scene handedness depth direction.
+ * @property {number} eyeDistance - Virtual camera distance independent of model zoom.
+ */
+
+/**
+ * BabylonJSViewCubeSVGController - Owns the selectable SVG orientation indicator and model-framing camera navigation.
+ *
+ * Displays 26 face/edge/corner presets with primary-color hover and nearest-view feedback.
+ * A final SVG label layer keeps face text above all interactive fills and highlight outlines.
+ * Synchronizes camera projection and orientation while locked cameras remain display-only.
+ * Stylesheets own widget dimensions; resize only caps them to the available viewport.
+ * Accepted clicks preserve projection, fit only model bounds and retain world +Y as camera up.
+ * Mouse or one-finger dragging orbits ArcRotateCamera directly, independently of canvas inputs, preserving target/radius/limits.
+ * Owns pointer capture and temporary touch hover until release or cancellation; full camera locks/XR forbid navigation.
+ *
+ * The host owns the camera, scene, assets and render loop. It calls tick() to advance transitions
+ * and sync() to refresh the indicator. The cube requests rendering but allocates no Engine,
+ * Scene or asset meshes. dispose() releases only the overlay and its listeners/observers.
+ *
+ * Members are ordered as properties, constructor, static methods, private methods and public methods.
+ * @class
+ */
+export default class BabylonJSViewCubeSVGController {
+    static #SVG_NS = "http://www.w3.org/2000/svg";
+    static #DRAG_THRESHOLD = 4;
+    static #DRAG_ANGLE = Math.PI;
+
+    #cameraDistances = new WeakMap();
+    #host;
+    #root;
+    #svg;
+    #regions = BabylonJSViewCubeSVGController.createViewCubeRegions();
+    #nodes = new Map();
+    #shell = [];
+    #geometryKey = null;
+    #locale;
+    #locked;
+    #enabled = false;
+    #transition = null;
+    #camera = null;
+    #observer = null;
+    #syncing = false;
+    #disposed = false;
+    #hover = null;
+    #pointer = null;
+    #listeners = [];
+    #resizeObserver;
+    #viewportResizeObserver;
+    #layoutKey = null;
+    #drag = null;
+    #touchFeedback = null;
+    #suppressClick = false;
+    #clickRegion = null;
+
+    /**
+     * Creates the CSS-sized SVG overlay with a final text layer above highlights, then enables input/lifecycle observers.
+     * The host retains ownership of the camera, scene, assets and render loop. Callbacks resolve
+     * current state so camera/model replacement does not leave the cube with stale references.
+     *
+     * @public
+     * @param {Object} host - Internal integration contract supplied by the owning viewer.
+     * @param {HTMLCanvasElement} host.canvas - Connected scene canvas; its parent receives the cube overlay.
+     * @param {function(): (import("@babylonjs/core").Camera|null|undefined)} host.getCamera - Returns the effective active camera, or no camera while unavailable.
+     * @param {function(import("@babylonjs/core").Camera|null|undefined): boolean} host.isLocked - Reports whether navigation is forbidden for the supplied camera, including unavailable cameras or active XR.
+     * @param {function(): (ViewCubeBounds|null)} host.getBounds - Returns current model-only world bounds and their eight corners; null when geometry is unusable. Excludes the environment.
+     * @param {function(): {width: number, height: number}} host.getViewport - Returns the current scene viewport dimensions in CSS pixels.
+     * @param {function(): void} host.requestRender - Requests rendering through the host scheduler after accepted navigation.
+     * @param {function(): string} [host.getCulture] - Returns the current localization culture; omitted callbacks use the translator's default culture.
+     * @param {function(number, number): void} [host.onLayout] - Receives the measured cube SVG viewport height and scene viewport height, in CSS pixels; zero cube height clears the menu offset, and disposal reports (0, 0).
+     */
+    constructor(host) {
+        this.#host = host;
+        const doc = host.canvas.ownerDocument;
+        this.#root = doc.createElement("div");
+        this.#root.className = "pref-viewer-view-cube";
+        this.#root.dataset.renderer = "svg";
+        const style = doc.createElement("style");
+        style.textContent = PrefViewerViewCubeStyles;
+        this.#root.append(style);
+        this.#svg = doc.createElementNS(BabylonJSViewCubeSVGController.#SVG_NS, "svg");
+        this.#svg.setAttribute("viewBox", "0 0 120 120");
+        this.#svg.setAttribute("role", "group");
+        this.#root.append(this.#svg);
+        const labels = doc.createElementNS(BabylonJSViewCubeSVGController.#SVG_NS, "g");
+        labels.setAttribute("class", "cube-labels");
+        for (const region of this.#regions.filter((r) => r.kind === "face")) {
+            const polygon = doc.createElementNS(BabylonJSViewCubeSVGController.#SVG_NS, "polygon");
+            polygon.setAttribute("class", "cube-shell");
+            this.#svg.append(polygon);
+            this.#shell.push({ ...region.outline, polygon });
+        }
+        for (const region of this.#regions) {
+            const group = doc.createElementNS(BabylonJSViewCubeSVGController.#SVG_NS, "g");
+            const surfaces = region.surfaces.map((surface) => {
+                const polygon = doc.createElementNS(BabylonJSViewCubeSVGController.#SVG_NS, "polygon");
+                polygon.dataset.region = region.id;
+                polygon.dataset.kind = region.kind;
+                group.append(polygon);
+                return { ...surface, polygon };
+            });
+            const label = doc.createElementNS(BabylonJSViewCubeSVGController.#SVG_NS, "text");
+            if (region.kind === "face") {
+                label.dataset.face = region.id;
+                labels.append(label);
+            }
+            this.#svg.append(group);
+            const outline = doc.createElementNS(BabylonJSViewCubeSVGController.#SVG_NS, "path");
+            outline.setAttribute("class", "hover-outline");
+            this.#nodes.set(region.id, { group, surfaces, label, outline });
+        }
+        // Stroke every clickable boundary above all filled regions, including interior face boundaries.
+        for (const node of this.#nodes.values()) {
+            this.#svg.append(node.outline);
+        }
+        this.#svg.append(labels);
+        host.canvas.parentElement.append(this.#root);
+        this.#addListener(this.#svg, "pointermove", this.#onPointerMove);
+        this.#addListener(this.#svg, "pointerleave", () => {
+            if (!this.#drag) {
+                this.#pointer = null;
+                this.#setHover(null);
+            }
+        });
+        this.#addListener(this.#svg, "pointerdown", this.#onPointerDown);
+        this.#addListener(this.#svg, "pointerup", this.#onPointerUp);
+        this.#addListener(this.#svg, "pointercancel", this.#onPointerUp);
+        this.#addListener(this.#svg, "lostpointercapture", this.#onPointerUp);
+        this.#addListener(this.#svg, "click", this.#onClick);
+        if (doc.defaultView) {
+            this.#addListener(doc.defaultView, "blur", () => this.#finishDrag());
+            this.#addListener(doc.defaultView, "keydown", this.#onDragKeyDown);
+        }
+        for (const event of ["pointerdown", "wheel", "keydown"]) {
+            this.#addListener(host.canvas, event, () => this.cancel());
+        }
+        this.#resizeObserver = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => this.resize());
+        this.#resizeObserver?.observe(host.canvas);
+        this.#viewportResizeObserver = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => this.#publishLayout());
+        this.#viewportResizeObserver?.observe(this.#svg);
+        this.setEnabled(true);
+    }
+
+    /**
+     * Captures a primary mouse or single-touch gesture on an unlocked orbital region independently of canvas inputs.
+     * Secondary touches cancel the pending gesture; touch uses temporary hover styling without a hold delay.
+     * Supported non-orbital cameras receive the same press feedback while retaining their preset-only navigation.
+     * Pending clicks retain their original selection behavior until movement exceeds the threshold.
+     * @private
+     * @param {PointerEvent} event - Pointer press originating on the SVG.
+     * @returns {void}
+     */
+    #onPointerDown = event => {
+        if (this.#drag || this.#touchFeedback) {
+            const pointerId = this.#drag?.pointerId ?? this.#touchFeedback.pointerId;
+            if (event.pointerType === "touch" && event.pointerId !== pointerId) {
+                event.stopPropagation();
+                this.#finishDrag();
+            }
+            return;
+        }
+        this.#suppressClick = false;
+        this.#clickRegion = null;
+        const region = BabylonJSViewCubeSVGController.#getRegionAt(event);
+        if (!region) {
+            return;
+        }
+        event.stopPropagation();
+        const camera = this.#host.getCamera();
+        if (event.button !== 0 || !["mouse", "touch"].includes(event.pointerType) || event.isPrimary === false
+            || this.#disposed || !this.#enabled || !BabylonJSCameraFraming.isCameraSupported(camera) || this.#host.isLocked(camera)) {
+            return;
+        }
+        if (!this.#isOrbit(camera) && event.pointerType !== "touch") {
+            return;
+        }
+        this.cancel();
+        if (event.pointerType === "touch") {
+            this.#pointer = null;
+            this.#touchFeedback = { pointerId: event.pointerId, region, camera, mode: camera.mode };
+            this.#setHover(region);
+        }
+        if (!this.#isOrbit(camera)) {
+            this.#svg.setPointerCapture?.(event.pointerId);
+            return;
+        }
+        this.#drag = { camera, region, mode: camera.mode, pointerId: event.pointerId, x: event.clientX, y: event.clientY,
+            alpha: camera.alpha, beta: camera.beta, size: Math.max(1, this.#svg.getBoundingClientRect().width), moved: false };
+        this.#svg.setPointerCapture?.(event.pointerId);
+    };
+
+    /**
+     * Rotates the captured orbital camera directly and requests continuous host interaction rendering after accepted movement.
+     * Preserves target/radius/projection and limits; capture allows mouse or touch movement outside the widget.
+     * Touch press feedback clears when movement crosses the drag threshold; uncaptured touch cannot create sticky hover.
+     * @private
+     * @param {PointerEvent} event - Pointer update, or ordinary hover when no drag is pending.
+     * @returns {void}
+     */
+    #onPointerMove = event => {
+        const drag = this.#drag;
+        if (!drag) {
+            if (event.pointerType === "touch") {
+                return;
+            }
+            this.#pointer = { x: event.clientX, y: event.clientY };
+            this.#setHover(BabylonJSViewCubeSVGController.#getRegionAt(event));
+            return;
+        }
+        if (event.pointerId !== drag.pointerId) {
+            return;
+        }
+        const camera = drag.camera;
+        if (this.#host.getCamera() !== camera || this.#host.isLocked(camera) || camera.mode !== drag.mode || !(event.buttons & 1)) {
+            this.#finishDrag();
+            return;
+        }
+        const dx = event.clientX - drag.x;
+        const dy = event.clientY - drag.y;
+        if (!drag.moved && Math.hypot(dx, dy) < BabylonJSViewCubeSVGController.#DRAG_THRESHOLD) {
+            return;
+        }
+        drag.moved = true;
+        this.#suppressClick = true;
+        this.#root.dataset.dragging = "true";
+        this.#pointer = null;
+        this.#setHover(null);
+        event.preventDefault();
+        event.stopPropagation();
+        const scale = BabylonJSViewCubeSVGController.#DRAG_ANGLE / drag.size;
+        const direction = camera.getScene().useRightHandedSystem ? -1 : 1;
+        this.#clearInertia(camera);
+        camera.alpha = Math.max(camera.lowerAlphaLimit ?? -Infinity,
+            Math.min(camera.upperAlphaLimit ?? Infinity, drag.alpha - dx * scale * direction));
+        camera.beta = Math.max(camera.lowerBetaLimit ?? 0.001,
+            Math.min(camera.upperBetaLimit ?? Math.PI - 0.001, drag.beta - dy * scale));
+        camera.getViewMatrix(true);
+        this.#host.requestRender({ interaction: true });
+        this.sync();
+    };
+
+    /**
+     * Releases the matching captured press/drag, clears temporary touch hover and suppresses a consumed drag's click.
+     * @private
+     * @param {PointerEvent} event - Release, cancellation or lost-capture event.
+     * @returns {void}
+     */
+    #onPointerUp = event => {
+        const gesture = this.#drag ?? this.#touchFeedback;
+        if (gesture?.pointerId === event.pointerId) {
+            if (event.type === "pointerup" && !this.#drag?.moved) {
+                this.#clickRegion = gesture.region;
+            }
+            this.#finishDrag(event.type === "pointerup");
+        }
+    };
+
+    /**
+     * Retains preset selection for clicks/taps and consumes compatibility clicks emitted after mouse or touch orbit.
+     * @private
+     * @param {MouseEvent} event - SVG click, including the browser's post-drag click.
+     * @returns {void}
+     */
+    #onClick = event => {
+        const capturedRegion = this.#clickRegion;
+        this.#clickRegion = null;
+        if (this.#suppressClick) {
+            this.#suppressClick = false;
+            event.preventDefault();
+            event.stopPropagation();
+            return;
+        }
+        const id = BabylonJSViewCubeSVGController.#getRegionAt(event) ?? capturedRegion;
+        if (!id) {
+            return;
+        }
+        event.stopPropagation();
+        if (event.button === 0) {
+            this.select(id);
+        }
+    };
+
+    /**
+     * Cancels an in-progress cube gesture on Escape without modifying its last accepted camera orientation.
+     * @private
+     * @param {KeyboardEvent} event - Owning window key event.
+     * @returns {void}
+     */
+    #onDragKeyDown = event => {
+        if (event.key === "Escape") {
+            this.#finishDrag();
+        }
+    };
+
+    /**
+     * Drops gesture ownership before releasing pointer capture so lost-capture dispatch cannot recurse.
+     * Suppresses trailing clicks for cancelled gestures, including those below the movement threshold.
+     * Clears touch hover for both orbital drags and non-orbital press feedback.
+     * No camera inputs or scene resources are changed.
+     * @private
+     * @param {boolean} [allowClick=false] - A normal pointer release permits a short click; cancellation does not.
+     * @returns {void}
+     */
+    #finishDrag(allowClick = false) {
+        const drag = this.#drag;
+        const touch = this.#touchFeedback;
+        const pointerId = drag?.pointerId ?? touch?.pointerId;
+        if ((drag && (!allowClick || drag.moved)) || (touch && !allowClick)) {
+            this.#suppressClick = true;
+            this.#clickRegion = null;
+        }
+        this.#drag = null;
+        this.#touchFeedback = null;
+        if (touch) {
+            this.#pointer = null;
+            this.#setHover(null);
+        }
+        delete this.#root.dataset.dragging;
+        if (pointerId !== undefined && this.#svg.hasPointerCapture?.(pointerId)) {
+            this.#svg.releasePointerCapture(pointerId);
+        }
+    }
+
+    /**
+     * Creates the 26 signed-axis presets and their sharp-cube interaction surfaces.
+     * Edges share two prism surfaces; corners share three surfaces. Face outlines form the shell.
+     * @public
+     * @static
+     * @returns {ViewCubeRegion[]} Six face, twelve edge and eight corner regions with normalized directions.
+     */
+    static createViewCubeRegions() {
+        const regions = [];
+        const inset = 0.78;
+        for (let i = 0; i < 3; i++) {
+            for (const s of [-1, 1]) {
+                const axis = [0, 0, 0];
+                axis[i] = s;
+                BabylonJSViewCubeSVGController.#addRegion(regions, axis, [
+                    BabylonJSViewCubeSVGController.#createSurface(i, s, [
+                        [-inset, inset],
+                        [-inset, inset],
+                        [-inset, inset],
+                    ]),
+                ]);
+                regions.at(-1).outline = BabylonJSViewCubeSVGController.#createSurface(i, s, [
+                    [-1, 1],
+                    [-1, 1],
+                    [-1, 1],
+                ]);
+            }
+        }
+        for (let i = 0; i < 3; i++) {
+            for (let j = i + 1; j < 3; j++) {
+                for (const s of [-1, 1]) {
+                    for (const t of [-1, 1]) {
+                        const axis = [0, 0, 0];
+                        axis[i] = s;
+                        axis[j] = t;
+                        const ranges = [
+                            [-inset, inset],
+                            [-inset, inset],
+                            [-inset, inset],
+                        ];
+                        ranges[i] = [s * inset, s];
+                        ranges[j] = [t * inset, t];
+                        BabylonJSViewCubeSVGController.#addRegion(regions, axis, [BabylonJSViewCubeSVGController.#createSurface(i, s, ranges), BabylonJSViewCubeSVGController.#createSurface(j, t, ranges)]);
+                    }
+                }
+            }
+        }
+        for (const x of [-1, 1]) {
+            for (const y of [-1, 1]) {
+                for (const z of [-1, 1]) {
+                    const signs = [x, y, z];
+                    const ranges = signs.map((s) => [s * inset, s]);
+                    BabylonJSViewCubeSVGController.#addRegion(regions,
+                        signs,
+                        signs.map((s, i) => BabylonJSViewCubeSVGController.#createSurface(i, s, ranges)),
+                    );
+                }
+            }
+        }
+        return regions;
+    }
+
+    /**
+     * Creates a signed-axis quad with its normal and four cube-space vertices.
+     * @private
+     * @static
+     * @param {number} axis - Fixed coordinate axis index.
+     * @param {number} sign - Fixed axis direction, -1 or 1.
+     * @param {Array<number[]>} ranges - Lower and upper coordinates for each axis.
+     * @returns {{normal:Vector3,vertices:Vector3[]}}
+     */
+    static #createSurface(axis, sign, ranges) {
+        const other = [0, 1, 2].filter((i) => i !== axis);
+        const normalComponents = [0, 0, 0];
+        normalComponents[axis] = sign;
+        const normal = new Vector3(...normalComponents);
+        const vertices = [
+            [0, 0],
+            [1, 0],
+            [1, 1],
+            [0, 1],
+        ].map(([u, v]) => {
+            const p = [0, 0, 0];
+            p[axis] = sign;
+            p[other[0]] = ranges[other[0]][u];
+            p[other[1]] = ranges[other[1]][v];
+            return new Vector3(...p);
+        });
+        return { normal, vertices };
+    }
+
+    /**
+     * Adds a face, edge or corner preset from its signed-axis vector and clickable surfaces.
+     * @private
+     * @static
+     * @param {ViewCubeRegion[]} regions - Destination region collection.
+     * @param {number[]} axis - Signed direction components.
+     * @param {Array<{normal:Vector3,vertices:Vector3[]}>} surfaces - Surfaces sharing that direction.
+     * @returns {void}
+     */
+    static #addRegion(regions, axis, surfaces) {
+        const direction = new Vector3(...axis).normalize();
+        regions.push({ id: axis.join(","), direction, surfaces, kind: ["", "face", "edge", "corner"][axis.filter(Boolean).length] });
+    }
+
+    /**
+     * Finds the semantic cube-region id under the event target.
+     * @private
+     * @static
+     * @param {PointerEvent|MouseEvent} event - Overlay input event.
+     * @returns {string|null}
+     */
+    static #getRegionAt(event) {
+        return event.target?.closest?.("polygon[data-region]")?.dataset.region ?? null;
+    }
+
+    /**
+     * Interpolates an orthographic extent from its start or fallback using the current eased transition.
+     * @private
+     * @static
+     * @param {number|null} start - Initial extent.
+     * @param {number} end - Destination extent.
+     * @param {number} fallback - Initial extent when absent.
+     * @param {number} eased - Eased transition fraction from 0 to 1.
+     * @returns {number}
+     */
+    static #interpolateExtent(start, end, fallback, eased) {
+        return (start ?? fallback) + (end - (start ?? fallback)) * eased;
+    }
+
+    /**
+     * Projects a cube-space vertex into the overlay SVG using the effective camera projection.
+     * @private
+     * @static
+     * @param {Vector3} vertex - Cube-space vertex.
+     * @param {ViewCubeProjection} projection - Current virtual cube projection.
+     * @returns {{x:number,y:number}}
+     */
+    static #projectVertex(vertex, projection) {
+        const { view, perspective, depthSign, eyeDistance } = projection;
+        const point = Vector3.TransformNormal(vertex, view);
+        const scale = perspective ? eyeDistance / (eyeDistance + point.z * depthSign) : 1;
+        return { x: 60 + point.x * 31 * scale, y: 60 - point.y * 31 * scale };
+    }
+
+    /**
+     * Updates surface visibility and projected polygon points for the current camera orientation.
+     * @private
+     * @static
+     * @param {object} surface - Surface containing its normal, vertices and SVG polygon.
+     * @param {ViewCubeProjection} projection - Current virtual cube projection.
+     * @returns {{shown:boolean,points:Array<{x:number,y:number}>}}
+     */
+    static #drawSurface(surface, projection) {
+        const { view, perspective, depthSign, eyeDistance } = projection;
+        const normal = Vector3.TransformNormal(surface.normal, view);
+        const shown = perspective ? -normal.z * depthSign * eyeDistance > 1.001 : normal.z * depthSign < -0.001;
+        surface.polygon.style.display = shown ? "" : "none";
+        const points = surface.vertices.map((vertex) => BabylonJSViewCubeSVGController.#projectVertex(vertex, projection));
+        surface.polygon.setAttribute("points", points.map((p) => `${p.x},${p.y}`).join(" "));
+        return { shown, points };
+    }
+
+    /**
+     * Converts a quaternion into a new rotation matrix without changing the quaternion.
+     * @private
+     * @param {Quaternion} q - Camera orientation.
+     * @returns {Matrix} Rotation matrix.
+     */
+    #rotationMatrix(q) {
+        const matrix = Matrix.Identity();
+        q.toRotationMatrix(matrix);
+        return matrix;
+    }
+
+    /**
+     * Identifies the ArcRotateCamera adapter by its Babylon class name.
+     * @private
+     * @param {ViewCubeCamera|null|undefined} camera - Camera to inspect.
+     * @returns {boolean} Whether the camera uses orbital controls.
+     */
+    #isOrbit(camera) {
+        return camera?.getClassName?.() === "ArcRotateCamera";
+    }
+
+    /**
+     * Reads the effective world-space camera pose and current orthographic extents.
+     * Transforms orbit targets through the parent; other cameras use the remembered distance or one unit.
+     * @private
+     * @param {ViewCubeCamera} camera - Camera whose view matrix will be refreshed.
+     * @returns {ViewCubePose} Snapshot used for synchronization and transition interpolation.
+     */
+    #readPose(camera) {
+        const world = camera.getViewMatrix(true).clone().invert();
+        const position = Vector3.Zero();
+        const rotation = Quaternion.Identity();
+        world.decompose(undefined, rotation, position);
+        const orbitTarget = this.#isOrbit(camera) ? camera.getTarget().clone() : null;
+        const target = orbitTarget ? (camera.parent ? Vector3.TransformCoordinates(orbitTarget, camera.parent.getWorldMatrix()) : orbitTarget) : position.add(camera.getForwardRay().direction.scale(this.#cameraDistances.get(camera) ?? 1));
+        return { position, rotation, target, distance: Math.max(Vector3.Distance(position, target), 0.0001), left: camera.orthoLeft, right: camera.orthoRight, bottom: camera.orthoBottom, top: camera.orthoTop };
+    }
+
+    /**
+     * Clears orbital, translational and rotational inertia plus pending surface-focused wheel motion before explicit cube navigation.
+     * @private
+     * @param {ViewCubeCamera} camera - Camera whose pending movement is cleared.
+     * @returns {void}
+     */
+    #clearInertia(camera) {
+        BabylonJSCameraWheelMotion.cancel(camera);
+        for (const key of ["inertialAlphaOffset", "inertialBetaOffset", "inertialRadiusOffset", "inertialPanningX", "inertialPanningY"]) {
+            if (key in camera) {
+                camera[key] = 0;
+            }
+        }
+        camera.cameraDirection?.setAll(0);
+        camera.cameraRotation?.setAll(0);
+    }
+
+    /**
+     * Applies a world-space position and target while retaining world +Y as camera up.
+     * Converts parented poses to local coordinates, clears inertia and adjusts clipping/navigation limits.
+     * Reads ViewCube radius factors from BabylonJSController.config.camera.
+     * Free/Universal cameras use target/Euler rotation to prevent quaternion-driven up-vector changes.
+     * The transition caller checks camera identity and lock before invoking this method.
+     * @private
+     * @param {ViewCubeCamera} camera - Camera receiving the accepted navigation pose.
+     * @param {Vector3} position - Interpolated world-space position.
+     * @param {Vector3} target - Interpolated world-space model target.
+     * @param {number} distance - Interpolated camera-to-target distance.
+     * @param {ViewCubeFit} fit - Destination bounds/framing used to adjust clipping.
+     * @returns {void}
+     */
+    #writePose(camera, position, target, distance, fit) {
+        const parentWorld = camera.parent?.getWorldMatrix?.();
+        const parentInverse = parentWorld?.clone().invert();
+        const localPosition = parentInverse ? Vector3.TransformCoordinates(position, parentInverse) : position;
+        const upWorld = Vector3.Up();
+        camera.upVector = parentInverse ? Vector3.TransformNormal(upWorld, parentInverse).normalize() : upWorld;
+        this.#clearInertia(camera);
+        if (this.#isOrbit(camera)) {
+            // Cube selection explicitly overrides incompatible orbit constraints on this camera only.
+            camera.lowerAlphaLimit = null;
+            camera.upperAlphaLimit = null;
+            camera.lowerBetaLimit = null;
+            camera.upperBetaLimit = null;
+            camera.allowUpsideDown = false;
+            camera.lowerRadiusLimit = Math.min(distance * BabylonJSController.config.camera.minRadiusFactor, camera.lowerRadiusLimit ?? Infinity);
+            camera.upperRadiusLimit = Math.max(distance * BabylonJSController.config.camera.maxRadiusFactor, camera.upperRadiusLimit ?? 0);
+            camera.setTarget(parentInverse ? Vector3.TransformCoordinates(target, parentInverse) : target);
+            camera.setPosition(localPosition);
+        } else {
+            camera.position.copyFrom(localPosition);
+            // Quaternion changes make TargetCamera rotate its upVector. Its target/Euler API keeps roll zero.
+            camera.rotationQuaternion = null;
+            camera.updateUpVectorFromRotation = false;
+            camera.setTarget(parentInverse ? Vector3.TransformCoordinates(target, parentInverse) : target);
+            // Flush Babylon's initial roll cache before restoring the fixed world-up vector.
+            camera.getViewMatrix(true);
+            camera.upVector = parentInverse ? Vector3.TransformNormal(upWorld, parentInverse).normalize() : upWorld;
+            this.#cameraDistances.set(camera, distance);
+        }
+        camera.minZ = Math.min(camera.minZ > 0 ? camera.minZ : Infinity, Math.max(fit.radius * 0.001, 0.00001));
+        camera.maxZ = Math.max(camera.maxZ, distance + fit.radius * 2);
+    }
+
+    /**
+     * Publishes measured cube viewport height and scene height when either changes.
+     * Disabled cubes report zero height; resolved CSS height is used when the SVG has no layout measurement.
+     * @private
+     * @returns {void}
+     */
+    #publishLayout() {
+        if (this.#disposed) {
+            return;
+        }
+        const viewportHeight = this.#svg.getBoundingClientRect().height
+            || parseFloat(this.#root.ownerDocument.defaultView?.getComputedStyle(this.#root).height) || 0;
+        const cubeHeight = this.#enabled ? viewportHeight : 0;
+        const sceneHeight = this.#host.getViewport().height;
+        const key = `${cubeHeight},${sceneHeight}`;
+        if (key === this.#layoutKey) {
+            return;
+        }
+        this.#layoutKey = key;
+        this.#host.onLayout?.(cubeHeight, sceneHeight);
+    }
+
+    /**
+     * Registers an overlay or canvas listener and retains its removal callback for disposal.
+     * @private
+     * @param {EventTarget} element - Event source.
+     * @param {string} name - DOM event name.
+     * @param {EventListener} handler - Handler to register.
+     * @returns {void}
+     */
+    #addListener(element, name, handler) {
+        element.addEventListener(name, handler);
+        this.#listeners.push(() => element.removeEventListener(name, handler));
+    }
+
+    /**
+     * Updates hover feedback for every surface and the outline of one region.
+     * @private
+     * @param {string|null} key - Cube region id whose hover feedback is updated.
+     * @param {boolean} active - Whether hover feedback is active.
+     * @returns {void}
+     */
+    #setRegionHover(key, active) {
+        const node = this.#nodes.get(key);
+        if (!node) {
+            return;
+        }
+        for (const surface of node.surfaces) {
+            surface.polygon.toggleAttribute("data-hover", active);
+        }
+        node.outline.toggleAttribute("data-hover", active);
+    }
+
+    /**
+     * Updates only the old/new region feedback attributes without rebuilding geometry.
+     * Clears hover when disabled or locked; all surfaces of an edge or corner share the same state.
+     * @private
+     * @param {string|null} id - Signed-axis region identifier, or null to remove hover.
+     * @returns {void}
+     */
+    #setHover(id) {
+        if (!this.#enabled || this.#host.isLocked(this.#host.getCamera())) {
+            id = null;
+        }
+        if (id === this.#hover) {
+            return;
+        }
+
+        this.#setRegionHover(this.#hover, false);
+        this.#hover = id;
+        this.#setRegionHover(id, true);
+    }
+
+    /**
+     * Reports whether an accepted navigation transition is pending.
+     * @public
+     * @returns {boolean} Whether the owning renderer should continue advancing the transition.
+     */
+    get isAnimating() {
+        return this.#transition !== null;
+    }
+
+    /**
+     * Returns the overlay root for host integration or inspection.
+     * @public
+     * @returns {HTMLDivElement} Root element containing styles and the SVG.
+     */
+    get element() {
+        return this.#root;
+    }
+
+    /**
+     * Changes cube visibility without reloading assets or replacing the camera.
+     * Disabling cancels navigation and clears hover; either state refreshes dimensions and synchronization.
+     * @public
+     * @param {boolean} enabled - Whether the cube should be visible and interactive when unlocked.
+     * @returns {void}
+     */
+    setEnabled(enabled) {
+        if (this.#disposed) {
+            return;
+        }
+        this.#enabled = Boolean(enabled);
+        this.#root.hidden = !this.#enabled;
+        if (!this.#enabled) {
+            this.cancel();
+            this.#pointer = null;
+            this.#setHover(null);
+        }
+        this.resize();
+        this.sync();
+    }
+
+    /**
+     * Constrains the CSS-sized square widget to the viewport without overriding its stylesheet dimensions.
+     * CSS owns the requested size and density defaults; only the shared maximum dimension is written inline.
+     * Cancels obsolete navigation and synchronizes the indicator without changing the camera pose.
+     * @public
+     * @returns {void}
+     */
+    resize() {
+        if (this.#disposed) {
+            return;
+        }
+        this.cancel();
+        const viewport = this.#host.getViewport();
+        const size = Math.max(0, Math.min(viewport.width, viewport.height));
+        this.#root.style.maxWidth = `${size}px`;
+        this.#root.style.maxHeight = `${size}px`;
+        this.#publishLayout();
+        this.sync();
+    }
+
+    /**
+     * Stops the pending transition, captured drag and temporary touch feedback without reverting camera changes.
+     * @public
+     * @returns {void}
+     */
+    cancel() {
+        this.#transition = null;
+        this.#finishDrag();
+    }
+
+    /**
+     * Ends any captured drag and starts or retargets smooth navigation using fresh model-only framing.
+     * Rejects disabled/disposed, locked, unsupported or unusable inputs without starting navigation.
+     * An accepted action clears inertia and asks the owning renderer to advance the transition.
+     * @public
+     * @param {string} id - Signed-axis preset identifier, for example "0,0,1" for Interior.
+     * @param {number} [now=performance.now()] - Start timestamp in milliseconds on the performance clock.
+     * @returns {boolean} Whether navigation was accepted.
+     */
+    select(id, now = performance.now()) {
+        const camera = this.#host.getCamera();
+        const region = this.#regions.find((r) => r.id === id);
+        if (this.#disposed || !this.#enabled || !region || this.#host.isLocked(camera) || !BabylonJSCameraFraming.isCameraSupported(camera)) {
+            return false;
+        }
+        const fit = BabylonJSCameraFraming.calculateCameraFit(camera, this.#host.getBounds(), region.direction, this.#host.getViewport());
+        if (!fit) {
+            return false;
+        }
+        this.#finishDrag();
+        this.#clearInertia(camera);
+        this.#transition = { camera, mode: camera.mode, start: this.#readPose(camera), fit, at: now };
+        this.#host.requestRender();
+        return true;
+    }
+
+    /**
+     * Advances an accepted transition with smooth easing and preserved projection mode.
+     * Uses BabylonJSController.config.camera.transitionDuration as the duration in milliseconds.
+     * Rechecks active-camera identity, lock and projection before each write; invalidated transitions stop.
+     * The owning render loop calls this method; it does not start an independent animation loop.
+     * @public
+     * @param {number} [now=performance.now()] - Current timestamp in milliseconds on the performance clock.
+     * @returns {void}
+     */
+    tick(now = performance.now()) {
+        const t = this.#transition;
+        if (!t) {
+            return;
+        }
+        if (this.#host.getCamera() !== t.camera || this.#host.isLocked(t.camera) || t.camera.mode !== t.mode) {
+            this.cancel();
+            return;
+        }
+        const p = Math.max(0, Math.min(1, (now - t.at) / BabylonJSController.config.camera.transitionDuration));
+        const eased = p * p * (3 - 2 * p);
+        const rotation = Quaternion.Slerp(t.start.rotation, t.fit.rotation, eased);
+        const target = Vector3.Lerp(t.start.target, t.fit.target, eased);
+        const distance = t.start.distance + (t.fit.distance - t.start.distance) * eased;
+        const forward = Vector3.TransformNormal(new Vector3(0, 0, t.camera.getScene().useRightHandedSystem ? -1 : 1), this.#rotationMatrix(rotation));
+        const position = target.subtract(forward.scale(distance));
+        this.#writePose(t.camera, position, target, distance, t.fit);
+        if (t.mode === 1) {
+
+            const viewport = this.#host.getViewport();
+            t.camera.orthoLeft = BabylonJSViewCubeSVGController.#interpolateExtent(t.start.left, -t.fit.halfWidth, -viewport.width / 2, eased);
+            t.camera.orthoRight = BabylonJSViewCubeSVGController.#interpolateExtent(t.start.right, t.fit.halfWidth, viewport.width / 2, eased);
+            t.camera.orthoBottom = BabylonJSViewCubeSVGController.#interpolateExtent(t.start.bottom, -t.fit.halfHeight, -viewport.height / 2, eased);
+            t.camera.orthoTop = BabylonJSViewCubeSVGController.#interpolateExtent(t.start.top, t.fit.halfHeight, viewport.height / 2, eased);
+        }
+        if (p === 1) {
+            this.cancel();
+        }
+    }
+
+    /**
+     * Synchronizes projection, nearest-orientation feedback, labels and lock state from the active camera.
+     * Rebinds the view-matrix observer on replacement and guards against recursive notifications.
+     * Releases a pending drag/touch highlight when camera identity, projection or full-lock state changes.
+     * Reprojects SVG geometry only for camera pose/projection changes; hover and localization reuse it.
+     * Keeps top-layer label visibility aligned with its face instead of inheriting an interaction group's visibility.
+     * The virtual cube camera follows orientation/FOV independently of the model zoom.
+     * @public
+     * @returns {void}
+     */
+    sync() {
+        if (this.#disposed || !this.#enabled || this.#syncing) {
+            return;
+        }
+        this.#syncing = true;
+        try {
+            const camera = this.#host.getCamera();
+            if (camera !== this.#camera) {
+                this.#camera?.onViewMatrixChangedObservable?.remove(this.#observer);
+                this.#camera = camera;
+                this.#geometryKey = null;
+                this.#observer = camera?.onViewMatrixChangedObservable?.add(() => this.sync());
+            }
+            const locked = !BabylonJSCameraFraming.isCameraSupported(camera) || this.#host.isLocked(camera);
+            const gesture = this.#drag ?? this.#touchFeedback;
+            if (gesture && (gesture.camera !== camera || gesture.mode !== camera?.mode || locked)) {
+                this.#finishDrag();
+            }
+            const lockChanged = locked !== this.#locked;
+            this.#locked = locked;
+            if (lockChanged) {
+                this.#root.dataset.locked = String(locked);
+            }
+            if (locked) {
+                this.#setHover(null);
+            }
+            if (!camera?.getViewMatrix) {
+                this.#svg.style.visibility = "hidden";
+                return;
+            }
+            if (this.#svg.style.visibility !== "visible") {
+                this.#svg.style.visibility = "visible";
+            }
+            const locale = this.#host.getCulture?.();
+            const localeChanged = locale !== this.#locale || this.#geometryKey === null;
+            const geometryKey = `${camera.getViewMatrix().m.join(",")}|${camera.mode}|${camera.fov}|${camera.getScene().useRightHandedSystem}`;
+            const geometryChanged = geometryKey !== this.#geometryKey;
+            if (!geometryChanged && !localeChanged && !lockChanged) {
+                return;
+            }
+            this.#geometryKey = geometryKey;
+            this.#locale = locale;
+            const pose = this.#readPose(camera);
+            const view = this.#rotationMatrix(pose.rotation).invert();
+            const rightHanded = camera.getScene().useRightHandedSystem;
+            const depthSign = rightHanded ? -1 : 1;
+            const perspective = camera.mode !== 1;
+            const fov = Number.isFinite(camera.fov) && camera.fov > 0 && camera.fov < Math.PI ? camera.fov : 0.8;
+            // An isolated virtual eye follows the scene camera's orientation/FOV, not its model zoom.
+            const eyeDistance = 1.8 + 1.8 / Math.tan(fov / 2);
+            const projection = { view, perspective, depthSign, eyeDistance };
+            if (geometryChanged) {
+                for (const surface of this.#shell) {
+                    BabylonJSViewCubeSVGController.#drawSurface(surface, projection);
+                }
+            }
+            const towardObserver = Vector3.TransformNormal(new Vector3(0, 0, -depthSign), this.#rotationMatrix(pose.rotation)).normalize();
+            const nearest = this.#regions.reduce((best, r) => (Vector3.Dot(r.direction, towardObserver) > Vector3.Dot(best.direction, towardObserver) ? r : best));
+            if (geometryChanged) {
+                this.#root.dataset.projection = perspective ? "perspective" : "orthographic";
+                this.#root.dataset.currentRegion = nearest.id;
+            }
+            // Draw full faces first, then the coplanar edge prisms and corner cubes.
+            // Visibility belongs to each physical face, not the semantic preset direction.
+            if (localeChanged) {
+                this.#svg.setAttribute("aria-label", I18n.translate("prefViewer.viewCube.title", { locale }));
+            }
+            for (const r of this.#regions) {
+                const node = this.#nodes.get(r.id);
+                const parts = r.id.split(",").map(Number);
+                const names = parts
+                    .map((s, i) =>
+                        s
+                            ? I18n.translate(
+                                  `prefViewer.viewCube.${
+                                      [
+                                          ["right", "left"],
+                                          ["bottom", "top"],
+                                          ["back", "front"],
+                                      ][i][s > 0 ? 1 : 0]
+                                  }`,
+                                  { locale },
+                              )
+                            : null,
+                    )
+                    .filter(Boolean);
+                let visible = false;
+                const outlineSegments = [];
+                for (const surface of node.surfaces) {
+                    const { shown, points } = geometryChanged ? BabylonJSViewCubeSVGController.#drawSurface(surface, projection) : { shown: surface.polygon.style.display !== "none", points: [] };
+                    visible ||= shown;
+                    if (lockChanged || geometryChanged) {
+                        surface.polygon.style.pointerEvents = locked ? "none" : "visiblePainted";
+                    }
+                    if (geometryChanged) {
+                        surface.polygon.toggleAttribute("data-current", r.id === nearest.id);
+                    }
+                    if (localeChanged) {
+                        surface.polygon.setAttribute("aria-label", names.join(" / "));
+                    }
+                    if (geometryChanged && shown) {
+                        outlineSegments.push(`M${points.map((p) => `${p.x},${p.y}`).join(" L")} Z`);
+                    }
+                    if (geometryChanged && r.kind === "face") {
+                        node.label.setAttribute("x", String(points.reduce((sum, v) => sum + v.x, 0) / points.length));
+                        node.label.setAttribute("y", String(points.reduce((sum, v) => sum + v.y, 0) / points.length));
+                    }
+                }
+                if (geometryChanged) {
+                    node.group.style.display = visible ? "" : "none";
+                    if (r.kind === "face") {
+                        node.label.style.display = visible ? "" : "none";
+                    }
+                    node.outline.setAttribute("d", outlineSegments.join(" "));
+                }
+                if (localeChanged) {
+                    node.label.textContent = r.kind === "face" ? names[0] : "";
+                }
+            }
+            // Camera motion can move hit regions under a stationary mouse.
+            if (geometryChanged && this.#pointer && Number.isFinite(this.#pointer.x + this.#pointer.y)) {
+                const hit = this.#root.getRootNode().elementFromPoint?.(this.#pointer.x, this.#pointer.y);
+                if (hit) {
+                    this.#setHover(this.#root.contains(hit) ? (hit.closest?.("polygon[data-region]")?.dataset.region ?? null) : null);
+                }
+            }
+        } finally {
+            this.#syncing = false;
+        }
+    }
+
+    /**
+     * Idempotently cancels navigation and releases listeners, camera/resize observers and overlay DOM.
+     * Reports zero layout footprint without disposing the host camera, scene or model assets.
+     * @public
+     * @returns {void}
+     */
+    dispose() {
+        if (this.#disposed) {
+            return;
+        }
+        this.cancel();
+        this.#disposed = true;
+        this.#camera?.onViewMatrixChangedObservable?.remove(this.#observer);
+        this.#resizeObserver?.disconnect();
+        this.#viewportResizeObserver?.disconnect();
+        this.#listeners.forEach((remove) => remove());
+        this.#listeners.length = 0;
+        this.#root.remove();
+        this.#host.onLayout?.(0, 0);
+    }
+}