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

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

@@ -0,0 +1,1287 @@
+import { Matrix, Quaternion, Vector3 } from "@babylonjs/core/Maths/math.vector.js";
+import { PrefViewerStyleVariables, PrefViewerViewCubePalette, PrefViewerViewCubeTypography, PrefViewerViewCubeSizingStyles, PrefViewerViewCubeCursorStyles } 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";
+import BabylonJSViewCubeCanvasRenderer from "./babylonjs-view-cube-canvas-renderer.js";
+import BabylonJSViewCubeCanvasOrbitMath from "./babylonjs-view-cube-canvas-orbit-math.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.
+ */
+
+/**
+ * Options handed to the renderer factory.
+ * @typedef {Object} ViewCubeRendererOptions
+ * @property {HTMLCanvasElement} canvas - Cube canvas inside the overlay root.
+ * @property {Object<string, string>} labels - Translated face labels keyed right, left, bottom, top, back, front.
+ * @property {object} colors - Shared resolved hex palette and numeric hover/current opacities.
+ * @property {number} devicePixelRatio - Pixel ratio of the owning window.
+ * @property {function(): void} [onReady] - Requests a repaint after initial shader/texture readiness.
+ * @property {function(): void} onContextRestored - Called when the renderer's own WebGL context was restored; the controller then repaints.
+ */
+
+/**
+ * BabylonJSViewCubeCanvasController - Owns a 3D orientation indicator and model-framing camera navigation.
+ *
+ * Displays 26 face/edge/corner presets with the shared SVG palette, primary-color hover and nearest-view feedback.
+ * Owns shared palette, typography and cursor stylesheets inside its overlay root; disposal releases them with the root.
+ * The visual layer is a BabylonJSViewCubeCanvasRenderer drawing on a canvas inside the overlay root; this class
+ * keeps the interaction (hover, click), the camera pose reading and the camera transitions.
+ * Touch hover lasts only during a stationary press; dragging and release retain only nearest-view feedback.
+ * Synchronizes camera orientation while locked, unsupported and XR cameras remain display-only.
+ * Accepted clicks preserve projection, fit only model bounds and retain world +Y as camera up.
+ *
+ * The host owns the camera, scene, assets and render loop. It calls tick() to advance transitions
+ * and sync() to refresh the indicator; sync() renders the cube, so the cube has no render loop of its own.
+ * The renderer owns a separate Engine and Scene, created lazily once a camera exists and disposed when the cube
+ * is disabled or disposed. dispose() releases the overlay, its listeners/observers and the renderer.
+ *
+ * Interaction thresholds, theme tokens and navigation constants are private static class members.
+ * Members are ordered as properties, constructor, static methods, private methods and public methods.
+ * @class
+ */
+export default class BabylonJSViewCubeCanvasController {
+    // Horizontal component of the unit view direction below which the camera counts as being on a pole.
+    static #POLE_SNAP = 1e-6;
+    static #PRIMARY_COLOR_VARIABLE = "--pref-viewer-color-primary";
+    // The app can change the primary colour at runtime without notifying the cube, so it is polled; reading the computed
+    // style forces a style recalculation, hence at most one read per interval (creation, culture change, resize and
+    // setEnabled(true) always read).
+    static #COLOR_REFRESH_MS = 250;
+    // CSS-wide keywords and currentcolor resolve against the probe's parent, not to a colour of their own.
+    static #CSS_COLOR_KEYWORDS = /^(?:inherit|initial|unset|revert|revert-layer|currentcolor)$/i;
+    // Host-settable CSS custom property (set on any ancestor of the viewer; it inherits through the shadow boundary)
+    // that insets the cube from the right edge of its container. Unset, the cube stays pinned at right:0px.
+    static #INSET_RIGHT_VARIABLE = "--pref-viewer-view-cube-inset-right";
+    // Pointer travel, in CSS pixels, beyond which a press on the cube stops being a click and becomes a drag.
+    static #DRAG_THRESHOLD_PX = 3;
+    // Orbit angle, in radians, applied per CSS pixel of drag; the PrefSketch view cube uses the same value.
+    static #DRAG_RADIANS_PER_PX = 0.012;
+    static #INERTIA_KEYS = ["inertialAlphaOffset", "inertialBetaOffset", "inertialRadiusOffset", "inertialPanningX", "inertialPanningY"];
+
+    #cameraDistances = new WeakMap();
+    #host;
+    #root;
+    #canvas;
+    #renderer = null;
+    #regions = BabylonJSViewCubeCanvasController.createViewCubeRegions();
+    // View matrix, projection mode and handedness the cube was last posed for; null forces a new pose.
+    #geometryKey = null;
+    #colorsReadAt = null;
+    #locale;
+    #locked;
+    #enabled = false;
+    #transition = null;
+    #camera = null;
+    #observer = null;
+    #syncing = false;
+    #disposed = false;
+    #hover = null;
+    #pointer = null;
+    #press = null;
+    #alpha = 0;
+    #dirty = false;
+    #paletteRaw = null;
+    #listeners = [];
+    #paletteStyleObserver;
+    #resizeObserver;
+    #viewportResizeObserver;
+    #resizeFrame = null;
+    #layoutKey = null;
+    #stopPixelRatioWatch = null;
+
+    /**
+     * Creates the overlay root, shared palette/typography/cursor stylesheet and canvas, attaches input/resize and inherited-style observers and enables the cube.
+     * Mouse hover follows the pointer; touch highlights the pressed region until drag, release or cancellation.
+     * 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(Object=): void} host.requestRender - Requests rendering through the host scheduler after accepted navigation; `{ interaction: true }` marks a pointer drag step, for which the host keeps rendering continuously as it does for its own canvas drags.
+     * @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 viewport height and scene viewport height, in CSS pixels; zero cube height clears the menu offset, and disposal reports (0, 0).
+     * @param {function(ViewCubeRendererOptions): BabylonJSViewCubeCanvasRenderer} [host.createRenderer] - Renderer factory, mainly for tests; defaults to a BabylonJSViewCubeCanvasRenderer with its own Engine.
+     */
+    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 = "canvas";
+        this.#root.style.cssText = `position:absolute;right:var(${BabylonJSViewCubeCanvasController.#INSET_RIGHT_VARIABLE}, 0px);top:0px;z-index:900;pointer-events:none`;
+        this.#canvas = doc.createElement("canvas");
+        this.#canvas.setAttribute("role", "img");
+        // The canvas is the only pointer-active part; the layout wrapper never intercepts scene input.
+        // The renderer keeps Babylon's input manager detached from this canvas, so nothing else focuses it or moves the
+        // cursor. The ring, selection and tap highlight are still suppressed as a harmless extra guard: the cube is pointer-driven.
+        this.#canvas.style.cssText = "display:block;width:100%;height:100%;touch-action:none;pointer-events:auto;outline:none;-webkit-tap-highlight-color:transparent;user-select:none;-webkit-user-select:none";
+        const paletteStyle = doc.createElement("style");
+        paletteStyle.textContent = PrefViewerViewCubePalette.styles + PrefViewerViewCubeTypography.styles + PrefViewerViewCubeSizingStyles + PrefViewerViewCubeCursorStyles;
+        this.#root.append(paletteStyle, this.#canvas);
+        host.canvas.parentElement.append(this.#root);
+        if (doc.defaultView?.MutationObserver) {
+            this.#paletteStyleObserver = new doc.defaultView.MutationObserver(this.#onPaletteStyleChange);
+            let ancestor = this.#root.parentElement;
+            while (ancestor) {
+                this.#paletteStyleObserver.observe(ancestor, { attributes: true, attributeFilter: ["style", "class"] });
+                ancestor = ancestor.parentElement ?? ancestor.getRootNode()?.host;
+            }
+        }
+        this.#addListener(this.#canvas, "pointermove", (event) => {
+            const touch = event.pointerType === "touch";
+            this.#pointer = touch && !this.#press ? null : this.#toLocal(event);
+            if (this.#press) {
+                this.#dragTo(event);
+                return;
+            }
+            this.#setHover(touch ? null : this.#pick(this.#pointer));
+        });
+        this.#addListener(this.#canvas, "pointerleave", () => {
+            this.#pointer = null;
+            this.#endPress();
+            this.#setHover(null);
+        });
+        this.#addListener(this.#canvas, "pointerdown", (event) => {
+            if (!this.#isInteractive()) {
+                return;
+            }
+            // The whole canvas is a drag surface, transparent corners included: the main camera never starts from it.
+            event.stopPropagation();
+            if (event.button !== 0 || event.isPrimary === false || (this.#press && this.#press.pointerId !== event.pointerId)) {
+                return;
+            }
+            this.#endPress();
+            this.#pointer = this.#toLocal(event);
+            this.#press = { pointerType: event.pointerType, pointerId: event.pointerId, id: this.#pick(this.#pointer), startX: event.clientX, startY: event.clientY, lastX: event.clientX, lastY: event.clientY, dragging: false };
+            this.#setHover(this.#press.id);
+            try {
+                this.#canvas.setPointerCapture?.(event.pointerId);
+            } catch (_error) {}
+        });
+        this.#addListener(this.#canvas, "pointerup", (event) => {
+            const press = this.#press;
+            if (!press || press.pointerId !== event.pointerId) {
+                return;
+            }
+            this.#endPress();
+            if (!press.dragging && press.id && event.button === 0 && this.#pick(this.#toLocal(event)) === press.id) {
+                this.select(press.id);
+            }
+        });
+        for (const name of ["pointercancel", "lostpointercapture"]) {
+            this.#addListener(this.#canvas, name, (event) => {
+                if (this.#press?.pointerId === event.pointerId) {
+                    this.#endPress();
+                }
+            });
+        }
+        for (const event of ["pointerdown", "wheel", "keydown"]) {
+            this.#addListener(host.canvas, event, () => this.cancel());
+        }
+        this.#resizeObserver = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => this.requestResize());
+        this.#resizeObserver?.observe(host.canvas);
+        this.#viewportResizeObserver = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => this.requestResize());
+        this.#viewportResizeObserver?.observe(this.#canvas);
+        this.#watchPixelRatio();
+        this.setEnabled(true);
+    }
+
+    /**
+     * 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;
+                BabylonJSViewCubeCanvasController.#addRegion(regions, axis, [
+                    BabylonJSViewCubeCanvasController.#createSurface(i, s, [
+                        [-inset, inset],
+                        [-inset, inset],
+                        [-inset, inset],
+                    ]),
+                ]);
+                regions.at(-1).outline = BabylonJSViewCubeCanvasController.#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];
+                        BabylonJSViewCubeCanvasController.#addRegion(regions, axis, [BabylonJSViewCubeCanvasController.#createSurface(i, s, ranges), BabylonJSViewCubeCanvasController.#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]);
+                    BabylonJSViewCubeCanvasController.#addRegion(regions,
+                        signs,
+                        signs.map((s, i) => BabylonJSViewCubeCanvasController.#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] });
+    }
+
+    /**
+     * 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;
+    }
+
+    /**
+     * Converts any CSS colour into lowercase "#rrggbb". The browser's own parser does the work when available: the value
+     * is assigned to a probe element's style (an invalid value leaves it empty) and the computed `color`, always
+     * "rgb()" or "rgba()", is converted. Environments without usable computed styles use a small pure-JS parser
+     * (hex 3/4/6/8 digits, rgb()/rgba() with numbers or percentages, hsl()/hsla()); named colours need the browser.
+     * Alpha is ignored and nothing is premultiplied: the colour is used as an opaque tint.
+     * @private
+     * @param {string} value - CSS colour text.
+     * @param {Element} [probeParent] - Element the probe is attached to while its computed colour is read.
+     * @returns {string|null} Hex colour, or null when the text is not a colour.
+     */
+    static #toHex(value, probeParent) {
+        const text = String(value ?? "").trim();
+        if (!text || BabylonJSViewCubeCanvasController.#CSS_COLOR_KEYWORDS.test(text)) {
+            return null;
+        }
+        return BabylonJSViewCubeCanvasController.#toHexWithBrowser(text, probeParent) ?? BabylonJSViewCubeCanvasController.#toHexWithoutBrowser(text);
+    }
+
+    /**
+     * Normalises a colour through the browser. Returns null when the browser is unavailable or cannot resolve it,
+     * so the caller can try the pure-JS parser.
+     * @private
+     * @static
+     * @param {string} text - Trimmed CSS colour text.
+     * @param {Element} [parent] - Element that hosts the probe while its computed colour is read.
+     * @returns {string|null}
+     */
+    static #toHexWithBrowser(text, parent) {
+        const view = parent?.ownerDocument?.defaultView;
+        if (!view?.getComputedStyle) {
+            return null;
+        }
+        const probe = parent.ownerDocument.createElement("span");
+        try {
+            probe.style.color = text;
+            if (!probe.style.color) {
+                return null;
+            }
+            parent.appendChild(probe);
+            return BabylonJSViewCubeCanvasController.#toHexWithoutBrowser(String(view.getComputedStyle(probe).color ?? "").trim());
+        } catch (_error) {
+            return null;
+        } finally {
+            probe.remove?.();
+        }
+    }
+
+    /**
+     * Pure-JS colour parser used when the browser cannot normalise a value.
+     * @private
+     * @static
+     * @param {string} value - Trimmed CSS colour text.
+     * @returns {string|null}
+     */
+    static #toHexWithoutBrowser(value) {
+        const text = value.toLowerCase();
+        const hex = /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/.exec(text)?.[1];
+        if (hex) {
+            const full = hex.length <= 4 ? [...hex].map((c) => c + c).join("") : hex;
+            return `#${full.slice(0, 6)}`;
+        }
+        const channel = "(\\d*\\.?\\d+)(%?)";
+        const rgb = new RegExp(`^rgba?\\(\\s*${channel}[\\s,]+${channel}[\\s,]+${channel}\\s*(?:[,/][^)]*)?\\)$`).exec(text);
+        if (rgb) {
+            const channels = [1, 3, 5].map((i) => (rgb[i + 1] ? Number(rgb[i]) * 2.55 : Number(rgb[i])));
+            return BabylonJSViewCubeCanvasController.#formatHex(channels);
+        }
+        const hsl = /^hsla?\(\s*(-?\d*\.?\d+)(?:deg)?[\s,]+(\d*\.?\d+)%[\s,]+(\d*\.?\d+)%\s*(?:[,/][^)]*)?\)$/.exec(text);
+        if (hsl) {
+            const hue = ((Number(hsl[1]) % 360) + 360) % 360;
+            const s = Math.min(1, Number(hsl[2]) / 100);
+            const l = Math.min(1, Number(hsl[3]) / 100);
+            const a = s * Math.min(l, 1 - l);
+            const f = (n) => l - a * Math.max(-1, Math.min((n + hue / 30) % 12 - 3, 9 - ((n + hue / 30) % 12), 1));
+            return BabylonJSViewCubeCanvasController.#formatHex([f(0) * 255, f(8) * 255, f(4) * 255]);
+        }
+        return null;
+    }
+
+    /**
+     * Formats 0-255 channels as "#rrggbb", rounding and clamping each one.
+     * @private
+     * @static
+     * @param {number[]} channels - Red, green and blue.
+     * @returns {string}
+     */
+    static #formatHex(channels) {
+        return `#${channels.map((c) => Math.max(0, Math.min(255, Math.round(c))).toString(16).padStart(2, "0")).join("")}`;
+    }
+
+    /**
+     * 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 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 BabylonJSViewCubeCanvasController.#INERTIA_KEYS) {
+            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; drag rotation omits it and keeps the clipping planes.
+     * @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);
+        }
+        if (fit) {
+            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);
+        }
+    }
+
+    /**
+     * Applies a drag increment to the host camera so the model follows the pointer.
+     *
+     * Sign convention, verified against the main-canvas input of Babylon: ArcRotateCameraPointersInput accumulates
+     * -offsetX and -offsetY, and ArcRotateCamera adds them to alpha (times -1 in right-handed scenes or mirrored
+     * parents, and times -1 with invertRotation) and to beta (times -1 with invertRotation). The same factors are
+     * applied here, so dragging the cube and dragging the main canvas rotate the model identically.
+     * ArcRotateCameras write alpha/beta directly with beta kept away from the poles; other cameras orbit their
+     * current target at the same distance, with the same angles, through the shared pose writer.
+     * @private
+     * @param {ViewCubeCamera} camera - Active host camera.
+     * @param {number} dx - Horizontal pointer travel in CSS pixels, positive to the right.
+     * @param {number} dy - Vertical pointer travel in CSS pixels, positive downwards.
+     * @returns {void}
+     */
+    #rotateCamera(camera, dx, dy) {
+        const invert = camera.invertRotation ? -1 : 1;
+        let handedness = camera.getScene().useRightHandedSystem ? -1 : 1;
+        if (camera.parent?.getWorldMatrix?.().determinant() < 0) {
+            handedness *= -1;
+        }
+        const dAlpha = -dx * BabylonJSViewCubeCanvasController.#DRAG_RADIANS_PER_PX * handedness * invert;
+        const dBeta = -dy * BabylonJSViewCubeCanvasController.#DRAG_RADIANS_PER_PX * invert;
+        if (this.#isOrbit(camera)) {
+            const next = BabylonJSViewCubeCanvasOrbitMath.applyDragDelta({ alpha: camera.alpha, beta: camera.beta }, dAlpha, dBeta);
+            this.#clearInertia(camera);
+            camera.alpha = next.alpha;
+            camera.beta = next.beta;
+        } else {
+            const pose = this.#readPose(camera);
+            const angles = BabylonJSViewCubeCanvasOrbitMath.anglesFromDirection(pose.position.subtract(pose.target), this.#alpha);
+            if (!angles) {
+                return;
+            }
+            const direction = BabylonJSViewCubeCanvasOrbitMath.directionFromAngles(BabylonJSViewCubeCanvasOrbitMath.applyDragDelta(angles, dAlpha, dBeta));
+            this.#writePose(camera, pose.target.add(new Vector3(direction.x, direction.y, direction.z).scale(pose.distance)), pose.target, pose.distance);
+        }
+        // A drag is pointer interaction: the host keeps its loop continuous for its interaction window, as it does for a
+        // main-canvas drag. A plain one-frame request would let its idle throttle pace the drag (seen at ~8 fps).
+        this.#host.requestRender({ interaction: true });
+    }
+
+    /**
+     * Follows a move of the pressed pointer: crossing the threshold turns the press into a drag, which cancels any
+     * running click transition and clears hover; every later move rotates by the delta since the previous one.
+     * @private
+     * @param {PointerEvent} event - Move event on the cube canvas.
+     * @returns {void}
+     */
+    #dragTo(event) {
+        const press = this.#press;
+        if (event.pointerId !== press.pointerId) {
+            return;
+        }
+        const camera = this.#host.getCamera();
+        if (!this.#isInteractive()) {
+            this.#endPress();
+            return;
+        }
+        if (!press.dragging) {
+            if (Math.hypot(event.clientX - press.startX, event.clientY - press.startY) <= BabylonJSViewCubeCanvasController.#DRAG_THRESHOLD_PX) {
+                return;
+            }
+            press.dragging = true;
+            this.cancel();
+            this.#setHover(null);
+        }
+        const dx = event.clientX - press.lastX;
+        const dy = event.clientY - press.lastY;
+        press.lastX = event.clientX;
+        press.lastY = event.clientY;
+        if (dx !== 0 || dy !== 0) {
+            this.#rotateCamera(camera, dx, dy);
+        }
+        this.#updateCursor();
+    }
+
+    /**
+     * Releases the current pointer capture after dropping press ownership to prevent lost-capture recursion.
+     * Touch clears hover and its cached point so camera synchronization cannot recreate sticky hover.
+     * Mouse/pen drag completion restores hover under the last pointer position; active-view feedback is independent.
+     * @private
+     * @returns {void}
+     */
+    #endPress() {
+        const press = this.#press;
+        if (!press) {
+            return;
+        }
+        this.#press = null;
+        try {
+            this.#canvas.releasePointerCapture?.(press.pointerId);
+        } catch (_error) {}
+        if (press.pointerType === "touch") {
+            this.#pointer = null;
+            this.#setHover(null);
+        } else if (press.dragging && this.#pointer) {
+            this.#setHover(this.#pick(this.#pointer));
+        }
+        this.#updateCursor();
+    }
+
+    /**
+     * Sets the canvas cursor: inherited while display-only, the shared rotation cursor while dragging, pointer over a region, default otherwise.
+     * @private
+     * @returns {void}
+     */
+    #updateCursor() {
+        const cursor = !this.#isInteractive() ? "" : this.#press?.dragging ? "var(--cube-rotation-cursor)" : this.#hover ? "pointer" : "default";
+        if (this.#canvas.style.cursor !== cursor) {
+            this.#canvas.style.cursor = cursor;
+        }
+    }
+
+    /**
+     * Publishes measured cube viewport height and scene height when either changes.
+     * Disabled cubes report zero height; computed CSS height is used if measurable canvas height is unavailable.
+     * Environments without layout or computed styles report zero until a real measurement becomes available.
+     * @private
+     * @returns {void}
+     */
+    #publishLayout() {
+        if (this.#disposed) {
+            return;
+        }
+        let viewportHeight = this.#canvas.getBoundingClientRect().height;
+        if (!viewportHeight) {
+            try {
+                viewportHeight = parseFloat(this.#root.ownerDocument.defaultView?.getComputedStyle(this.#root).height) || 0;
+            } catch (_error) {
+                viewportHeight = 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));
+    }
+
+    /**
+     * Reports whether the cube accepts pointer interaction: enabled, supported camera and not locked.
+     * @private
+     * @returns {boolean}
+     */
+    #isInteractive() {
+        const camera = this.#host.getCamera();
+        return this.#enabled && !this.#disposed && Boolean(this.#renderer) && BabylonJSCameraFraming.isCameraSupported(camera) && !this.#host.isLocked(camera);
+    }
+
+    /**
+     * Reads the current device pixel ratio of the owning window; browser zoom or a move to another monitor changes it.
+     * @private
+     * @returns {number} Positive ratio, 1 when unknown.
+     */
+    #readPixelRatio() {
+        const ratio = this.#root.ownerDocument.defaultView?.devicePixelRatio;
+        return ratio > 0 ? ratio : 1;
+    }
+
+    /**
+     * Listens for the next change of the device pixel ratio with a `(resolution: <ratio>dppx)` media query. The query
+     * only matches the ratio it was built with, so each change re-reads the ratio, resizes and arms a fresh query.
+     * Does nothing without matchMedia. Replaces any listener armed before.
+     * @private
+     * @returns {void}
+     */
+    #watchPixelRatio() {
+        this.#stopPixelRatioWatch?.();
+        this.#stopPixelRatioWatch = null;
+        const view = this.#root.ownerDocument.defaultView;
+        if (this.#disposed || typeof view?.matchMedia !== "function") {
+            return;
+        }
+        const list = view.matchMedia(`(resolution: ${this.#readPixelRatio()}dppx)`);
+        const onChange = () => {
+            this.#watchPixelRatio();
+            this.resize();
+        };
+        if (typeof list.addEventListener === "function") {
+            list.addEventListener("change", onChange);
+            this.#stopPixelRatioWatch = () => list.removeEventListener("change", onChange);
+        } else if (typeof list.addListener === "function") {
+            list.addListener(onChange);
+            this.#stopPixelRatioWatch = () => list.removeListener(onChange);
+        }
+    }
+
+    /**
+     * Repaints after initial GPU readiness or WebGL context restoration, waking an idle host with a dirty cube.
+     * @private
+     * @returns {void}
+     */
+    #handleRendererReady() {
+        if (this.#disposed || !this.#renderer) {
+            return;
+        }
+        this.#dirty = true;
+        this.#host.requestRender();
+    }
+
+    /**
+     * Converts pointer client coordinates into CSS pixels from the cube canvas top-left.
+     * @private
+     * @param {PointerEvent|MouseEvent} event - Canvas input event.
+     * @returns {{x:number,y:number}}
+     */
+    #toLocal(event) {
+        const rect = this.#canvas.getBoundingClientRect();
+        return { x: event.clientX - (rect.left ?? 0), y: event.clientY - (rect.top ?? 0) };
+    }
+
+    /**
+     * Resolves the region under a canvas point; null while the cube is display-only.
+     * @private
+     * @param {{x:number,y:number}} point - Canvas-local CSS pixel position.
+     * @returns {string|null}
+     */
+    #pick(point) {
+        return this.#isInteractive() && Number.isFinite(point.x + point.y) ? this.#renderer.pick(point.x, point.y) : null;
+    }
+
+    /**
+     * Forwards hover to the renderer and repaints the cube right away, since hover changes outside the host loop.
+     * The cube has its own engine and scene, so the host's model scene is not re-rendered (no host.requestRender()).
+     * During sync() the cube is rendered once at its end instead. Clears hover when disabled, locked, unsupported or dragging.
+     * @private
+     * @param {string|null} id - Signed-axis region identifier, or null to remove hover.
+     * @returns {void}
+     */
+    #setHover(id) {
+        if (!this.#isInteractive() || this.#press?.dragging) {
+            id = null;
+        }
+        if (id === this.#hover) {
+            return;
+        }
+        this.#hover = id;
+        this.#updateCursor();
+        this.#renderer?.setHover(id);
+        this.#dirty = true;
+        if (!this.#syncing) {
+            this.#renderDirty();
+        }
+    }
+
+    /**
+     * Renders the cube when something visible changed. A renderer that skipped the frame (zero-size canvas) returns
+     * false: the cube stays dirty so a later size change or sync repaints.
+     * @private
+     * @returns {void}
+     */
+    #renderDirty() {
+        if (this.#enabled && this.#renderer && this.#dirty) {
+            this.#dirty = this.#renderer.render() === false;
+        }
+    }
+
+    /**
+     * Builds the translated face labels in the renderer's key order.
+     * @private
+     * @param {string} [locale] - Localization culture.
+     * @returns {Object<string, string>}
+     */
+    #getLabels(locale) {
+        const labels = {};
+        for (const key of ["right", "left", "bottom", "top", "back", "front"]) {
+            labels[key] = I18n.translate(`prefViewer.viewCube.${key}`, { locale });
+        }
+        return labels;
+    }
+
+    /**
+     * Refreshes inherited palette overrides when ancestor styles change, including while the host render loop is idle.
+     * Observes attributes only, excludes the cube's own resize/cursor writes and releases all subscriptions on disposal.
+     * @private
+     * @returns {void} Repaints only the cube; no host model frame or timer is required.
+     */
+    #onPaletteStyleChange = () => {
+        if (this.#disposed) {
+            return;
+        }
+        this.#colorsReadAt = null;
+        this.sync();
+    };
+
+    /**
+     * Resolves the shared SVG label typography with an invisible temporary probe, including CSS variables and relative units.
+     * The probe is removed immediately; missing browser values fall back to the shared defaults.
+     * @private
+     * @returns {object} Font family, size and spacing in SVG units, weight and text transformation.
+     */
+    #readLabelStyle() {
+        const defaults = PrefViewerViewCubeTypography.defaults;
+        const probe = this.#root.ownerDocument.createElement("span");
+        probe.className = "pref-viewer-view-cube-label-style";
+        this.#root.appendChild(probe);
+        try {
+            const style = this.#root.ownerDocument.defaultView.getComputedStyle(probe);
+            const size = parseFloat(style.fontSize);
+            const spacing = parseFloat(style.letterSpacing);
+            return {
+                fontFamily: style.fontFamily || defaults.fontFamily,
+                fontSize: size > 0 ? size : defaults.fontSize,
+                fontWeight: style.fontWeight || defaults.fontWeight,
+                letterSpacing: Number.isFinite(spacing) ? spacing : defaults.letterSpacing,
+                textTransform: style.textTransform || defaults.textTransform
+            };
+        } catch (_error) {
+            return defaults;
+        } finally {
+            probe.remove();
+        }
+    }
+
+    /**
+     * Reads the shared SVG/Canvas palette and label typography from computed CSS, with immutable style defaults as fallback.
+     * Polling is throttled to COLOR_REFRESH_MS and unchanged raw inputs avoid color probes and repaints.
+     * Missing/unresolvable CSS values retain defaults; edge/corner colors use their dedicated Canvas gray.
+     * @private
+     * @param {boolean} [force=false] - Resolves now even when raw CSS inputs are unchanged.
+     * @returns {object|null} Resolved hex colors and numeric highlight opacities, or null when unchanged/throttled.
+     */
+    #readColors(force = false) {
+        const now = this.#now();
+        if (!force && this.#colorsReadAt !== null && now - this.#colorsReadAt < BabylonJSViewCubeCanvasController.#COLOR_REFRESH_MS) {
+            return null;
+        }
+        this.#colorsReadAt = now;
+        const defaults = PrefViewerViewCubePalette.colors;
+        let style;
+        try {
+            style = this.#root.ownerDocument.defaultView.getComputedStyle(this.#root);
+        } catch (_error) {}
+        /** @param {string} name - CSS custom property. @returns {string} Trimmed value, or empty when unavailable. */
+        const read = name => style?.getPropertyValue(name)?.trim() ?? "";
+        const primary = read(BabylonJSViewCubeCanvasController.#PRIMARY_COLOR_VARIABLE) || String(PrefViewerStyleVariables.colorPrimary);
+        const raw = {
+            fill: read("--pref-viewer-view-cube-fill-color") || read("--cube-fill-color"), border: read("--pref-viewer-view-cube-border-color") || read("--cube-border-color"), text: read("--pref-viewer-view-cube-text-color") || read("--cube-text-color"),
+            edge: read("--pref-viewer-view-cube-edge-color") || read("--cube-edge-color"), corner: read("--pref-viewer-view-cube-corner-color") || read("--cube-corner-color"),
+            hover: read("--pref-viewer-view-cube-hover-color") || read("--cube-hover-color"), current: read("--pref-viewer-view-cube-active-color") || read("--cube-active-color"),
+            hoverOpacity: read("--pref-viewer-view-cube-hover-opacity") || read("--cube-hover-opacity"), currentOpacity: read("--pref-viewer-view-cube-active-opacity") || read("--cube-active-opacity")
+        };
+        const labelStyle = this.#readLabelStyle();
+        const key = JSON.stringify([primary, raw, defaults, labelStyle]);
+        if (key === this.#paletteRaw && !force) {
+            return null;
+        }
+        this.#paletteRaw = key;
+        this.#renderer?.setLabelStyle?.(labelStyle);
+        /** @param {string} value - CSS color. @param {string} fallback - Known usable hex color. @returns {string} Resolved opaque hex color. */
+        const color = (value, fallback) => BabylonJSViewCubeCanvasController.#toHex(value, this.#root) ?? fallback;
+        const border = color(raw.border, defaults.border);
+        const tint = color(primary, defaults.hover);
+        /** @param {string} value - CSS opacity. @param {number} fallback - Default opacity. @returns {number} Opacity clamped to 0..1. */
+        const opacity = (value, fallback) => value && Number.isFinite(Number(value)) ? Math.min(1, Math.max(0, Number(value))) : fallback;
+        return {
+            fill: color(raw.fill, defaults.fill), border, text: color(raw.text, defaults.text),
+            edge: color(raw.edge, defaults.edge), corner: color(raw.corner, defaults.corner),
+            hover: color(raw.hover, tint), current: color(raw.current, tint),
+            hoverOpacity: opacity(raw.hoverOpacity, defaults.hoverOpacity), currentOpacity: opacity(raw.currentOpacity, defaults.currentOpacity)
+        };
+    }
+
+    /**
+     * Compares the pose inputs with the last ones the cube was posed for and remembers them.
+     * @private
+     * @param {ArrayLike<number>} matrix - Camera view matrix elements.
+     * @param {number} mode - Camera projection mode.
+     * @param {boolean} rightHanded - Whether the scene is right-handed.
+     * @param {number} fov - Camera vertical field of view in radians.
+     * @returns {boolean} Whether anything differs from the previous call.
+     */
+    #updateGeometryKey(matrix, mode, rightHanded, fov) {
+        const key = this.#geometryKey;
+        if (key && key.mode === mode && key.rightHanded === rightHanded && key.fov === fov && key.matrix.every((value, i) => value === matrix[i])) {
+            return false;
+        }
+        this.#geometryKey = { matrix: Array.from(matrix), mode, rightHanded, fov };
+        return true;
+    }
+
+    /**
+     * Current time in milliseconds: the host clock when it provides one, otherwise the performance clock.
+     * @private
+     * @returns {number}
+     */
+    #now() {
+        return this.#host.now?.() ?? performance.now();
+    }
+
+    /**
+     * Creates the renderer with resolved CSS typography once a camera exists while enabled, subscribing to GPU readiness and context restoration.
+     * @private
+     * @param {string} [locale] - Localization culture used for the initial labels.
+     * @returns {void}
+     */
+    #ensureRenderer(locale) {
+        if (this.#renderer) {
+            return;
+        }
+        const options = {
+            canvas: this.#canvas,
+            labels: this.#getLabels(locale),
+            colors: this.#readColors(true) ?? {},
+            labelStyle: this.#readLabelStyle(),
+            devicePixelRatio: this.#readPixelRatio(),
+            onContextRestored: () => this.#handleRendererReady(),
+            onReady: () => this.#handleRendererReady()
+        };
+        this.#renderer = this.#host.createRenderer ? this.#host.createRenderer(options) : new BabylonJSViewCubeCanvasRenderer(options);
+        this.#renderer.resize(this.#readPixelRatio());
+        this.#applyLocale(locale);
+        this.#geometryKey = null;
+        this.#dirty = true;
+    }
+
+    /**
+     * Remembers the culture and localizes the canvas accessible name.
+     * @private
+     * @param {string} [locale] - Localization culture.
+     * @returns {void}
+     */
+    #applyLocale(locale) {
+        this.#locale = locale;
+        this.#canvas.setAttribute("aria-label", I18n.translate("prefViewer.viewCube.title", { locale }));
+    }
+
+    /**
+     * Disposes the renderer and forgets everything derived from it.
+     * @private
+     * @returns {void}
+     */
+    #disposeRenderer() {
+        this.#endPress();
+        this.#renderer?.dispose();
+        this.#renderer = null;
+        this.#hover = null;
+        this.#paletteRaw = null;
+        this.#colorsReadAt = null;
+        this.#geometryKey = null;
+        this.#canvas.style.cursor = "";
+    }
+
+    /**
+     * 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 the cube canvas.
+     */
+    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.#colorsReadAt = null;
+        this.#root.hidden = !this.#enabled;
+        if (!this.#enabled) {
+            this.cancel();
+            this.#pointer = null;
+            this.#setHover(null);
+            this.#disposeRenderer();
+        }
+        this.resize();
+        this.sync();
+    }
+
+    /**
+     * Constrains the shared CSS-sized square to the available viewport, resizes graphics and publishes layout.
+     * SVG and Canvas use the same presentation-density dimensions; CSS owns width and height.
+     * Cancels obsolete navigation and synchronizes the indicator without changing the camera pose.
+     * @public
+     * @returns {void}
+     */
+    resize() {
+        if (this.#disposed) {
+            return;
+        }
+        this.cancel();
+        this.#colorsReadAt = null;
+        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`;
+        if (this.#renderer) {
+            this.#renderer.resize(this.#readPixelRatio());
+            this.#dirty = true;
+        }
+        this.#publishLayout();
+        this.sync();
+    }
+
+    /**
+     * Coalesces observer/presentation resize requests into the owning window's next animation frame.
+     * Keeps canvas/root writes outside ResizeObserver delivery and ignores queued work after disposal.
+     * @returns {void} Environments without animation frames resize synchronously.
+     */
+    requestResize() {
+        if (this.#disposed || this.#resizeFrame !== null) {
+            return;
+        }
+        const view = this.#canvas.ownerDocument.defaultView;
+        if (!view?.requestAnimationFrame) {
+            this.resize();
+            return;
+        }
+        this.#resizeFrame = view.requestAnimationFrame(() => {
+            this.#resizeFrame = null;
+            if (!this.#disposed) {
+                this.resize();
+            }
+        });
+    }
+
+    /**
+     * Stops the pending transition at the displayed pose without reverting camera changes.
+     * @public
+     * @returns {void}
+     */
+    cancel() {
+        this.#transition = null;
+    }
+
+    /**
+     * Starts or retargets smooth navigation to a region 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.#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 = BabylonJSViewCubeCanvasController.#interpolateExtent(t.start.left, -t.fit.halfWidth, -viewport.width / 2, eased);
+            t.camera.orthoRight = BabylonJSViewCubeCanvasController.#interpolateExtent(t.start.right, t.fit.halfWidth, viewport.width / 2, eased);
+            t.camera.orthoBottom = BabylonJSViewCubeCanvasController.#interpolateExtent(t.start.bottom, -t.fit.halfHeight, -viewport.height / 2, eased);
+            t.camera.orthoTop = BabylonJSViewCubeCanvasController.#interpolateExtent(t.start.top, t.fit.halfHeight, viewport.height / 2, eased);
+        }
+        if (p === 1) {
+            this.cancel();
+        }
+    }
+
+    /**
+     * Synchronizes the 3D cube with the active camera: pose, nearest orientation, labels, colours and lock state.
+     * Rebinds the view-matrix observer on replacement and guards against recursive notifications.
+     * Creates the renderer lazily once a camera exists. The cube orientation follows the camera direction only,
+     * independent of model zoom and projection. Locked, unsupported and XR cameras keep the cube following the
+     * camera but make it display-only. Renders only when something visible changed; it is called by the host
+     * render loop after the scene renders. Hover picking stays suspended throughout a drag, while camera
+     * orientation and current-region highlighting continue to update. Hover changes repaint only the cube.
+     * @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 lockChanged = locked !== this.#locked;
+            this.#locked = locked;
+            if (lockChanged) {
+                this.#root.dataset.locked = String(locked);
+                this.#canvas.style.pointerEvents = locked ? "none" : "auto";
+                this.#endPress();
+                this.#dirty = true;
+            }
+            if (locked) {
+                this.#setHover(null);
+            }
+            this.#updateCursor();
+            if (!camera?.getViewMatrix) {
+                this.#canvas.style.visibility = "hidden";
+                return;
+            }
+            if (this.#canvas.style.visibility !== "visible") {
+                this.#canvas.style.visibility = "visible";
+            }
+            const locale = this.#host.getCulture?.();
+            this.#ensureRenderer(locale);
+            this.#updateCursor();
+            const renderer = this.#renderer;
+            if (locale !== this.#locale) {
+                this.#applyLocale(locale);
+                renderer.setLabels(this.#getLabels(locale));
+                this.#colorsReadAt = null;
+                this.#dirty = true;
+            }
+            const colors = this.#readColors();
+            if (colors) {
+                renderer.setColors(colors);
+                this.#dirty = true;
+            }
+            const rightHanded = camera.getScene().useRightHandedSystem;
+            if (this.#updateGeometryKey(camera.getViewMatrix().m, camera.mode, rightHanded, camera.fov)) {
+                const pose = this.#readPose(camera);
+                const rotation = this.#rotationMatrix(pose.rotation);
+                const towardObserver = Vector3.TransformNormal(new Vector3(0, 0, rightHanded ? 1 : -1), rotation).normalize();
+                // At the poles alpha is undefined and the horizontal part is numerical noise: snap it to
+                // zero so the previous alpha is kept instead of spinning the cube arbitrarily.
+                const horizontal = Math.hypot(towardObserver.x, towardObserver.z) < BabylonJSViewCubeCanvasController.#POLE_SNAP ? { x: 0, y: towardObserver.y, z: 0 } : towardObserver;
+                const angles = BabylonJSViewCubeCanvasOrbitMath.anglesFromDirection(horizontal, this.#alpha);
+                if (angles) {
+                    this.#alpha = angles.alpha;
+                    renderer.setPose({ ...angles, mode: camera.mode, fov: camera.fov });
+                }
+                const nearest = this.#regions.reduce((best, r) => (Vector3.Dot(r.direction, towardObserver) > Vector3.Dot(best.direction, towardObserver) ? r : best));
+                renderer.setCurrent(nearest.id);
+                this.#root.dataset.projection = camera.mode === 1 ? "orthographic" : "perspective";
+                this.#root.dataset.currentRegion = nearest.id;
+                this.#dirty = true;
+                // Camera motion can move hit regions under a stationary pointer outside a drag.
+                if (this.#pointer && !this.#press?.dragging) {
+                    this.#setHover(this.#pick(this.#pointer));
+                }
+            }
+            this.#renderDirty();
+        } finally {
+            this.#syncing = false;
+        }
+    }
+
+    /**
+     * Idempotently cancels navigation and releases listeners, camera/resize/style observers, the renderer, pending resize frame 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;
+        if (this.#resizeFrame !== null) {
+            this.#canvas.ownerDocument.defaultView?.cancelAnimationFrame?.(this.#resizeFrame);
+            this.#resizeFrame = null;
+        }
+        this.#camera?.onViewMatrixChangedObservable?.remove(this.#observer);
+        this.#paletteStyleObserver?.disconnect();
+        this.#resizeObserver?.disconnect();
+        this.#viewportResizeObserver?.disconnect();
+        this.#stopPixelRatioWatch?.();
+        this.#stopPixelRatioWatch = null;
+        this.#listeners.forEach((remove) => remove());
+        this.#listeners.length = 0;
+        this.#disposeRenderer();
+        this.#root.remove();
+        this.#host.onLayout?.(0, 0);
+    }
+}