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

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

@@ -0,0 +1,775 @@
+// Visual design adapted from the PrefSketch view cube (PrefSketch src/viewer/view-cube.ts): a 1-unit cube with
+// 512 px labelled face cells, thin edge bars, corner spheres, a hemispheric light and the shared SVG interface palette.
+// Geometry, lighting and painting are translated to this viewer's left-handed scene and region-per-mesh picking.
+import { ArcRotateCamera, Camera, Color3, Color4, DirectionalLight, DynamicTexture, Engine, EngineStore, HemisphericLight, MeshBuilder, Quaternion, Ray, Scene, StandardMaterial, Texture, Vector3 } from "@babylonjs/core";
+import { PrefViewerViewCubePalette, PrefViewerViewCubeTypography } from "./styles.js";
+import { SSAO2RenderingPipeline } from "@babylonjs/core/PostProcesses/RenderPipeline/Pipelines/ssao2RenderingPipeline.js";
+import "@babylonjs/core/Rendering/geometryBufferRendererSceneComponent.js";
+import { FxaaPostProcess } from "@babylonjs/core/PostProcesses/fxaaPostProcess.js";
+import BabylonJSViewCubeCanvasOrbitMath from "./babylonjs-view-cube-canvas-orbit-math.js";
+
+/**
+ * Renders the 3D view cube on its own Babylon.js engine and scene, bound to a small canvas.
+ *
+ * The scene is left-handed and Y-up like the viewer scene and its ArcRotateCamera (orthographic or perspective, following
+ * the host camera) uses the host camera's alpha/beta unchanged, so no axis mirroring is needed. Every pickable mesh carries
+ * `metadata.regionId` equal to a VIEW_CUBE_DIRECTIONS id. The class owns no render loop or interaction logic.
+ * Geometry constants and picking helpers belong to this class; the default palette comes from styles.js.
+ * Surface emission is disabled for this lighting-only trial; transparent text planes retain independent unlit shading.
+ * All 26 surfaces use diffuseColor consistently; six non-pickable transparent text planes carry the shared SVG labels.
+ * Text planes are unlit for legibility, depth-tested against the cube and disposed with the owned scene.
+ * Hemispheric lighting is supplemented by a weak diffuse-only upward light for the lower surfaces.
+ * A rotation-invariant bounding sphere tightly frames every mesh with 2% padding in either projection.
+ * An optional lightweight SSAO trial shades contacts using only solid surfaces; final FXAA preserves the alpha output.
+ * SSAO and antialiasing resources stay inside this private scene and are released on disposal.
+ * The host calls render() and interprets pick() results. GPU readiness requests a host repaint even when idle.
+ * It touches neither
+ * `window` nor `document` itself, so it can be imported in any environment.
+ */
+export default class BabylonJSViewCubeCanvasRenderer {
+    static #CUBE_HALF = 0.5;
+    static #EDGE_THICKNESS = 0.09;
+    static #EDGE_LENGTH = 1 + BabylonJSViewCubeCanvasRenderer.#EDGE_THICKNESS;
+    static #CORNER_DIAMETER = 0.26;
+    static #CORNER_SEGMENTS = 8;
+    // PrefSketch light direction is (0.4, 1, 0.6) in a right-handed scene; X is mirrored for this left-handed one.
+    static #LIGHT_DIRECTION = new Vector3(-0.4, 1, 0.6);
+    static #LIGHT_INTENSITY = 1.0;
+    /** Support rays travel upward and diagonally to illuminate Bottom (-Y), Left (+X) and Outer (-Z). */
+    static #BOTTOM_LIGHT_DIRECTION = new Vector3(-0.4, 1, 0.4);
+    /** Low diffuse-only support, independent of hemispheric fill and surface emission. */
+    static #BOTTOM_LIGHT_INTENSITY = 0.16;
+    /** Reduces light specular strength by 25% to soften broad highlights, most apparent in Top. */
+    static #LIGHT_SPECULAR_COLOR = new Color3(0.75, 0.75, 0.75);
+    /** Shared neutral reflection strength for every face, edge and corner material. */
+    static #SPECULAR_COLOR = new Color3(0.5, 0.5, 0.5);
+    /** Highlight concentration for face and edge surface materials. */
+    static #SPECULAR_POWER = 64;
+    /** Lower concentration broadens the highlights specifically on corner spheres. */
+    static #CORNER_SPECULAR_POWER = 32;
+    /** Fraction of surface color emitted independently of lighting; zero for the current lighting-only trial. */
+    static #EMISSIVE_STRENGTH = 0;
+    /** Neutral lower fill restores moderate hemispheric contrast and makes the cube volume easier to read. */
+    static #LIGHT_GROUND_COLOR = new Color3(0.75, 0.75, 0.75);
+    /** Frontal SVG face width: two units projected at 31 reference pixels per unit. */
+    static #SVG_FACE_WIDTH = 62;
+    /** Small rasterization margin around the rotation-invariant geometry envelope. */
+    static #FRAME_PADDING = 1.02;
+    static #CAMERA_RADIUS = 5;
+    /** Numerical pole offset only; unlike drag limits, it must not visibly tilt top/bottom faces. */
+    static #POLE_RENDER_MARGIN = 1e-7;
+    static #DEFAULT_FOV = 0.8;
+    // Far-plane margin exceeds the full radius including the outer corner sphere surfaces.
+    static #PERSPECTIVE_DEPTH_MARGIN = 2;
+    // Distance from the cube centre to a corner sphere centre (half the cube diagonal).
+    static #CORNER_DISTANCE = Math.sqrt(3) / 2;
+    /** All faces, edge bars and corner spheres fit inside this sphere for every camera orientation. */
+    static #BOUNDING_RADIUS = BabylonJSViewCubeCanvasRenderer.#CORNER_DISTANCE + BabylonJSViewCubeCanvasRenderer.#CORNER_DIAMETER / 2;
+    /** Supersampled label texture side; typography scales proportionally to preserve its apparent size. */
+    static #TEXTURE_SIZE = 512;
+    /** Improves label definition on oblique faces; Babylon clamps this to the GPU capability. */
+    static #LABEL_ANISOTROPY = 8;
+    /** Small outward offset separates label planes from their solid parent faces without visible parallax. */
+    static #LABEL_SURFACE_OFFSET = 0.0005;
+    // Hits farther than this behind the nearest one are other sides of the cube, not overlapping parts.
+    static #PICK_DEPTH_TOLERANCE = 0.15;
+    // Screen-space pick tolerance, in CSS pixels: an edge or corner whose projected centre is this close to the pointer
+    // wins over the face under it, because the drawn edge bars (~4 px) and corner spheres (~11 px) are below the 24 px
+    // WCAG 2.2 minimum target size. It is capped at PICK_TOLERANCE_PX and shrinks with the cube (see computePickTolerance)
+    // so that the tolerance discs of the edge and corner centres never swallow the faces of a small cube.
+    static #PICK_TOLERANCE_PX = 8;
+    // 1/12 of the cube side: exactly 8 px for the 96 px minimum cube and 5 px for a 60 px one, where the face centre is
+    // only ~13 px away from the nearest edge centre.
+    static #PICK_TOLERANCE_SIDE_RATIO = 1 / 12;
+    // Minimum dot product between a region's direction and the direction towards the camera for the region to count as
+    // front-facing (about 78 degrees from the view axis). Edge-on regions on the silhouette stay out of tolerance picking.
+    static #FRONT_FACING_MIN_DOT = 0.2;
+
+
+    /**
+     * Options of the default cube Engine (as in PrefSketch, plus loseContextOnDispose). Babylon only calls
+     * WEBGL_lose_context.loseContext() on dispose when loseContextOnDispose is set; without it the cube's WebGL context
+     * would linger until garbage collection, and browsers cap the number of live contexts per page.
+     */
+    static #VIEW_CUBE_ENGINE_OPTIONS = Object.freeze({ alpha: true, antialias: true, premultipliedAlpha: false, stencil: false, loseContextOnDispose: true });
+
+    static #DEFAULT_LABELS = Object.freeze({ right: "Right", left: "Left", bottom: "Bottom", top: "Top", back: "Back", front: "Front" });
+
+    // Label key per signed axis; matches the SVG cube: +X is "left", +Y is "top", +Z is "front".
+    static #FACE_LABEL_KEYS = Object.freeze({ "1,0,0": "left", "-1,0,0": "right", "0,1,0": "top", "0,-1,0": "bottom", "0,0,1": "front", "0,0,-1": "back" });
+
+    /** Experimental SSAO is localized here so the visual trial can be switched off independently. */
+    static #SSAO_ENABLED = true;
+    static #SSAO_SETTINGS = Object.freeze({ samples: 8, ratio: 0.5, radius: 0.12, strength: 0.6 });
+
+    #ambientOcclusion;
+    #antiAliasing;
+    #canvas;
+    #engine;
+    #scene;
+    #camera;
+    #mode = Camera.ORTHOGRAPHIC_CAMERA;
+    #fov = BabylonJSViewCubeCanvasRenderer.#DEFAULT_FOV;
+    #colors;
+    #labels;
+    #devicePixelRatio;
+    #regions = new Map();
+    #state = { hover: null, current: null };
+    #labelStyle;
+    #disposed = false;
+    #contextRestoredObserver = null;
+
+    /**
+     * Creates the engine, isolated scene, optional SSAO pipeline, final FXAA pass, 26 lit surfaces and six label layers.
+     * @param {Object} options - Renderer options.
+     * @param {HTMLCanvasElement} options.canvas - Canvas the cube is drawn on; expected to be square.
+     * @param {function(HTMLCanvasElement): Engine} [options.createEngine] - Engine factory; defaults to an Engine built with VIEW_CUBE_ENGINE_OPTIONS (antialiased, alpha-enabled, releases its WebGL context on dispose). Tests inject a NullEngine.
+     * @param {Object<string, string>} [options.labels] - Face labels keyed right, left, bottom, top, back, front.
+     * @param {object} [options.colors] - Hex colors: fill, text, edge, corner, hover and current; border is used only by SVG; hoverOpacity/currentOpacity are numeric 0..1.
+     * @param {number} [options.devicePixelRatio=1] - Pixel ratio used by resize(); never read from `window`.
+     * @param {string} [options.fontFamily] - Optional font-family override for internal hosts.
+     * @param {object} [options.labelStyle] - Shared SVG typography: fontFamily, fontSize and letterSpacing in reference pixels, fontWeight and textTransform.
+     * @param {function(): void} [options.onReady] - Requests a repaint after initial shader/texture readiness; ignored after disposal.
+     * @param {function(): void} [options.onContextRestored] - Called after the cube's own WebGL context was restored; the host should repaint.
+     */
+    constructor({ canvas, createEngine, labels, colors, devicePixelRatio, fontFamily, labelStyle, onContextRestored, onReady }) {
+        this.#canvas = canvas;
+        this.#colors = { ...PrefViewerViewCubePalette.colors, ...colors };
+        this.#labels = { ...BabylonJSViewCubeCanvasRenderer.#DEFAULT_LABELS, ...labels };
+        this.#devicePixelRatio = devicePixelRatio > 0 ? devicePixelRatio : 1;
+        this.#labelStyle = { ...PrefViewerViewCubeTypography.defaults, ...labelStyle, ...(fontFamily ? { fontFamily } : {}) };
+        this.#engine = createEngine ? createEngine(canvas) : new Engine(canvas, true, { ...BabylonJSViewCubeCanvasRenderer.#VIEW_CUBE_ENGINE_OPTIONS });
+        // Second line of defence: if Babylon's input manager were ever attached, it would write engine.canvasTabIndex
+        // (default 1) to the canvas on every pointer move and make it keyboard-focusable. -1 keeps it out of the tab order.
+        this.#engine.canvasTabIndex = -1;
+        this.#contextRestoredObserver = this.#engine.onContextRestoredObservable?.add(() => {
+            if (!this.#disposed) {
+                onContextRestored?.();
+            }
+        });
+        this.#engine.setHardwareScalingLevel(1 / this.#devicePixelRatio);
+        // Babylon resolves objects created without an explicit scene or engine (textures, IBL filtering, ...) through
+        // EngineStore.LastCreatedScene and EngineStore.LastCreatedEngine (the last entry of EngineStore.Instances).
+        // The cube must stay out of both, or the main viewer would create resources on the cube's WebGL context
+        // ("object does not belong to this context"). A virtual scene never becomes LastCreatedScene, and the engine
+        // is unregistered right after creation. The host calls render() itself, so neither registry is needed.
+        this.#unregisterEngine();
+        this.#scene = new Scene(this.#engine, { virtual: true });
+        // The cube needs no Babylon input: the controller handles pointers itself and picks with an explicit ray. Even a
+        // virtual scene attaches its InputManager to the canvas when a `window` exists, which would reset the cursor on
+        // every move, call preventDefault() and focus() on press (stealing keyboard focus from the host canvas) and
+        // capture the pointer a second time. Detach it, and keep the flags as a guard in case something re-attaches it.
+        this.#scene.detachControl();
+        this.#scene.doNotHandleCursors = true;
+        this.#scene.preventDefaultOnPointerDown = false;
+        this.#scene.preventDefaultOnPointerUp = false;
+        this.#scene.clearColor = new Color4(0, 0, 0, 0);
+        this.#camera = this.#createCamera();
+        this.#createLight();
+        this.#createRegions();
+        this.#createAmbientOcclusion();
+        this.#antiAliasing = new FxaaPostProcess("view-cube-fxaa", 1, this.#camera, undefined, this.#engine);
+        if (onReady) {
+            this.#scene.executeWhenReady(() => {
+                if (!this.#disposed) {
+                    onReady();
+                }
+            });
+        }
+    }
+
+    /**
+     * The Babylon scene, exposed for hosts and tests that need to inspect it.
+     * @returns {Scene}
+     */
+    get scene() {
+        return this.#scene;
+    }
+
+    /**
+     * Orients the cube like the host camera and follows its projection. An orthographic host gives an orthographic
+     * cube fitted to the full geometry envelope. Perspective uses the host vertical FOV and the smallest
+     * rotation-invariant sphere framing, with a 2% safety margin in both modes.
+     * Top/bottom synchronization uses a numerical pole offset rather than the separate user-drag safety limit.
+     * @param {{alpha: number, beta: number, mode?: number, fov?: number}} pose - Host camera angles in radians (beta uses only a 1e-7 rad numerical pole offset), projection mode (Camera.ORTHOGRAPHIC_CAMERA or Camera.PERSPECTIVE_CAMERA; absent keeps the last one) and vertical field of view in radians (absent or outside the finite (0, PI) range keeps the last one, 0.8 initially).
+     * @returns {void}
+     */
+    setPose({ alpha, beta, mode, fov }) {
+        if (this.#disposed) {
+            return;
+        }
+        const camera = this.#camera;
+        if (mode === Camera.ORTHOGRAPHIC_CAMERA || mode === Camera.PERSPECTIVE_CAMERA) {
+            this.#mode = mode;
+        }
+        if (typeof fov === "number" && Number.isFinite(fov) && fov > 0 && fov < Math.PI) {
+            this.#fov = fov;
+        }
+        this.#applyProjection(camera);
+        camera.alpha = alpha;
+        camera.beta = Math.min(Math.max(beta, BabylonJSViewCubeCanvasRenderer.#POLE_RENDER_MARGIN), Math.PI - BabylonJSViewCubeCanvasRenderer.#POLE_RENDER_MARGIN);
+        camera.getViewMatrix(true);
+    }
+
+    /**
+     * Finds the region under a point. Coordinates are CSS pixels from the canvas top-left; they are scaled by
+     * the canvas client size (falling back to the render size when the client size is unknown) and cast as an
+     * ray (parallel for an orthographic cube, from the camera for a perspective one), so the result does not depend on hardware scaling. Corners win over edges and edges over
+     * faces when they overlap on screen. A front-facing edge or corner whose projected centre is within the pick tolerance
+     * of the pointer wins over the face under it (corners before edges, then the nearest centre). The tolerance is
+     * min(8 CSS px, 1/12 of the cube side), so small cubes keep their face centres pickable. It also rescues a ray that
+     * misses the cube: a pointer just outside the silhouette but within tolerance of a front-facing edge or corner
+     * centre returns that region, which makes the thin outer bars and corner spheres easier to hit; hover and click
+     * both go through pick(), so they stay consistent. Back-facing and edge-on regions are never chosen this way, and a
+     * point outside the cube farther than the tolerance from every front-facing centre still returns null.
+     * @param {number} x - Horizontal position in CSS pixels.
+     * @param {number} y - Vertical position in CSS pixels.
+     * @returns {string|null} Region id such as "0,0,1", "1,0,1" or "1,1,1", or null outside the cube.
+     */
+    pick(x, y) {
+        if (this.#disposed) {
+            return null;
+        }
+        const { width, height } = this.#getCssSize();
+        if (!(width > 0 && height > 0)) {
+            return null;
+        }
+        const camera = this.#camera;
+        camera.getViewMatrix(true);
+        const forward = camera.target.subtract(camera.position).normalize();
+        const right = Vector3.Cross(camera.upVector, forward).normalize();
+        const up = Vector3.Cross(forward, right);
+        const perspective = camera.mode === Camera.PERSPECTIVE_CAMERA;
+        // Half extents of the view plane through the cube centre: fixed for orthographic, radius * tan(fov / 2) for perspective.
+        const halfHeight = perspective ? camera.radius * Math.tan(camera.fov / 2) : (camera.orthoTop - camera.orthoBottom) / 2;
+        const halfWidth = perspective ? halfHeight * (width / height) : (camera.orthoRight - camera.orthoLeft) / 2;
+        const offset = right.scale((x / width * 2 - 1) * halfWidth).add(up.scale((1 - y / height * 2) * halfHeight));
+        const ray = perspective
+            ? new Ray(camera.position, forward.scale(camera.radius).add(offset).normalize(), 100)
+            : new Ray(camera.position.add(offset), forward, 100);
+        const hits = this.#scene
+            .multiPickWithRay(ray, (mesh) => Boolean(mesh.metadata?.regionId))
+            .filter((hit) => hit.hit)
+            .sort((a, b) => a.distance - b.distance);
+        const near = this.#pickByTolerance(x, y, width, height, forward, BabylonJSViewCubeCanvasRenderer.#computePickTolerance(Math.min(width, height)));
+        if (near) {
+            return near;
+        }
+        if (!hits.length) {
+            return null;
+        }
+        const front = hits.filter((hit) => hit.distance - hits[0].distance <= BabylonJSViewCubeCanvasRenderer.#PICK_DEPTH_TOLERANCE);
+        const rank = (hit) => hit.pickedMesh.metadata.rank;
+        return front.reduce((best, hit) => (rank(hit) > rank(best) ? hit : best)).pickedMesh.metadata.regionId;
+    }
+
+    /**
+     * Sets the hovered region, shown with the hover colour. Hover wins over current.
+     * @param {string|null} regionId - Region id, or null to clear.
+     * @returns {void}
+     */
+    setHover(regionId) {
+        this.#setState("hover", regionId);
+    }
+
+    /**
+     * Sets the region that matches the current view, shown with the current colour.
+     * @param {string|null} regionId - Region id, or null to clear.
+     * @returns {void}
+     */
+    setCurrent(regionId) {
+        this.#setState("current", regionId);
+    }
+
+    /**
+     * Merges colours into the palette and repaints every region; meshes are kept.
+     * @param {object} colors - Partial hex palette and hoverOpacity/currentOpacity values in 0..1.
+     * @returns {void}
+     */
+    setColors(colors) {
+        if (this.#disposed) {
+            return;
+        }
+        this.#colors = { ...this.#colors, ...colors };
+        this.#paintAll();
+    }
+
+    /**
+     * Applies resolved SVG typography and repaints existing face textures only when it changes.
+     * Font size and letter spacing are converted from the SVG face width to texture pixels during painting.
+     * @param {object} style - Font family, size, weight, spacing and textTransform in SVG reference units.
+     * @returns {void}
+     */
+    setLabelStyle(style) {
+        if (this.#disposed) {
+            return;
+        }
+        const next = { ...this.#labelStyle, ...style };
+        if (JSON.stringify(next) === JSON.stringify(this.#labelStyle)) {
+            return;
+        }
+        this.#labelStyle = next;
+        this.#paintAll();
+    }
+
+    /**
+     * Merges face labels and repaints the face textures; meshes are kept.
+     * @param {Object<string, string>} labels - Partial labels keyed right, left, bottom, top, back, front.
+     * @returns {void}
+     */
+    setLabels(labels) {
+        if (this.#disposed) {
+            return;
+        }
+        this.#labels = { ...this.#labels, ...labels };
+        this.#paintAll();
+    }
+
+    /**
+     * Returns the colour a region is currently painted with (face fill, edge, corner, hover or current).
+     * @param {string} regionId - Region id.
+     * @returns {string|null} "#rrggbb" colour, or null for an unknown region.
+     */
+    getRegionColor(regionId) {
+        return this.#regions.has(regionId) ? this.#resolveColor(this.#regions.get(regionId)) : null;
+    }
+
+    /**
+     * Projects a region centre with the current camera.
+     * @param {string} regionId - Region id.
+     * @returns {{x: number, y: number}|null} Position in CSS pixels from the canvas top-left, or null for an unknown region or after dispose.
+     */
+    getRegionScreenPosition(regionId) {
+        const region = this.#regions.get(regionId);
+        if (this.#disposed || !region) {
+            return null;
+        }
+        const { width, height } = this.#getCssSize();
+        const camera = this.#camera;
+        const viewProjection = camera.getViewMatrix(true).multiply(camera.getProjectionMatrix(true));
+        const ndc = Vector3.TransformCoordinates(region.mesh.position, viewProjection);
+        return { x: (ndc.x * 0.5 + 0.5) * width, y: (0.5 - ndc.y * 0.5) * height };
+    }
+
+    /**
+     * Applies canvas size, hardware scaling and aspect-aware cube framing after a viewport resize.
+     * @param {number} [devicePixelRatio] - Current pixel ratio; when valid (> 0) it replaces the stored one, otherwise the stored one is kept.
+     * @returns {void}
+     */
+    resize(devicePixelRatio) {
+        if (this.#disposed) {
+            return;
+        }
+        if (devicePixelRatio > 0) {
+            this.#devicePixelRatio = devicePixelRatio;
+        }
+        this.#engine.setHardwareScalingLevel(1 / this.#devicePixelRatio);
+        this.#engine.resize();
+        this.#applyProjection(this.#camera);
+    }
+
+    /**
+     * Renders one frame; the host render loop calls this. No-op after dispose or for a zero-size canvas.
+     * @returns {boolean} Whether a frame was drawn; false means the host should keep its dirty flag and retry later.
+     */
+    render() {
+        if (this.#disposed || this.#engine.getRenderWidth() === 0 || this.#engine.getRenderHeight() === 0) {
+            return false;
+        }
+        this.#scene.render();
+        return true;
+    }
+
+    /**
+     * Releases the experimental SSAO pipeline, cube FXAA pass, scene, textures and engine. Safe to call more than once; host graphics are untouched.
+     * @returns {void}
+     */
+    dispose() {
+        if (this.#disposed) {
+            return;
+        }
+        this.#disposed = true;
+        this.#engine.onContextRestoredObservable?.remove(this.#contextRestoredObserver);
+        this.#contextRestoredObserver = null;
+        this.#regions.clear();
+        if (this.#ambientOcclusion) {
+            this.#ambientOcclusion.dispose();
+            this.#ambientOcclusion = null;
+            this.#scene.disableGeometryBufferRenderer();
+        }
+        this.#antiAliasing.dispose(this.#camera);
+        this.#scene.dispose();
+        // Engine.dispose() tolerates a missing entry, but it also tears down shared state (such as the audio engine)
+        // when it believes it is the last registered engine. Register it again so it disposes like any other engine.
+        if (!EngineStore.Instances.includes(this.#engine)) {
+            EngineStore.Instances.push(this.#engine);
+        }
+        this.#engine.dispose();
+    }
+
+    /**
+     * Pick tolerance for a cube drawn with the given side: min(PICK_TOLERANCE_PX, PICK_TOLERANCE_SIDE_RATIO * side).
+     * @param {number} side - Rendered cube side in CSS pixels.
+     * @returns {number} Tolerance radius in CSS pixels.
+     */
+    static #computePickTolerance(side) {
+        return Math.min(BabylonJSViewCubeCanvasRenderer.#PICK_TOLERANCE_PX, BabylonJSViewCubeCanvasRenderer.#PICK_TOLERANCE_SIDE_RATIO * side);
+    }
+
+
+    /**
+     * Removes this private engine from Babylon global engine discovery without disposing it.
+     * @returns {void}
+     */
+    #unregisterEngine() {
+        const index = EngineStore.Instances.indexOf(this.#engine);
+        if (index >= 0) {
+            EngineStore.Instances.splice(index, 1);
+        }
+    }
+
+    // Best front-facing edge or corner within `tolerance` CSS px of the pointer: highest rank first, then nearest centre.
+    /**
+     * Selects the nearest highest-rank front-facing edge or corner inside a screen-space tolerance.
+     * @param {number} x - Pointer X in CSS pixels.
+     * @param {number} y - Pointer Y in CSS pixels.
+     * @param {number} width - Canvas CSS width.
+     * @param {number} height - Canvas CSS height.
+     * @param {Vector3} forward - Unit camera forward direction.
+     * @param {number} tolerance - Maximum pointer distance in CSS pixels.
+     * @returns {?string} Region identifier, or null when no eligible region is nearby.
+     */
+    #pickByTolerance(x, y, width, height, forward, tolerance) {
+        const camera = this.#camera;
+        const viewProjection = camera.getViewMatrix(true).multiply(camera.getProjectionMatrix(true));
+        let best = null;
+        for (const region of this.#regions.values()) {
+            if (region.kind < 2) {
+                continue;
+            }
+            const length = Math.hypot(...region.axes);
+            const facing = -(region.axes[0] * forward.x + region.axes[1] * forward.y + region.axes[2] * forward.z) / length;
+            if (facing < BabylonJSViewCubeCanvasRenderer.#FRONT_FACING_MIN_DOT) {
+                continue;
+            }
+            const ndc = Vector3.TransformCoordinates(region.mesh.position, viewProjection);
+            const distance = Math.hypot((ndc.x * 0.5 + 0.5) * width - x, (0.5 - ndc.y * 0.5) * height - y);
+            if (distance > tolerance) {
+                continue;
+            }
+            if (!best || region.kind > best.kind || (region.kind === best.kind && distance < best.distance)) {
+                best = { id: region.id, kind: region.kind, distance };
+            }
+        }
+        return best?.id ?? null;
+    }
+
+    /**
+     * Fits the rotation-invariant bounding sphere, including corner spheres, with a 2% rasterization margin.
+     * Orthographic extents and perspective tangent framing use the narrower viewport dimension; the host FOV
+     * is retained. Framing does not change while orbiting, so the cube never pulses or clips during rotation.
+     * Near/far planes enclose the complete geometry, even for a very wide perspective field of view.
+     * @param {ArcRotateCamera} camera - Owned cube camera to update; the host camera is untouched.
+     * @returns {void}
+     */
+    #applyProjection(camera) {
+        const { width, height } = this.#getCssSize();
+        const aspect = width > 0 && height > 0 ? width / height : 1;
+        const radius = BabylonJSViewCubeCanvasRenderer.#BOUNDING_RADIUS;
+        const extent = radius * BabylonJSViewCubeCanvasRenderer.#FRAME_PADDING;
+        if (this.#mode === Camera.PERSPECTIVE_CAMERA) {
+            camera.mode = Camera.PERSPECTIVE_CAMERA;
+            camera.fovMode = Camera.FOVMODE_VERTICAL_FIXED;
+            camera.fov = this.#fov;
+            const tangent = Math.tan(this.#fov / 2) * Math.min(1, aspect) / BabylonJSViewCubeCanvasRenderer.#FRAME_PADDING;
+            camera.radius = radius * Math.sqrt(1 + 1 / (tangent * tangent));
+            camera.minZ = Math.min(0.1, (camera.radius - radius) / 2);
+            camera.maxZ = camera.radius + BabylonJSViewCubeCanvasRenderer.#PERSPECTIVE_DEPTH_MARGIN;
+            return;
+        }
+        camera.mode = Camera.ORTHOGRAPHIC_CAMERA;
+        camera.radius = BabylonJSViewCubeCanvasRenderer.#CAMERA_RADIUS;
+        camera.orthoLeft = -extent * Math.max(1, aspect);
+        camera.orthoRight = extent * Math.max(1, aspect);
+        camera.orthoBottom = -extent / Math.min(1, aspect);
+        camera.orthoTop = extent / Math.min(1, aspect);
+        camera.minZ = 0.1;
+        camera.maxZ = BabylonJSViewCubeCanvasRenderer.#CAMERA_RADIUS * 4;
+    }
+
+    /**
+     * Creates the detached-input cube camera, frames the geometry and permits pole views with only a numerical offset.
+     * Explicit beta limits prevent Babylon from imposing its default visible tilt during scene updates.
+     * @returns {ArcRotateCamera} Camera disposed with the owned scene.
+     */
+    #createCamera() {
+        const camera = new ArcRotateCamera("view-cube-camera", Math.PI / 2, Math.PI / 2, BabylonJSViewCubeCanvasRenderer.#CAMERA_RADIUS, Vector3.Zero(), this.#scene);
+        camera.inputs.clear();
+        camera.lowerBetaLimit = BabylonJSViewCubeCanvasRenderer.#POLE_RENDER_MARGIN;
+        camera.upperBetaLimit = Math.PI - BabylonJSViewCubeCanvasRenderer.#POLE_RENDER_MARGIN;
+        this.#applyProjection(camera);
+        this.#scene.activeCamera = camera;
+        return camera;
+    }
+
+    /**
+     * Enables the lightweight SSAO visual trial when this private engine supports the required buffers.
+     * Own-engine checks avoid SSAO2.IsSupported, which reads Babylon's global engine registry and can inspect
+     * the host model engine instead. Unsupported engines (including NullEngine) keep the normal cube rendering.
+     * Half-resolution geometry excludes transparent labels; the composite retains scene alpha and final FXAA
+     * runs afterward. The host's demand-render loop remains the only frame owner. dispose() releases the pipeline
+     * and its dedicated geometry buffer before the rest of the scene. No main-scene resources are changed.
+     * @returns {void}
+     */
+    #createAmbientOcclusion() {
+        const caps = this.#engine.getCaps();
+        if (!BabylonJSViewCubeCanvasRenderer.#SSAO_ENABLED || !this.#engine._features?.supportSSAO2
+            || !caps.drawBuffersExtension || !(caps.textureFloatRender || caps.textureHalfFloatRender)) {
+            return;
+        }
+        const settings = BabylonJSViewCubeCanvasRenderer.#SSAO_SETTINGS;
+        const geometry = this.#scene.enableGeometryBufferRenderer(settings.ratio);
+        if (!geometry?.isSupported) {
+            this.#scene.disableGeometryBufferRenderer();
+            return;
+        }
+        geometry.renderList = [...this.#regions.values()].map(region => region.mesh);
+        geometry.renderTransparentMeshes = false;
+        const pipeline = new SSAO2RenderingPipeline("view-cube-ssao", this.#scene,
+            { ssaoRatio: settings.ratio, blurRatio: 1 }, [this.#camera], geometry);
+        pipeline.samples = settings.samples;
+        pipeline.radius = settings.radius;
+        pipeline.totalStrength = settings.strength;
+        pipeline.textureSamples = 1;
+        this.#ambientOcclusion = pipeline;
+    }
+
+    /**
+     * Adds hemispheric illumination with neutral 75% lower fill for moderate surface contrast.
+     * Light specular strength is reduced to soften Top highlights while preserving diffuse fill and material settings.
+     * A weak tilted lower directional light adds diffuse illumination and white specular highlights to Bottom, Left and Outer,
+     * preserving the hemispheric fill and upper-face illumination. Scene disposal releases both lights.
+     * @returns {void}
+     */
+    #createLight() {
+        const light = new HemisphericLight("view-cube-light", BabylonJSViewCubeCanvasRenderer.#LIGHT_DIRECTION.clone(), this.#scene);
+        light.intensity = BabylonJSViewCubeCanvasRenderer.#LIGHT_INTENSITY;
+        light.specular = BabylonJSViewCubeCanvasRenderer.#LIGHT_SPECULAR_COLOR.clone();
+        light.groundColor = BabylonJSViewCubeCanvasRenderer.#LIGHT_GROUND_COLOR.clone();
+        const bottomLight = new DirectionalLight("view-cube-bottom-light", BabylonJSViewCubeCanvasRenderer.#BOTTOM_LIGHT_DIRECTION.clone(), this.#scene);
+        bottomLight.intensity = BabylonJSViewCubeCanvasRenderer.#BOTTOM_LIGHT_INTENSITY;
+        bottomLight.diffuse = Color3.White();
+        bottomLight.specular = Color3.White();
+    }
+
+    /**
+     * Creates 26 pickable lit surfaces with broader highlights on corner spheres plus six transparent label layers, then paints the palette.
+     * @returns {void} Resources are owned by this renderer and its scene.
+     */
+    #createRegions() {
+        for (const { id } of BabylonJSViewCubeCanvasOrbitMath.VIEW_CUBE_DIRECTIONS) {
+            const axes = id.split(",").map(Number);
+            const kind = axes.filter(Boolean).length; // 1 face, 2 edge, 3 corner
+            const material = new StandardMaterial(`view-cube-${id}`, this.#scene);
+            material.specularColor = BabylonJSViewCubeCanvasRenderer.#SPECULAR_COLOR.clone();
+            material.specularPower = kind === 3 ? BabylonJSViewCubeCanvasRenderer.#CORNER_SPECULAR_POWER : BabylonJSViewCubeCanvasRenderer.#SPECULAR_POWER;
+            const region = { id, kind, axes, material, mesh: null, texture: null, labelMesh: null };
+            region.mesh = kind === 1 ? this.#createFace(region) : kind === 2 ? this.#createEdge(region) : this.#createCorner(region);
+            region.mesh.material = material;
+            region.mesh.metadata = { regionId: id, rank: kind };
+            region.mesh.computeWorldMatrix(true);
+            this.#regions.set(id, region);
+        }
+        this.#paintAll();
+    }
+
+    /**
+     * Creates a solid outward-facing plane plus a separately owned transparent label layer.
+     * The base material has no texture, so its diffuse/specular/emission response matches edges and corners.
+     * @param {object} region - Region axes, identifier and material; receives its texture.
+     * @returns {import("@babylonjs/core").Mesh} Plane owned by the cube scene.
+     */
+    #createFace(region) {
+        const [x, y, z] = region.axes;
+        const mesh = MeshBuilder.CreatePlane(`view-cube-face-${region.id}`, { size: BabylonJSViewCubeCanvasRenderer.#CUBE_HALF * 2 }, this.#scene);
+        mesh.position.set(x * BabylonJSViewCubeCanvasRenderer.#CUBE_HALF, y * BabylonJSViewCubeCanvasRenderer.#CUBE_HALF, z * BabylonJSViewCubeCanvasRenderer.#CUBE_HALF);
+        // Babylon's plane is visible, with its texture upright and unmirrored, from the side its normal points to; aim local
+        // +Z outward so back-face culling keeps the near faces (checked on screen: aimed inward, the far faces showed through).
+        const up = y ? new Vector3(0, 0, -y) : Vector3.Up();
+        mesh.rotationQuaternion = Quaternion.FromLookDirectionLH(new Vector3(x, y, z), up);
+        region.material.backFaceCulling = true;
+        this.#createFaceLabel(region, mesh);
+        return mesh;
+    }
+
+    /**
+     * Adds an alpha-blended text-only plane just outside its solid parent face; it never participates in picking.
+     * The 512 px mipmapped texture owns only glyph pixels. Depth testing/back-face culling hide rear labels,
+     * while a small geometric offset and depth bias avoid flickering against the parent face.
+     * Label material, mesh and texture belong to the cube scene and are released by dispose().
+     * @param {object} region - Face region receiving its label mesh and texture.
+     * @param {import("@babylonjs/core").Mesh} face - Solid parent plane whose orientation is inherited.
+     * @returns {void}
+     */
+    #createFaceLabel(region, face) {
+        region.texture = new DynamicTexture(`view-cube-label-${region.id}`, this.#createLabelCanvas(), this.#scene, true, Texture.TRILINEAR_SAMPLINGMODE);
+        region.texture.anisotropicFilteringLevel = BabylonJSViewCubeCanvasRenderer.#LABEL_ANISOTROPY;
+        region.texture.hasAlpha = true;
+        const material = new StandardMaterial(`view-cube-label-material-${region.id}`, this.#scene);
+        material.diffuseTexture = region.texture;
+        material.useAlphaFromDiffuseTexture = true;
+        material.transparencyMode = StandardMaterial.MATERIAL_ALPHABLEND;
+        material.disableLighting = true;
+        material.emissiveColor = Color3.White();
+        material.specularColor = Color3.Black();
+        material.backFaceCulling = true;
+        material.zOffset = -1;
+        const label = MeshBuilder.CreatePlane(`view-cube-label-plane-${region.id}`, { size: BabylonJSViewCubeCanvasRenderer.#CUBE_HALF * 2 }, this.#scene);
+        label.parent = face;
+        // Babylon plane vertices face local -Z, so a negative local offset moves the label outward.
+        label.position.z = -BabylonJSViewCubeCanvasRenderer.#LABEL_SURFACE_OFFSET;
+        label.material = material;
+        label.isPickable = false;
+        region.labelMesh = label;
+    }
+
+    /**
+     * Creates an axis-aligned edge bar in the owned cube scene.
+     * @param {object} region - Region identifier and signed axes.
+     * @returns {import("@babylonjs/core").Mesh} Bar disposed with the cube scene.
+     */
+    #createEdge(region) {
+        const [x, y, z] = region.axes;
+        /** @param {number} axis - Signed region axis. @returns {number} Edge length along that axis. */
+        const size = (axis) => (axis ? BabylonJSViewCubeCanvasRenderer.#EDGE_THICKNESS : BabylonJSViewCubeCanvasRenderer.#EDGE_LENGTH);
+        const mesh = MeshBuilder.CreateBox(`view-cube-edge-${region.id}`, { width: size(x), height: size(y), depth: size(z) }, this.#scene);
+        mesh.position.set(x * BabylonJSViewCubeCanvasRenderer.#CUBE_HALF, y * BabylonJSViewCubeCanvasRenderer.#CUBE_HALF, z * BabylonJSViewCubeCanvasRenderer.#CUBE_HALF);
+        return mesh;
+    }
+
+    /**
+     * Creates a corner sphere in the owned cube scene.
+     * @param {object} region - Region identifier and signed axes.
+     * @returns {import("@babylonjs/core").Mesh} Sphere disposed with the cube scene.
+     */
+    #createCorner(region) {
+        const [x, y, z] = region.axes;
+        const mesh = MeshBuilder.CreateSphere(`view-cube-corner-${region.id}`, { diameter: BabylonJSViewCubeCanvasRenderer.#CORNER_DIAMETER, segments: BabylonJSViewCubeCanvasRenderer.#CORNER_SEGMENTS }, this.#scene);
+        mesh.position.set(x * BabylonJSViewCubeCanvasRenderer.#CUBE_HALF, y * BabylonJSViewCubeCanvasRenderer.#CUBE_HALF, z * BabylonJSViewCubeCanvasRenderer.#CUBE_HALF);
+        return mesh;
+    }
+
+    // The canvas comes from the host document so the renderer never touches a global `document`.
+    /**
+     * Allocates a supersampled 512 px label texture canvas using the host document without accessing a global document.
+     * @returns {HTMLCanvasElement} Offscreen canvas retained by the face texture.
+     */
+    #createLabelCanvas() {
+        const canvas = this.#canvas.ownerDocument.createElement("canvas");
+        canvas.width = BabylonJSViewCubeCanvasRenderer.#TEXTURE_SIZE;
+        canvas.height = BabylonJSViewCubeCanvasRenderer.#TEXTURE_SIZE;
+        return canvas;
+    }
+
+    /**
+     * Composites hover or current tint over a neutral gray derived from base RGB luminance; hover wins.
+     * Uses perceptual channel weights (0.2126 R, 0.7152 G, 0.0722 B) so the base contributes brightness without hue.
+     * Unhighlighted surfaces retain their original base color; material opacity and lighting remain unchanged.
+     * @param {object} region - Region identifier and face/edge/corner kind.
+     * @returns {string} Hex color from the active palette.
+     */
+    #resolveColor(region) {
+        const base = region.kind === 1 ? this.#colors.fill : region.kind === 2 ? this.#colors.edge : this.#colors.corner;
+        const rgb = Color3.FromHexString(base);
+        const luminance = rgb.r * 0.2126 + rgb.g * 0.7152 + rgb.b * 0.0722;
+        const gray = new Color3(luminance, luminance, luminance);
+        if (region.id === this.#state.hover) {
+            return Color3.Lerp(gray, Color3.FromHexString(this.#colors.hover), this.#colors.hoverOpacity).toHexString().toLowerCase();
+        }
+        if (region.id === this.#state.current) {
+            return Color3.Lerp(gray, Color3.FromHexString(this.#colors.current), this.#colors.currentOpacity).toHexString().toLowerCase();
+        }
+        return base;
+    }
+
+    /**
+     * Updates diffuse color and the configured emissive fraction (currently zero) on all surfaces, then redraws transparent glyphs.
+     * Palette and interaction changes therefore update emission as well as the visible fill and labels.
+     * Shared SVG typography and spacing scale with texture resolution, retaining centered text at its apparent size.
+     * @param {object} region - Region with its material and optional face texture.
+     * @returns {void}
+     */
+    #paint(region) {
+        const color = this.#resolveColor(region);
+        const base = Color3.FromHexString(color);
+        region.material.diffuseColor = base;
+        region.material.emissiveColor = base.scale(BabylonJSViewCubeCanvasRenderer.#EMISSIVE_STRENGTH);
+        if (region.kind > 1) {
+            return;
+        }
+        const context = region.texture.getContext();
+        if (context) {
+            context.clearRect(0, 0, BabylonJSViewCubeCanvasRenderer.#TEXTURE_SIZE, BabylonJSViewCubeCanvasRenderer.#TEXTURE_SIZE);
+            context.fillStyle = this.#colors.text;
+            const typography = this.#labelStyle;
+            const scale = BabylonJSViewCubeCanvasRenderer.#TEXTURE_SIZE / BabylonJSViewCubeCanvasRenderer.#SVG_FACE_WIDTH;
+            context.font = `${typography.fontWeight} ${typography.fontSize * scale}px ${typography.fontFamily}`;
+            context.letterSpacing = `${typography.letterSpacing * scale}px`;
+            context.textAlign = "center";
+            context.textBaseline = "middle";
+            const label = this.#labels[BabylonJSViewCubeCanvasRenderer.#FACE_LABEL_KEYS[region.id]];
+            const text = typography.textTransform === "uppercase" ? label.toUpperCase() : typography.textTransform === "lowercase" ? label.toLowerCase() : label;
+            context.fillText(text, BabylonJSViewCubeCanvasRenderer.#TEXTURE_SIZE / 2, BabylonJSViewCubeCanvasRenderer.#TEXTURE_SIZE / 2);
+        }
+        region.texture.update();
+    }
+
+    /**
+     * Repaints all registered regions using the current palette, labels and interaction state.
+     * @returns {void}
+     */
+    #paintAll() {
+        this.#regions.forEach((region) => this.#paint(region));
+    }
+
+    /**
+     * Updates a hover/current region and repaints the affected regions; ignores disposed or unchanged state.
+     * @param {"hover"|"current"} key - State entry to update.
+     * @param {?string} regionId - Region to activate, or null to clear.
+     * @returns {void}
+     */
+    #setState(key, regionId) {
+        if (this.#disposed) {
+            return;
+        }
+        const previous = this.#state[key];
+        const next = this.#regions.has(regionId) ? regionId : null;
+        if (previous === next) {
+            return;
+        }
+        this.#state[key] = next;
+        [previous, next].forEach((id) => id && this.#paint(this.#regions.get(id)));
+    }
+
+    /**
+     * Reads canvas CSS dimensions, falling back to engine render dimensions multiplied by hardware scaling.
+     * @returns {{width: number, height: number}} Canvas dimensions in CSS pixels.
+     */
+    #getCssSize() {
+        const scaling = this.#engine.getHardwareScalingLevel();
+        return {
+            width: this.#canvas.clientWidth || this.#engine.getRenderWidth() * scaling,
+            height: this.#canvas.clientHeight || this.#engine.getRenderHeight() * scaling,
+        };
+    }
+
+    /** @returns {Readonly<Object<string, string>>} Immutable palette available to dark-theme hosts. */
+    static get VIEW_CUBE_DARK_COLORS() {
+        return PrefViewerViewCubePalette.darkColors;
+    }
+
+    /** @returns {Readonly<object>} Immutable default Engine options, including context cleanup policy. */
+    static get VIEW_CUBE_ENGINE_OPTIONS() {
+        return BabylonJSViewCubeCanvasRenderer.#VIEW_CUBE_ENGINE_OPTIONS;
+    }
+}