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

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

@@ -1,548 +0,0 @@
-// Visual design adapted from the PrefSketch view cube (PrefSketch src/viewer/view-cube.ts): a 1-unit cube with
-// 128 px labelled face cells, thin edge bars, corner spheres, a hemispheric light and the PrefSketch palette.
-// Geometry, lighting and painting are translated to this viewer's left-handed scene and region-per-mesh picking.
-import { ArcRotateCamera, Camera, Color3, Color4, DynamicTexture, Engine, EngineStore, HemisphericLight, MeshBuilder, Quaternion, Ray, Scene, StandardMaterial, Vector3 } from "@babylonjs/core";
-import { VIEW_CUBE_DIRECTIONS, clampBeta } from "./view-cube-orbit-math.js";
-
-const CUBE_HALF = 0.5;
-const EDGE_THICKNESS = 0.09;
-const EDGE_LENGTH = 1 + EDGE_THICKNESS;
-const CORNER_DIAMETER = 0.26;
-const CORNER_SEGMENTS = 8;
-// Edges and corners are lit and also glow at this share of their colour, as in PrefSketch.
-const EMISSIVE_SCALE = 0.35;
-// PrefSketch light direction is (0.4, 1, 0.6) in a right-handed scene; X is mirrored for this left-handed one.
-const LIGHT_DIRECTION = new Vector3(-0.4, 1, 0.6);
-const LIGHT_INTENSITY = 1.1;
-const LIGHT_GROUND_COLOR = new Color3(0.55, 0.55, 0.6);
-const LABEL_FONT_SIZE = 26;
-const BORDER_INSET = 4;
-const BORDER_WIDTH = 4;
-const ORTHO_EXTENT = 1.15;
-const CAMERA_RADIUS = 5;
-const DEFAULT_FOV = 0.8;
-// Perspective depth range around the cube, which is at most ~0.87 from its centre (corner), so +-2 leaves margin.
-const PERSPECTIVE_DEPTH_MARGIN = 2;
-// Distance from the cube centre to a corner sphere centre (half the cube diagonal).
-const CORNER_DISTANCE = Math.sqrt(3) / 2;
-const TEXTURE_SIZE = 128;
-// Hits farther than this behind the nearest one are other sides of the cube, not overlapping parts.
-const 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.
-const 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.
-const 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.
-const FRONT_FACING_MIN_DOT = 0.2;
-
-/**
- * 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.
- */
-function computePickTolerance(side) {
-    return Math.min(PICK_TOLERANCE_PX, PICK_TOLERANCE_SIDE_RATIO * side);
-}
-
-/**
- * PrefSketch dark-theme palette (its --cubo-* tokens). Hosts that follow a dark theme can pass it to
- * setColors(); the renderer itself never reads the page theme.
- */
-export const VIEW_CUBE_DARK_COLORS = Object.freeze({
-    fill: "#2f363a",
-    border: "#9ba4a9",
-    text: "#e6e3da",
-    edge: "#56606a",
-    corner: "#6b7886",
-});
-
-// Light palette = PrefSketch --cubo-cara, --cubo-borde, --cubo-texto, --cubo-arista, --cubo-esquina. PrefSketch has no hover or current state.
-const DEFAULT_COLORS = Object.freeze({
-    fill: "#f7f3ea",
-    border: "#4a5058",
-    text: "#2a2e33",
-    edge: "#b8c2d1",
-    corner: "#9eadc7",
-    hover: "#ff6700",
-    current: "#ffd1b3",
-});
-
-/**
- * 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.
- */
-export const VIEW_CUBE_ENGINE_OPTIONS = Object.freeze({ alpha: true, antialias: true, premultipliedAlpha: false, stencil: false, loseContextOnDispose: true });
-
-const 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".
-const 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" });
-
-/**
- * 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 and no
- * interaction logic: the host calls render() and decides what pick() results mean. It touches neither
- * `window` nor `document` itself, so it can be imported in any environment.
- */
-export default class BabylonJSViewCubeRenderer {
-    #canvas;
-    #engine;
-    #scene;
-    #camera;
-    #mode = Camera.ORTHOGRAPHIC_CAMERA;
-    #fov = DEFAULT_FOV;
-    #colors;
-    #labels;
-    #devicePixelRatio;
-    #regions = new Map();
-    #state = { hover: null, current: null };
-    #fontFamily;
-    #disposed = false;
-    #contextRestoredObserver = null;
-
-    /**
-     * Creates the engine, scene, camera and the 26 cube regions.
-     * @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<string, string>} [options.colors] - "#rrggbb" colours: fill, border, text (faces), edge, corner, hover, current.
-     * @param {number} [options.devicePixelRatio=1] - Pixel ratio used by resize(); never read from `window`.
-     * @param {string} [options.fontFamily="sans-serif"] - Font family of the face labels.
-     * @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 = "sans-serif", onContextRestored }) {
-        this.#canvas = canvas;
-        this.#colors = { ...DEFAULT_COLORS, ...colors };
-        this.#labels = { ...DEFAULT_LABELS, ...labels };
-        this.#devicePixelRatio = devicePixelRatio > 0 ? devicePixelRatio : 1;
-        this.#fontFamily = fontFamily;
-        this.#engine = createEngine ? createEngine(canvas) : new Engine(canvas, true, { ...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();
-    }
-
-    /**
-     * 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 (radius 5, extents +-1.15). A perspective host gives a perspective cube with the host's vertical fov at
-     * radius 0.5 + 1.15 / tan(fov / 2), so the near face and its corner knobs keep the on-screen size of the
-     * orthographic layout (the rest of the cube foreshortens behind it).
-     * @param {{alpha: number, beta: number, mode?: number, fov?: number}} pose - Host camera angles in radians (beta is clamped away from the poles), projection mode (Camera.ORTHOGRAPHIC_CAMERA or Camera.PERSPECTIVE_CAMERA; absent keeps the last one) and vertical field of view in radians (absent or not a finite positive number 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) {
-            this.#fov = fov;
-        }
-        this.#applyProjection(camera);
-        camera.alpha = alpha;
-        camera.beta = clampBeta(beta);
-        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, computePickTolerance(Math.min(width, height)));
-        if (near) {
-            return near;
-        }
-        if (!hits.length) {
-            return null;
-        }
-        const front = hits.filter((hit) => hit.distance - hits[0].distance <= 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<string, string>} colors - Partial "#rrggbb" palette, see the constructor.
-     * @returns {void}
-     */
-    setColors(colors) {
-        if (this.#disposed) {
-            return;
-        }
-        this.#colors = { ...this.#colors, ...colors };
-        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 the canvas size and the hardware scaling derived from devicePixelRatio.
-     * @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();
-    }
-
-    /**
-     * 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 scene, its textures and the engine. Safe to call more than once.
-     * @returns {void}
-     */
-    dispose() {
-        if (this.#disposed) {
-            return;
-        }
-        this.#disposed = true;
-        this.#engine.onContextRestoredObservable?.remove(this.#contextRestoredObserver);
-        this.#contextRestoredObserver = null;
-        this.#regions.clear();
-        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();
-    }
-
-    #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.
-    #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 < 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;
-    }
-
-    // Orthographic: fixed radius and extents. Perspective: the host fov and the radius that frames the same half extent
-    // at the near face plane (CUBE_HALF in front of the centre), where the corner knobs and the face in view are drawn.
-    #applyProjection(camera) {
-        if (this.#mode === Camera.PERSPECTIVE_CAMERA) {
-            camera.mode = Camera.PERSPECTIVE_CAMERA;
-            camera.fovMode = Camera.FOVMODE_VERTICAL_FIXED;
-            camera.fov = this.#fov;
-            camera.radius = CUBE_HALF + ORTHO_EXTENT / Math.tan(this.#fov / 2);
-            // A wide fov brings the camera closer than the margin: keep the near plane positive and before the nearest corner.
-            camera.minZ = Math.max(camera.radius - PERSPECTIVE_DEPTH_MARGIN, Math.min(0.1, (camera.radius - CORNER_DISTANCE) / 2));
-            camera.maxZ = camera.radius + PERSPECTIVE_DEPTH_MARGIN;
-            return;
-        }
-        camera.mode = Camera.ORTHOGRAPHIC_CAMERA;
-        camera.radius = CAMERA_RADIUS;
-        camera.minZ = 0.1;
-        camera.maxZ = CAMERA_RADIUS * 4;
-    }
-
-    #createCamera() {
-        const camera = new ArcRotateCamera("view-cube-camera", Math.PI / 2, Math.PI / 2, CAMERA_RADIUS, Vector3.Zero(), this.#scene);
-        camera.inputs.clear();
-        camera.mode = Camera.ORTHOGRAPHIC_CAMERA;
-        camera.orthoLeft = -ORTHO_EXTENT;
-        camera.orthoRight = ORTHO_EXTENT;
-        camera.orthoBottom = -ORTHO_EXTENT;
-        camera.orthoTop = ORTHO_EXTENT;
-        camera.minZ = 0.1;
-        camera.maxZ = CAMERA_RADIUS * 4;
-        this.#scene.activeCamera = camera;
-        return camera;
-    }
-
-    #createLight() {
-        const light = new HemisphericLight("view-cube-light", LIGHT_DIRECTION.clone(), this.#scene);
-        light.intensity = LIGHT_INTENSITY;
-        light.groundColor = LIGHT_GROUND_COLOR.clone();
-    }
-
-    #createRegions() {
-        for (const { id } of 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 = kind === 1 ? new Color3(0.05, 0.05, 0.05) : Color3.Black();
-            const region = { id, kind, axes, material, mesh: null, texture: 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();
-    }
-
-    #createFace(region) {
-        const [x, y, z] = region.axes;
-        const mesh = MeshBuilder.CreatePlane(`view-cube-face-${region.id}`, { size: CUBE_HALF * 2 }, this.#scene);
-        mesh.position.set(x * CUBE_HALF, y * CUBE_HALF, z * 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.texture = new DynamicTexture(`view-cube-label-${region.id}`, this.#createLabelCanvas(), this.#scene, true);
-        region.material.diffuseTexture = region.texture;
-        region.material.emissiveColor = new Color3(EMISSIVE_SCALE, EMISSIVE_SCALE, EMISSIVE_SCALE);
-        region.material.backFaceCulling = true;
-        return mesh;
-    }
-
-    #createEdge(region) {
-        const [x, y, z] = region.axes;
-        const size = (axis) => (axis ? EDGE_THICKNESS : 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 * CUBE_HALF, y * CUBE_HALF, z * CUBE_HALF);
-        return mesh;
-    }
-
-    #createCorner(region) {
-        const [x, y, z] = region.axes;
-        const mesh = MeshBuilder.CreateSphere(`view-cube-corner-${region.id}`, { diameter: CORNER_DIAMETER, segments: CORNER_SEGMENTS }, this.#scene);
-        mesh.position.set(x * CUBE_HALF, y * CUBE_HALF, z * CUBE_HALF);
-        return mesh;
-    }
-
-    // The canvas comes from the host document so the renderer never touches a global `document`.
-    #createLabelCanvas() {
-        const canvas = this.#canvas.ownerDocument.createElement("canvas");
-        canvas.width = TEXTURE_SIZE;
-        canvas.height = TEXTURE_SIZE;
-        return canvas;
-    }
-
-    #resolveColor(region) {
-        if (region.id === this.#state.hover) {
-            return this.#colors.hover;
-        }
-        if (region.id === this.#state.current) {
-            return this.#colors.current;
-        }
-        return region.kind === 1 ? this.#colors.fill : region.kind === 2 ? this.#colors.edge : this.#colors.corner;
-    }
-
-    #paint(region) {
-        const color = this.#resolveColor(region);
-        if (region.kind > 1) {
-            const base = Color3.FromHexString(color);
-            region.material.diffuseColor = base;
-            region.material.emissiveColor = base.scale(EMISSIVE_SCALE);
-            return;
-        }
-        const context = region.texture.getContext();
-        if (context) {
-            context.fillStyle = color;
-            context.fillRect(0, 0, TEXTURE_SIZE, TEXTURE_SIZE);
-            context.strokeStyle = this.#colors.border;
-            context.lineWidth = BORDER_WIDTH;
-            context.strokeRect(BORDER_INSET, BORDER_INSET, TEXTURE_SIZE - BORDER_INSET * 2, TEXTURE_SIZE - BORDER_INSET * 2);
-            context.fillStyle = this.#colors.text;
-            context.font = `bold ${LABEL_FONT_SIZE}px ${this.#fontFamily}`;
-            context.textAlign = "center";
-            context.textBaseline = "middle";
-            context.fillText(this.#labels[FACE_LABEL_KEYS[region.id]], TEXTURE_SIZE / 2, TEXTURE_SIZE / 2);
-        }
-        region.texture.update();
-    }
-
-    #paintAll() {
-        this.#regions.forEach((region) => this.#paint(region));
-    }
-
-    #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)));
-    }
-
-    #getCssSize() {
-        const scaling = this.#engine.getHardwareScalingLevel();
-        return {
-            width: this.#canvas.clientWidth || this.#engine.getRenderWidth() * scaling,
-            height: this.#canvas.clientHeight || this.#engine.getRenderHeight() * scaling,
-        };
-    }
-}