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

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

@@ -1,8 +1,32 @@
 import { Matrix, Quaternion, Vector3 } from "@babylonjs/core/Maths/math.vector.js";
-import { PrefViewerViewCubeStyles } from "./styles.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
@@ -47,39 +71,42 @@ import BabylonJSCameraFraming from "./babylonjs-camera-framing.js";
  */
 
 /**
- * Virtual camera inputs used to project cube surfaces into SVG.
- * @typedef {Object} ViewCubeProjection
- * @property {Matrix} view - Cube-local to virtual camera rotation matrix.
- * @property {boolean} perspective - Whether to apply perspective scaling.
- * @property {number} depthSign - Scene handedness depth direction.
- * @property {number} eyeDistance - Virtual camera distance independent of model zoom.
+ * 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 an SVG orientation indicator and model-framing camera navigation.
+ * 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.
- * Synchronizes camera projection and orientation while locked cameras remain display-only.
+ * 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. The cube requests rendering but allocates no Engine,
- * Scene or asset meshes. dispose() releases only the overlay and its listeners/observers.
+ * 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
  */
 export default class BabylonJSViewCubeController {
-    static #SVG_NS = "http://www.w3.org/2000/svg";
-
     #cameraDistances = new WeakMap();
     #host;
     #root;
-    #svg;
+    #canvas;
+    #renderer = null;
     #regions = BabylonJSViewCubeController.createViewCubeRegions();
-    #nodes = new Map();
-    #shell = [];
+    // 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;
@@ -90,13 +117,18 @@ export default class BabylonJSViewCubeController {
     #disposed = false;
     #hover = null;
     #pointer = null;
+    #press = null;
+    #alpha = 0;
+    #dirty = false;
+    #primaryRaw = null;
     #listeners = [];
     #resizeObserver;
     #viewportResizeObserver;
     #layoutKey = null;
+    #stopPixelRatioWatch = null;
 
     /**
-     * Creates the SVG overlay, attaches input/resize observers and enables the cube.
+     * 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.
      *
@@ -109,80 +141,76 @@ export default class BabylonJSViewCubeController {
      * @param {function(): {width: number, height: number}} host.getViewport - Returns the current scene viewport dimensions in CSS pixels.
      * @param {function(): void} host.requestRender - Requests rendering through the host scheduler after accepted navigation.
      * @param {function(): string} [host.getCulture] - Returns the current localization culture; omitted callbacks use the translator's default culture.
-     * @param {function(number, number): void} [host.onLayout] - Receives the measured cube SVG viewport height and scene viewport height, in CSS pixels; zero cube height clears the menu offset, and disposal reports (0, 0).
+     * @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.
      */
     constructor(host) {
         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:0px;top:0px;width:100px;height:100px;z-index:900;pointer-events:none";
-        const style = doc.createElement("style");
-        style.textContent = PrefViewerViewCubeStyles;
-        this.#root.append(style);
-        this.#svg = doc.createElementNS(BabylonJSViewCubeController.#SVG_NS, "svg");
-        this.#svg.setAttribute("viewBox", "0 0 120 120");
-        this.#svg.setAttribute("role", "group");
-        this.#root.append(this.#svg);
-        for (const region of this.#regions.filter((r) => r.kind === "face")) {
-            const polygon = doc.createElementNS(BabylonJSViewCubeController.#SVG_NS, "polygon");
-            polygon.setAttribute("class", "cube-shell");
-            this.#svg.append(polygon);
-            this.#shell.push({ ...region.outline, polygon });
-        }
-        for (const region of this.#regions) {
-            const group = doc.createElementNS(BabylonJSViewCubeController.#SVG_NS, "g");
-            const surfaces = region.surfaces.map((surface) => {
-                const polygon = doc.createElementNS(BabylonJSViewCubeController.#SVG_NS, "polygon");
-                polygon.dataset.region = region.id;
-                polygon.dataset.kind = region.kind;
-                group.append(polygon);
-                return { ...surface, polygon };
-            });
-            const label = doc.createElementNS(BabylonJSViewCubeController.#SVG_NS, "text");
-            if (region.kind === "face") {
-                group.append(label);
-            }
-            this.#svg.append(group);
-            const outline = doc.createElementNS(BabylonJSViewCubeController.#SVG_NS, "path");
-            outline.setAttribute("class", "hover-outline");
-            this.#nodes.set(region.id, { group, surfaces, label, outline });
-        }
-        // Stroke every clickable boundary above all filled regions, including interior face boundaries.
-        for (const node of this.#nodes.values()) {
-            this.#svg.append(node.outline);
-        }
+        this.#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.#svg, "pointermove", (event) => {
-            this.#pointer = { x: event.clientX, y: event.clientY };
-            this.#setHover(BabylonJSViewCubeController.#getRegionAt(event));
+        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.#svg, "pointerleave", () => {
+        this.#addListener(this.#canvas, "pointerleave", () => {
             this.#pointer = null;
+            this.#endPress();
             this.#setHover(null);
         });
-        this.#addListener(this.#svg, "pointerdown", (event) => {
-            if (BabylonJSViewCubeController.#getRegionAt(event)) {
-                event.stopPropagation();
+        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.#svg, "click", (event) => {
-            const id = BabylonJSViewCubeController.#getRegionAt(event);
-            if (!id) {
+        this.#addListener(this.#canvas, "pointerup", (event) => {
+            const press = this.#press;
+            if (!press || press.pointerId !== event.pointerId) {
                 return;
             }
-            event.stopPropagation();
-            if (event.button === 0) {
-                this.select(id);
+            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.#svg);
+        this.#viewportResizeObserver?.observe(this.#canvas);
+        this.#watchPixelRatio();
         this.setEnabled(true);
     }
 
@@ -291,17 +319,6 @@ export default class BabylonJSViewCubeController {
         regions.push({ id: axis.join(","), direction, surfaces, kind: ["", "face", "edge", "corner"][axis.filter(Boolean).length] });
     }
 
-    /**
-     * Finds the semantic cube-region id under the event target.
-     * @private
-     * @static
-     * @param {PointerEvent|MouseEvent} event - Overlay input event.
-     * @returns {string|null}
-     */
-    static #getRegionAt(event) {
-        return event.target?.closest?.("polygon[data-region]")?.dataset.region ?? null;
-    }
-
     /**
      * Interpolates an orthographic extent from its start or fallback using the current eased transition.
      * @private
@@ -317,36 +334,109 @@ export default class BabylonJSViewCubeController {
     }
 
     /**
-     * Projects a cube-space vertex into the overlay SVG using the effective camera projection.
+     * 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 {Vector3} vertex - Cube-space vertex.
-     * @param {ViewCubeProjection} projection - Current virtual cube projection.
-     * @returns {{x:number,y:number}}
+     * @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 #projectVertex(vertex, projection) {
-        const { view, perspective, depthSign, eyeDistance } = projection;
-        const point = Vector3.TransformNormal(vertex, view);
-        const scale = perspective ? eyeDistance / (eyeDistance + point.z * depthSign) : 1;
-        return { x: 60 + point.x * 31 * scale, y: 60 - point.y * 31 * scale };
+    static #formatHex(channels) {
+        return `#${channels.map((c) => Math.max(0, Math.min(255, Math.round(c))).toString(16).padStart(2, "0")).join("")}`;
     }
 
     /**
-     * Updates surface visibility and projected polygon points for the current camera orientation.
+     * Mixes two "#rrggbb" colours.
      * @private
      * @static
-     * @param {object} surface - Surface containing its normal, vertices and SVG polygon.
-     * @param {ViewCubeProjection} projection - Current virtual cube projection.
-     * @returns {{shown:boolean,points:Array<{x:number,y:number}>}}
+     * @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 #drawSurface(surface, projection) {
-        const { view, perspective, depthSign, eyeDistance } = projection;
-        const normal = Vector3.TransformNormal(surface.normal, view);
-        const shown = perspective ? -normal.z * depthSign * eyeDistance > 1.001 : normal.z * depthSign < -0.001;
-        surface.polygon.style.display = shown ? "" : "none";
-        const points = surface.vertices.map((vertex) => BabylonJSViewCubeController.#projectVertex(vertex, projection));
-        surface.polygon.setAttribute("points", points.map((p) => `${p.x},${p.y}`).join(" "));
-        return { shown, points };
+    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("")}`;
     }
 
     /**
@@ -395,7 +485,8 @@ export default class BabylonJSViewCubeController {
      * @returns {void}
      */
     #clearInertia(camera) {
-        for (const key of ["inertialAlphaOffset", "inertialBetaOffset", "inertialRadiusOffset", "inertialPanningX", "inertialPanningY"]) {
+        BabylonJSCameraWheelMotion.cancel(camera);
+        for (const key of INERTIA_KEYS) {
             if (key in camera) {
                 camera[key] = 0;
             }
@@ -415,7 +506,7 @@ export default class BabylonJSViewCubeController {
      * @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.
+     * @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) {
@@ -447,8 +538,117 @@ export default class BabylonJSViewCubeController {
             camera.upVector = parentInverse ? Vector3.TransformNormal(upWorld, parentInverse).normalize() : upWorld;
             this.#cameraDistances.set(camera, distance);
         }
-        camera.minZ = Math.min(camera.minZ > 0 ? camera.minZ : Infinity, Math.max(fit.radius * 0.001, 0.00001));
-        camera.maxZ = Math.max(camera.maxZ, distance + fit.radius * 2);
+        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);
+        }
+        this.#host.requestRender();
+    }
+
+    /**
+     * 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();
+    }
+
+    /**
+     * Sets the canvas cursor: none while display-only, grabbing while dragging, pointer over a region, grab otherwise.
+     * @private
+     * @returns {void}
+     */
+    #updateCursor() {
+        const cursor = !this.#isInteractive() ? "" : this.#press?.dragging ? "grabbing" : this.#hover ? "pointer" : "grab";
+        if (this.#canvas.style.cursor !== cursor) {
+            this.#canvas.style.cursor = cursor;
+        }
     }
 
     /**
@@ -461,7 +661,7 @@ export default class BabylonJSViewCubeController {
         if (this.#disposed) {
             return;
         }
-        const viewportHeight = this.#svg.getBoundingClientRect().height || parseFloat(this.#root.style.height) || 0;
+        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}`;
@@ -486,41 +686,235 @@ export default class BabylonJSViewCubeController {
     }
 
     /**
-     * Updates hover feedback for every surface and the outline of one region.
+     * 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
-     * @param {string|null} key - Cube region id whose hover feedback is updated.
-     * @param {boolean} active - Whether hover feedback is active.
      * @returns {void}
      */
-    #setRegionHover(key, active) {
-        const node = this.#nodes.get(key);
-        if (!node) {
+    #watchPixelRatio() {
+        this.#stopPixelRatioWatch?.();
+        this.#stopPixelRatioWatch = null;
+        const view = this.#root.ownerDocument.defaultView;
+        if (this.#disposed || typeof view?.matchMedia !== "function") {
             return;
         }
-        for (const surface of node.surfaces) {
-            surface.polygon.toggleAttribute("data-hover", active);
+        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;
         }
-        node.outline.toggleAttribute("data-hover", active);
+        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;
     }
 
     /**
-     * Updates only the old/new region feedback attributes without rebuilding geometry.
-     * Clears hover when disabled or locked; all surfaces of an edge or corner share the same state.
+     * 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.#enabled || this.#host.isLocked(this.#host.getCamera())) {
+        if (!this.#isInteractive()) {
             id = null;
         }
         if (id === this.#hover) {
             return;
         }
-
-        this.#setRegionHover(this.#hover, false);
         this.#hover = id;
-        this.#setRegionHover(id, true);
+        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;
+    }
+
+    /**
+     * 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;
+    }
+
+    /**
+     * 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 once a camera exists while the cube is enabled.
+     * @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) ?? {}, 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 = "";
     }
 
     /**
@@ -535,7 +929,7 @@ export default class BabylonJSViewCubeController {
     /**
      * Returns the overlay root for host integration or inspection.
      * @public
-     * @returns {HTMLDivElement} Root element containing styles and the SVG.
+     * @returns {HTMLDivElement} Root element containing the cube canvas.
      */
     get element() {
         return this.#root;
@@ -553,18 +947,20 @@ 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();
     }
 
     /**
-     * Fits the widget to a maximum of 100 x 100 CSS pixels inside the scene viewport and publishes its layout.
+     * 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}
@@ -574,10 +970,15 @@ export default class BabylonJSViewCubeController {
             return;
         }
         this.cancel();
+        this.#colorsReadAt = null;
         const viewport = this.#host.getViewport();
-        const size = Math.max(0, Math.min(100, viewport.width, viewport.height));
+        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;
+        }
         this.#publishLayout();
         this.sync();
     }
@@ -656,10 +1057,12 @@ export default class BabylonJSViewCubeController {
     }
 
     /**
-     * Synchronizes projection, nearest-orientation feedback, labels and lock state from the active camera.
+     * 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.
-     * Reprojects SVG geometry only for camera pose/projection changes; hover and localization reuse it.
-     * The virtual cube camera follows orientation/FOV independently of the model zoom.
+     * 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}
      */
@@ -681,114 +1084,67 @@ export default class BabylonJSViewCubeController {
             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.#svg.style.visibility = "hidden";
+                this.#canvas.style.visibility = "hidden";
                 return;
             }
-            if (this.#svg.style.visibility !== "visible") {
-                this.#svg.style.visibility = "visible";
+            if (this.#canvas.style.visibility !== "visible") {
+                this.#canvas.style.visibility = "visible";
             }
             const locale = this.#host.getCulture?.();
-            const localeChanged = locale !== this.#locale || this.#geometryKey === null;
-            const geometryKey = `${camera.getViewMatrix().m.join(",")}|${camera.mode}|${camera.fov}|${camera.getScene().useRightHandedSystem}`;
-            const geometryChanged = geometryKey !== this.#geometryKey;
-            if (!geometryChanged && !localeChanged && !lockChanged) {
-                return;
+            this.#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;
             }
-            this.#geometryKey = geometryKey;
-            this.#locale = locale;
-            const pose = this.#readPose(camera);
-            const view = this.#rotationMatrix(pose.rotation).invert();
             const rightHanded = camera.getScene().useRightHandedSystem;
-            const depthSign = rightHanded ? -1 : 1;
-            const perspective = camera.mode !== 1;
-            const fov = Number.isFinite(camera.fov) && camera.fov > 0 && camera.fov < Math.PI ? camera.fov : 0.8;
-            // An isolated virtual eye follows the scene camera's orientation/FOV, not its model zoom.
-            const eyeDistance = 1.8 + 1.8 / Math.tan(fov / 2);
-            const projection = { view, perspective, depthSign, eyeDistance };
-            if (geometryChanged) {
-                for (const surface of this.#shell) {
-                    BabylonJSViewCubeController.#drawSurface(surface, projection);
+            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 towardObserver = Vector3.TransformNormal(new Vector3(0, 0, -depthSign), this.#rotationMatrix(pose.rotation)).normalize();
-            const nearest = this.#regions.reduce((best, r) => (Vector3.Dot(r.direction, towardObserver) > Vector3.Dot(best.direction, towardObserver) ? r : best));
-            if (geometryChanged) {
-                this.#root.dataset.projection = perspective ? "perspective" : "orthographic";
+                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;
-            }
-            // Draw full faces first, then the coplanar edge prisms and corner cubes.
-            // Visibility belongs to each physical face, not the semantic preset direction.
-            if (localeChanged) {
-                this.#svg.setAttribute("aria-label", I18n.translate("prefViewer.viewCube.title", { locale }));
-            }
-            for (const r of this.#regions) {
-                const node = this.#nodes.get(r.id);
-                const parts = r.id.split(",").map(Number);
-                const names = parts
-                    .map((s, i) =>
-                        s
-                            ? I18n.translate(
-                                  `prefViewer.viewCube.${
-                                      [
-                                          ["right", "left"],
-                                          ["bottom", "top"],
-                                          ["back", "front"],
-                                      ][i][s > 0 ? 1 : 0]
-                                  }`,
-                                  { locale },
-                              )
-                            : null,
-                    )
-                    .filter(Boolean);
-                let visible = false;
-                const outlineSegments = [];
-                for (const surface of node.surfaces) {
-                    const { shown, points } = geometryChanged ? BabylonJSViewCubeController.#drawSurface(surface, projection) : { shown: surface.polygon.style.display !== "none", points: [] };
-                    visible ||= shown;
-                    if (lockChanged || geometryChanged) {
-                        surface.polygon.style.pointerEvents = locked ? "none" : "visiblePainted";
-                    }
-                    if (geometryChanged) {
-                        surface.polygon.toggleAttribute("data-current", r.id === nearest.id);
-                    }
-                    if (localeChanged) {
-                        surface.polygon.setAttribute("aria-label", names.join(" / "));
-                    }
-                    if (geometryChanged && shown) {
-                        outlineSegments.push(`M${points.map((p) => `${p.x},${p.y}`).join(" L")} Z`);
-                    }
-                    if (geometryChanged && r.kind === "face") {
-                        node.label.setAttribute("x", String(points.reduce((sum, v) => sum + v.x, 0) / points.length));
-                        node.label.setAttribute("y", String(points.reduce((sum, v) => sum + v.y, 0) / points.length));
-                    }
-                }
-                if (geometryChanged) {
-                    node.group.style.display = visible ? "" : "none";
-                    node.outline.setAttribute("d", outlineSegments.join(" "));
-                }
-                if (localeChanged) {
-                    node.label.textContent = r.kind === "face" ? names[0] : "";
-                }
-            }
-            // Camera motion can move hit regions under a stationary mouse.
-            if (geometryChanged && this.#pointer && Number.isFinite(this.#pointer.x + this.#pointer.y)) {
-                const hit = this.#root.getRootNode().elementFromPoint?.(this.#pointer.x, this.#pointer.y);
-                if (hit) {
-                    this.#setHover(this.#root.contains(hit) ? (hit.closest?.("polygon[data-region]")?.dataset.region ?? null) : null);
+                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;
         }
     }
 
     /**
-     * Idempotently cancels navigation and releases listeners, camera/resize observers and overlay DOM.
+     * 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}
@@ -802,8 +1158,11 @@ export default class BabylonJSViewCubeController {
         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);
     }