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

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

@@ -1,947 +1,86 @@
-import { Matrix, Quaternion, Vector3 } from "@babylonjs/core/Maths/math.vector.js";
-import { PrefViewerStyleVariables } 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 BabylonJSViewCubeRenderer from "./babylonjs-view-cube-renderer.js";
-import { anglesFromDirection, applyDragDelta, computeViewCubeSize, directionFromAngles } from "./view-cube-orbit-math.js";
-
-// Light PrefSketch palette tint: the "current view" colour is the primary colour mixed into the face fill.
-const CURRENT_FILL_COLOR = "#f7f3ea";
-const CURRENT_MIX = 0.25;
-// Horizontal component of the unit view direction below which the camera counts as being on a pole.
-const POLE_SNAP = 1e-6;
-const 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).
-const COLOR_REFRESH_MS = 250;
-// CSS-wide keywords and currentcolor resolve against the probe's parent, not to a colour of their own.
-const 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.
-const 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.
-const DRAG_THRESHOLD_PX = 3;
-// Orbit angle, in radians, applied per CSS pixel of drag; the PrefSketch view cube uses the same value.
-const DRAG_RADIANS_PER_PX = 0.012;
-const INERTIA_KEYS = ["inertialAlphaOffset", "inertialBetaOffset", "inertialRadiusOffset", "inertialPanningX", "inertialPanningY"];
-
-/**
- * @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
- */
+import BabylonJSViewCubeSVGController from "./babylonjs-view-cube-svg-controller.js";
+import BabylonJSViewCubeCanvasController from "./babylonjs-view-cube-canvas-controller.js";
 
 /**
- * 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<string, string>} colors - "#rrggbb" hover and current colours derived from the primary colour.
- * @property {number} devicePixelRatio - Pixel ratio of the owning window.
- * @property {function(): void} onContextRestored - Called when the renderer's own WebGL context was restored; the controller then repaints.
- */
-
-/**
- * BabylonJSViewCubeController - Owns a 3D orientation indicator and model-framing camera navigation.
- *
- * Displays 26 face/edge/corner presets with primary-color hover and nearest-view feedback.
- * The visual layer is a BabylonJSViewCubeRenderer drawing on a canvas inside the overlay root; this class
- * keeps the interaction (hover, click), the camera pose reading and the camera transitions.
- * 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.
- *
- * Members are ordered as properties, constructor, static methods, private methods and public methods.
- * @class
+ * Owns exactly one selectable ViewCube implementation for a host scene.
+ * Switching releases cube-only gestures, observers and graphics; the host camera/assets are never replaced.
+ * Canvas is the default. Disabled selection changes retain preference without constructing graphics resources.
+ * The host owns scheduling and locking; dispose this facade before disposing its host scene.
  */
 export default class BabylonJSViewCubeController {
-    #cameraDistances = new WeakMap();
     #host;
-    #root;
-    #canvas;
-    #renderer = null;
-    #regions = BabylonJSViewCubeController.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;
+    #controller = null;
+    #renderer;
+    #enabled = true;
     #disposed = false;
-    #hover = null;
-    #pointer = null;
-    #press = null;
-    #alpha = 0;
-    #dirty = false;
-    #primaryRaw = null;
-    #listeners = [];
-    #resizeObserver;
-    #viewportResizeObserver;
-    #layoutKey = null;
-    #stopPixelRatioWatch = null;
 
     /**
-     * Creates the overlay root and canvas, attaches input/resize observers and enables the cube.
-     * 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): BabylonJSViewCubeRenderer} [host.createRenderer] - Renderer factory, mainly for tests; defaults to a BabylonJSViewCubeRenderer with its own Engine.
+     * Creates the selected overlay with the existing callback-based host contract.
+     * @param {object} host - Host camera/bounds/viewport/scheduler callbacks, plus optional Canvas renderer factory.
+     * @param {"svg"|"canvas"} [renderer="canvas"] - Initial presentation; invalid values select Canvas.
      */
-    constructor(host) {
+    constructor(host, renderer = "canvas") {
         this.#host = host;
-        const doc = host.canvas.ownerDocument;
-        this.#root = doc.createElement("div");
-        this.#root.className = "pref-viewer-view-cube";
-        this.#root.style.cssText = `position:absolute;right:var(${INSET_RIGHT_VARIABLE}, 0px);top:0px;width:0px;height: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";
-        this.#root.append(this.#canvas);
-        host.canvas.parentElement.append(this.#root);
-        this.#addListener(this.#canvas, "pointermove", (event) => {
-            this.#pointer = this.#toLocal(event);
-            if (this.#press) {
-                this.#dragTo(event);
-                return;
-            }
-            this.#setHover(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.#press = { pointerId: event.pointerId, id: this.#pick(this.#toLocal(event)), startX: event.clientX, startY: event.clientY, lastX: event.clientX, lastY: event.clientY, dragging: false };
-            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.resize());
-        this.#resizeObserver?.observe(host.canvas);
-        this.#viewportResizeObserver = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => this.#publishLayout());
-        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;
-                BabylonJSViewCubeController.#addRegion(regions, axis, [
-                    BabylonJSViewCubeController.#createSurface(i, s, [
-                        [-inset, inset],
-                        [-inset, inset],
-                        [-inset, inset],
-                    ]),
-                ]);
-                regions.at(-1).outline = BabylonJSViewCubeController.#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];
-                        BabylonJSViewCubeController.#addRegion(regions, axis, [BabylonJSViewCubeController.#createSurface(i, s, ranges), BabylonJSViewCubeController.#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]);
-                    BabylonJSViewCubeController.#addRegion(regions,
-                        signs,
-                        signs.map((s, i) => BabylonJSViewCubeController.#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 || CSS_COLOR_KEYWORDS.test(text)) {
-            return null;
-        }
-        return BabylonJSViewCubeController.#toHexWithBrowser(text, probeParent) ?? BabylonJSViewCubeController.#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 BabylonJSViewCubeController.#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 BabylonJSViewCubeController.#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 BabylonJSViewCubeController.#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("")}`;
-    }
-
-    /**
-     * Mixes two "#rrggbb" colours.
-     * @private
-     * @static
-     * @param {string} base - Base colour.
-     * @param {string} tint - Colour mixed into the base.
-     * @param {number} amount - Share of the tint, from 0 to 1.
-     * @returns {string} Mixed "#rrggbb" colour.
-     */
-    static #mix(base, tint, amount) {
-        const channels = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
-        const [b, t] = [channels(base), channels(tint)];
-        return `#${b.map((c, i) => Math.round(c + (t[i] - c) * amount).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 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 * DRAG_RADIANS_PER_PX * handedness * invert;
-        const dBeta = -dy * DRAG_RADIANS_PER_PX * invert;
-        if (this.#isOrbit(camera)) {
-            const next = 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 = anglesFromDirection(pose.position.subtract(pose.target), this.#alpha);
-            if (!angles) {
-                return;
-            }
-            const direction = directionFromAngles(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) <= 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();
-    }
-
-    /**
-     * Ends the current press, if any: releases the pointer capture and, after a drag, brings hover back under the pointer.
-     * @private
-     * @returns {void}
-     */
-    #endPress() {
-        const press = this.#press;
-        if (!press) {
-            return;
-        }
-        this.#press = null;
-        try {
-            this.#canvas.releasePointerCapture?.(press.pointerId);
-        } catch (_error) {}
-        if (press.dragging && this.#pointer) {
-            this.#setHover(this.#pick(this.#pointer));
-        }
-        this.#updateCursor();
+        this.#renderer = BabylonJSViewCubeController.normalizeRenderer(renderer);
+        this.#create();
     }
 
     /**
-     * Sets the canvas cursor: none while display-only, grabbing while dragging, pointer over a region, grab otherwise.
-     * @private
-     * @returns {void}
+     * Normalizes public preferences without inferring hardware or changing other viewers.
+     * @param {unknown} value - Attribute, property or queued configuration value.
+     * @returns {"svg"|"canvas"} SVG only for the exact supported value; otherwise Canvas.
      */
-    #updateCursor() {
-        const cursor = !this.#isInteractive() ? "" : this.#press?.dragging ? "grabbing" : this.#hover ? "pointer" : "grab";
-        if (this.#canvas.style.cursor !== cursor) {
-            this.#canvas.style.cursor = cursor;
-        }
+    static normalizeRenderer(value) {
+        return value === "svg" ? "svg" : "canvas";
     }
 
-    /**
-     * Publishes measured cube viewport height and scene height when either changes.
-     * Disabled cubes report zero height; an inline-size fallback supports DOMs without layout measurements.
-     * @private
-     * @returns {void}
-     */
-    #publishLayout() {
-        if (this.#disposed) {
-            return;
-        }
-        const viewportHeight = this.#canvas.getBoundingClientRect().height || parseFloat(this.#root.style.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));
-    }
-
-    /**
-     * 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 the renderer's WebGL context was restored: marks the cube dirty and asks the host for a frame.
-     * @private
-     * @returns {void}
-     */
-    #handleContextRestored() {
-        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 or unsupported.
-     * @private
-     * @param {string|null} id - Signed-axis region identifier, or null to remove hover.
-     * @returns {void}
-     */
-    #setHover(id) {
-        if (!this.#isInteractive()) {
-            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;
-        }
+    /** @returns {Array<object>} Fresh semantic face/edge/corner definitions shared by both variants. */
+    static createViewCubeRegions() {
+        return BabylonJSViewCubeSVGController.createViewCubeRegions();
     }
 
-    /**
-     * 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 });
+    /** @private @returns {void} Creates only the enabled implementation and synchronizes its current host pose. */
+    #create() {
+        if (!this.#disposed && this.#enabled && !this.#controller) {
+            const Controller = this.#renderer === "canvas" ? BabylonJSViewCubeCanvasController : BabylonJSViewCubeSVGController;
+            this.#controller = new Controller(this.#host);
         }
-        return labels;
     }
 
-    /**
-     * Reads the primary colour from the root's computed style and derives the hover and current colours.
-     * Returns null when unchanged since the last call, when the last read is younger than COLOR_REFRESH_MS (unless
-     * forced or invalidated) or when no colour can be resolved; environments without getComputedStyle fall back to the
-     * configured style variable.
-     * @private
-     * @param {boolean} [force=false] - Reads now and returns the colours even when the source value did not change.
-     * @returns {{hover:string,current:string}|null}
-     */
-    #readColors(force = false) {
-        const now = this.#now();
-        if (!force && this.#colorsReadAt !== null && now - this.#colorsReadAt < COLOR_REFRESH_MS) {
-            return null;
-        }
-        this.#colorsReadAt = now;
-        let raw = "";
-        try {
-            raw = this.#root.ownerDocument.defaultView.getComputedStyle(this.#root).getPropertyValue(PRIMARY_COLOR_VARIABLE).trim();
-        } catch (_error) {}
-        raw ||= String(PrefViewerStyleVariables.colorPrimary ?? "").trim();
-        if (raw === this.#primaryRaw && !force) {
-            return null;
-        }
-        this.#primaryRaw = raw;
-        const hover = BabylonJSViewCubeController.#toHex(raw, this.#root) ?? BabylonJSViewCubeController.#toHex(PrefViewerStyleVariables.colorPrimary, this.#root);
-        return hover ? { hover, current: BabylonJSViewCubeController.#mix(CURRENT_FILL_COLOR, hover, CURRENT_MIX) } : null;
+    /** @returns {"svg"|"canvas"} The normalized preference, including while disabled. */
+    get renderer() {
+        return this.#renderer;
     }
 
-    /**
-     * 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;
+    /** @returns {?HTMLElement} Current overlay root, or null when no implementation is allocated. */
+    get element() {
+        return this.#controller?.element ?? null;
     }
 
-    /**
-     * 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();
+    /** @returns {boolean} Whether the active cube has a pending camera transition. */
+    get isAnimating() {
+        return this.#controller?.isAnimating === true;
     }
 
     /**
-     * Creates the renderer once a camera exists while the cube is enabled.
-     * @private
-     * @param {string} [locale] - Localization culture used for the initial labels.
-     * @returns {void}
+     * Replaces the cube without reloading or reframing the host scene.
+     * @param {"svg"|"canvas"} renderer - Requested renderer; invalid values select Canvas.
+     * @returns {void} Cancels and disposes the previous widget; repeats of the same preference are inert.
      */
-    #ensureRenderer(locale) {
-        if (this.#renderer) {
+    setRenderer(renderer) {
+        const normalized = BabylonJSViewCubeController.normalizeRenderer(renderer);
+        if (this.#disposed || normalized === this.#renderer) {
             return;
         }
-        const options = { canvas: this.#canvas, labels: this.#getLabels(locale), colors: this.#readColors(true) ?? {}, devicePixelRatio: this.#readPixelRatio(), onContextRestored: () => this.#handleContextRestored() };
-        this.#renderer = this.#host.createRenderer ? this.#host.createRenderer(options) : new BabylonJSViewCubeRenderer(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.#primaryRaw = 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;
+        this.#controller?.dispose();
+        this.#controller = null;
+        this.#renderer = normalized;
+        this.#create();
     }
 
     /**
-     * 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.
+     * Enables the selected implementation or hides it using its resource-aware lifecycle.
+     * @param {boolean} enabled - Whether presentation and interaction are enabled.
      * @returns {void}
      */
     setEnabled(enabled) {
@@ -949,223 +88,55 @@ export default class BabylonJSViewCubeController {
             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();
+        this.#create();
+        this.#controller?.setEnabled(this.#enabled);
     }
 
-    /**
-     * Sizes the square widget from the scene viewport (see computeViewCubeSize), resizes the renderer and publishes its layout.
-     * Cancels obsolete navigation and synchronizes the indicator without changing the camera pose.
-     * @public
-     * @returns {void}
-     */
+    /** @returns {void} Refreshes widget layout; defers Canvas writes outside observer delivery. */
     resize() {
-        if (this.#disposed) {
-            return;
-        }
-        this.cancel();
-        this.#colorsReadAt = null;
-        const viewport = this.#host.getViewport();
-        const size = computeViewCubeSize(viewport.width, viewport.height);
-        this.#root.style.width = `${size}px`;
-        this.#root.style.height = `${size}px`;
-        if (this.#renderer) {
-            this.#renderer.resize(this.#readPixelRatio());
-            this.#dirty = true;
+        if (this.#renderer === "canvas") {
+            this.#controller?.requestResize();
+        } else {
+            this.#controller?.resize();
         }
-        this.#publishLayout();
-        this.sync();
     }
 
-    /**
-     * Stops the pending transition at the displayed pose without reverting camera changes.
-     * @public
-     * @returns {void}
-     */
-    cancel() {
-        this.#transition = null;
+    /** @returns {void} Refreshes orientation, current region, culture and locking from the live host. */
+    sync() {
+        this.#controller?.sync();
     }
 
-    /**
-     * 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;
+    /** @returns {void} Cancels the selected implementation's pending navigation. */
+    cancel() {
+        this.#controller?.cancel();
     }
 
     /**
-     * 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.
+     * Advances host-scheduled camera navigation, without owning a separate render loop.
+     * @param {number} [now=performance.now()] - Host animation timestamp in milliseconds.
      * @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 = BabylonJSViewCubeController.#interpolateExtent(t.start.left, -t.fit.halfWidth, -viewport.width / 2, eased);
-            t.camera.orthoRight = BabylonJSViewCubeController.#interpolateExtent(t.start.right, t.fit.halfWidth, viewport.width / 2, eased);
-            t.camera.orthoBottom = BabylonJSViewCubeController.#interpolateExtent(t.start.bottom, -t.fit.halfHeight, -viewport.height / 2, eased);
-            t.camera.orthoTop = BabylonJSViewCubeController.#interpolateExtent(t.start.top, t.fit.halfHeight, viewport.height / 2, eased);
-        }
-        if (p === 1) {
-            this.cancel();
-        }
+        this.#controller?.tick(now);
     }
 
     /**
-     * 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, and hover changes ask the host for a frame.
-     * @public
-     * @returns {void}
+     * Requests the same semantic face/edge/corner navigation from either implementation.
+     * @param {string} id - Comma-separated signed axis direction.
+     * @param {number} [now=performance.now()] - Transition start timestamp in milliseconds.
+     * @returns {boolean} Whether the live unlocked implementation accepted navigation.
      */
-    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) < POLE_SNAP ? { x: 0, y: towardObserver.y, z: 0 } : towardObserver;
-                const angles = 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.
-                if (this.#pointer) {
-                    this.#setHover(this.#pick(this.#pointer));
-                }
-            }
-            this.#renderDirty();
-        } finally {
-            this.#syncing = false;
-        }
+    select(id, now = performance.now()) {
+        return this.#controller?.select(id, now) ?? false;
     }
 
-    /**
-     * Idempotently cancels navigation and releases listeners, camera/resize observers, the renderer and overlay DOM.
-     * Reports zero layout footprint without disposing the host camera, scene or model assets.
-     * @public
-     * @returns {void}
-     */
+    /** @returns {void} Idempotently releases the selected overlay and all its owned resources. */
     dispose() {
         if (this.#disposed) {
             return;
         }
-        this.cancel();
         this.#disposed = true;
-        this.#camera?.onViewMatrixChangedObservable?.remove(this.#observer);
-        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);
+        this.#controller?.dispose();
+        this.#controller = null;
     }
 }