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

package/src/babylonjs-selection-controller.js

@@ -0,0 +1,215 @@
+/**
+ * Applies semantic selection state to Babylon model meshes using non-destructive overlays.
+ * Retains the semantic snapshot across model replacements and restores original overlays on cleanup.
+ * @class BabylonJSSelectionController
+ */
+export default class BabylonJSSelectionController {
+    #getModelMeshes;
+    #requestRender;
+    #selectableColor;
+    #selectedColor;
+    #overlayAlpha;
+    #originalOverlays = new Map();
+    #state = {};
+
+    /**
+     * Removes the glTF loader suffix from a mesh id while preserving every other id shape.
+     * @public
+     * @static
+     * @param {unknown} value - Mesh id candidate.
+     * @returns {string} Normalized semantic id, or an empty string when unusable.
+     */
+    static normalizeMeshId(value) {
+        return typeof value === "string" ? value.replace(/_primitive\d+$/, "") : "";
+    }
+
+    /**
+     * Determines whether a completed pointer gesture represents a primary click.
+     * @public
+     * @static
+     * @param {{x:number,y:number,button:number,pointerId?:number,dragged?:boolean}|null} start - Pointer-down snapshot.
+     * @param {{x:number,y:number,button:number,pointerId?:number}|null} end - Pointer-up snapshot.
+     * @param {number} maxDistancePx - Maximum Euclidean movement in CSS pixels.
+     * @returns {boolean} Whether the gesture is a click.
+     */
+    static isPrimaryClickGesture(start, end, maxDistancePx) {
+        if (!start || !end || start.button !== 0 || end.button !== 0 || start.dragged || start.pointerId !== end.pointerId) {
+            return false;
+        }
+        return Math.hypot(end.x - start.x, end.y - start.y) <= maxDistancePx;
+    }
+
+    /**
+     * Checks that a model mesh has geometry and can participate in semantic picking.
+     * Explicit ray predicates bypass Babylon's default visibility and pickability checks.
+     * @public
+     * @static
+     * @param {object} mesh - Babylon mesh considered by the picking predicate.
+     * @param {Set<object>} modelMeshes - Mesh references belonging to the model container.
+     * @returns {boolean} Whether the mesh is visible, enabled, pickable and has vertices.
+     */
+    static isPickableModelMesh(mesh, modelMeshes) {
+        return modelMeshes.has(mesh) && mesh.isVisible !== false && mesh.visibility !== 0
+            && mesh.isPickable !== false && mesh.isEnabled?.() !== false
+            && (mesh.getTotalVertices?.() ?? 0) > 0;
+    }
+
+    /**
+     * Builds the set of model meshes accepted by picking, including Babylon instances owned by them.
+     * @public
+     * @static
+     * @param {Array<object>} meshes - Meshes from the model AssetContainer.
+     * @returns {Set<object>} Accepted model mesh references.
+     */
+    static getModelMeshSet(meshes = []) {
+        const result = new Set();
+        for (const mesh of meshes ?? []) {
+            if (!mesh) {
+                continue;
+            }
+            result.add(mesh);
+            for (const instance of mesh.instances ?? []) {
+                result.add(instance);
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Converts ordered Babylon ray hits into the public semantic mesh-id list.
+     * @public
+     * @static
+     * @param {Array<object>} picks - Babylon PickingInfo results.
+     * @param {Array<object>} modelMeshes - Meshes belonging to the model container.
+     * @returns {string[]} Stable, distance-ordered, deduplicated semantic ids.
+     */
+    static collectPickedMeshIds(picks = [], modelMeshes = []) {
+        const acceptedMeshes = BabylonJSSelectionController.getModelMeshSet(modelMeshes);
+        const ids = [];
+        const seen = new Set();
+        [...(picks ?? [])]
+            .filter((pick) => pick?.hit === true && acceptedMeshes.has(pick.pickedMesh))
+            .sort((left, right) => (left.distance ?? Number.POSITIVE_INFINITY) - (right.distance ?? Number.POSITIVE_INFINITY))
+            .forEach((pick) => {
+                const id = BabylonJSSelectionController.normalizeMeshId(pick.pickedMesh?.id);
+                if (id && !seen.has(id)) {
+                    seen.add(id);
+                    ids.push(id);
+                }
+            });
+        return ids;
+    }
+
+    /**
+     * Creates a controller with a live model-mesh provider and selection presentation settings.
+     * @public
+     * @param {function(): Array<object>} getModelMeshes - Returns current model meshes.
+     * @param {{selectableColor:object,selectedColor:object,overlayAlpha:number,requestRender?:function():void}} options - Overlay configuration.
+     */
+    constructor(getModelMeshes, options) {
+        this.#getModelMeshes = getModelMeshes;
+        this.#selectableColor = options.selectableColor;
+        this.#selectedColor = options.selectedColor;
+        this.#overlayAlpha = options.overlayAlpha;
+        this.#requestRender = options.requestRender ?? (() => {});
+    }
+
+    /**
+     * Applies a complete selection snapshot to every matching model mesh.
+     * @public
+     * @param {{selectableIds?:string[],selectedIds?:string[],selectedItems?:Array<{id:string,highlights?:string[]}>}} state - Canonical selection state.
+     * @returns {void}
+     */
+    applySelectionState(state = {}) {
+        this.#state = state;
+        this.refresh();
+    }
+
+    /**
+     * Reapplies the retained snapshot after model meshes are replaced.
+     * Restores removed meshes, gives selected ids priority and requests rendering only on changes.
+     * @public
+     * @returns {void}
+     */
+    refresh() {
+        const selectableIds = new Set(this.#state.selectableIds ?? []);
+        const selectedIds = new Set(this.#state.selectedIds ?? []);
+        for (const item of this.#state.selectedItems ?? []) {
+            if (item?.id) {
+                selectedIds.add(item.id);
+            }
+            for (const id of item?.highlights ?? []) {
+                selectedIds.add(id);
+            }
+        }
+
+        const currentMeshes = new Set(BabylonJSSelectionController.getModelMeshSet(this.#getModelMeshes?.() ?? []));
+        let changed = false;
+        for (const mesh of this.#originalOverlays.keys()) {
+            if (!currentMeshes.has(mesh)) {
+                changed = this.#restoreMesh(mesh) || changed;
+            }
+        }
+
+        for (const mesh of currentMeshes) {
+            const id = BabylonJSSelectionController.normalizeMeshId(mesh?.id);
+            const color = selectedIds.has(id)
+                ? this.#selectedColor
+                : (selectableIds.has(id) ? this.#selectableColor : null);
+            if (color) {
+                if (!this.#originalOverlays.has(mesh)) {
+                    this.#originalOverlays.set(mesh, {
+                        renderOverlay: mesh.renderOverlay,
+                        overlayColor: mesh.overlayColor,
+                        overlayAlpha: mesh.overlayAlpha,
+                    });
+                }
+                if (mesh.renderOverlay !== true || mesh.overlayColor !== color || mesh.overlayAlpha !== this.#overlayAlpha) {
+                    mesh.renderOverlay = true;
+                    mesh.overlayColor = color;
+                    mesh.overlayAlpha = this.#overlayAlpha;
+                    changed = true;
+                }
+            } else {
+                changed = this.#restoreMesh(mesh) || changed;
+            }
+        }
+
+        if (changed) {
+            this.#requestRender();
+        }
+    }
+
+    /**
+     * Restores all meshes changed by this controller and releases their saved overlay properties.
+     * @public
+     * @returns {void}
+     */
+    dispose() {
+        let changed = false;
+        for (const mesh of [...this.#originalOverlays.keys()]) {
+            changed = this.#restoreMesh(mesh) || changed;
+        }
+        if (changed) {
+            this.#requestRender();
+        }
+    }
+
+    /**
+     * Restores a mesh's saved overlay properties and removes its restoration snapshot.
+     * @private
+     * @param {object} mesh - Mesh previously updated by this controller.
+     * @returns {boolean} Whether a saved overlay was restored.
+     */
+    #restoreMesh(mesh) {
+        const original = this.#originalOverlays.get(mesh);
+        if (!original) {
+            return false;
+        }
+        mesh.renderOverlay = original.renderOverlay;
+        mesh.overlayColor = original.overlayColor;
+        mesh.overlayAlpha = original.overlayAlpha;
+        this.#originalOverlays.delete(mesh);
+        return true;
+    }
+}

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

@@ -1,6 +1,6 @@
 import { Matrix, Quaternion, Vector3 } from "@babylonjs/core/Maths/math.vector.js";
 import { PrefViewerViewCubeStyles } from "./styles.js";
-import { translate } from "./localization/i18n.js";
+import I18n from "./localization/i18n.js";
 import BabylonJSController from "./babylonjs-controller.js";
 import BabylonJSCameraFraming from "./babylonjs-camera-framing.js";
 
@@ -46,6 +46,15 @@ import BabylonJSCameraFraming from "./babylonjs-camera-framing.js";
  * @property {number|null} top - Current orthographic top extent.
  */
 
+/**
+ * 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.
+ */
+
 /**
  * BabylonJSViewCubeController - Owns an SVG orientation indicator and model-framing camera navigation.
  *
@@ -144,26 +153,21 @@ export default class BabylonJSViewCubeController {
             this.#svg.append(node.outline);
         }
         host.canvas.parentElement.append(this.#root);
-        const on = (element, name, handler) => {
-            element.addEventListener(name, handler);
-            this.#listeners.push(() => element.removeEventListener(name, handler));
-        };
-        const regionAt = (event) => event.target?.closest?.("polygon[data-region]")?.dataset.region ?? null;
-        on(this.#svg, "pointermove", (event) => {
+        this.#addListener(this.#svg, "pointermove", (event) => {
             this.#pointer = { x: event.clientX, y: event.clientY };
-            this.#setHover(regionAt(event));
+            this.#setHover(BabylonJSViewCubeController.#getRegionAt(event));
         });
-        on(this.#svg, "pointerleave", () => {
+        this.#addListener(this.#svg, "pointerleave", () => {
             this.#pointer = null;
             this.#setHover(null);
         });
-        on(this.#svg, "pointerdown", (event) => {
-            if (regionAt(event)) {
+        this.#addListener(this.#svg, "pointerdown", (event) => {
+            if (BabylonJSViewCubeController.#getRegionAt(event)) {
                 event.stopPropagation();
             }
         });
-        on(this.#svg, "click", (event) => {
-            const id = regionAt(event);
+        this.#addListener(this.#svg, "click", (event) => {
+            const id = BabylonJSViewCubeController.#getRegionAt(event);
             if (!id) {
                 return;
             }
@@ -173,7 +177,7 @@ export default class BabylonJSViewCubeController {
             }
         });
         for (const event of ["pointerdown", "wheel", "keydown"]) {
-            on(host.canvas, event, () => this.cancel());
+            this.#addListener(host.canvas, event, () => this.cancel());
         }
         this.#resizeObserver = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => this.resize());
         this.#resizeObserver?.observe(host.canvas);
@@ -192,41 +196,18 @@ export default class BabylonJSViewCubeController {
     static createViewCubeRegions() {
         const regions = [];
         const inset = 0.78;
-        const surface = (axis, sign, ranges) => {
-            const other = [0, 1, 2].filter((i) => i !== axis);
-            const normalComponents = [0, 0, 0];
-            normalComponents[axis] = sign;
-            const normal = new Vector3(...normalComponents);
-            const vertices = [
-                [0, 0],
-                [1, 0],
-                [1, 1],
-                [0, 1],
-            ].map(([u, v]) => {
-                const p = [0, 0, 0];
-                p[axis] = sign;
-                p[other[0]] = ranges[other[0]][u];
-                p[other[1]] = ranges[other[1]][v];
-                return new Vector3(...p);
-            });
-            return { normal, vertices };
-        };
-        const add = (axis, surfaces) => {
-            const direction = new Vector3(...axis).normalize();
-            regions.push({ id: axis.join(","), direction, surfaces, kind: ["", "face", "edge", "corner"][axis.filter(Boolean).length] });
-        };
         for (let i = 0; i < 3; i++) {
             for (const s of [-1, 1]) {
                 const axis = [0, 0, 0];
                 axis[i] = s;
-                add(axis, [
-                    surface(i, s, [
+                BabylonJSViewCubeController.#addRegion(regions, axis, [
+                    BabylonJSViewCubeController.#createSurface(i, s, [
                         [-inset, inset],
                         [-inset, inset],
                         [-inset, inset],
                     ]),
                 ]);
-                regions.at(-1).outline = surface(i, s, [
+                regions.at(-1).outline = BabylonJSViewCubeController.#createSurface(i, s, [
                     [-1, 1],
                     [-1, 1],
                     [-1, 1],
@@ -247,7 +228,7 @@ export default class BabylonJSViewCubeController {
                         ];
                         ranges[i] = [s * inset, s];
                         ranges[j] = [t * inset, t];
-                        add(axis, [surface(i, s, ranges), surface(j, t, ranges)]);
+                        BabylonJSViewCubeController.#addRegion(regions, axis, [BabylonJSViewCubeController.#createSurface(i, s, ranges), BabylonJSViewCubeController.#createSurface(j, t, ranges)]);
                     }
                 }
             }
@@ -257,9 +238,9 @@ export default class BabylonJSViewCubeController {
                 for (const z of [-1, 1]) {
                     const signs = [x, y, z];
                     const ranges = signs.map((s) => [s * inset, s]);
-                    add(
+                    BabylonJSViewCubeController.#addRegion(regions,
                         signs,
-                        signs.map((s, i) => surface(i, s, ranges)),
+                        signs.map((s, i) => BabylonJSViewCubeController.#createSurface(i, s, ranges)),
                     );
                 }
             }
@@ -267,6 +248,107 @@ export default class BabylonJSViewCubeController {
         return regions;
     }
 
+    /**
+     * Creates a signed-axis quad with its normal and four cube-space vertices.
+     * @private
+     * @static
+     * @param {number} axis - Fixed coordinate axis index.
+     * @param {number} sign - Fixed axis direction, -1 or 1.
+     * @param {Array<number[]>} ranges - Lower and upper coordinates for each axis.
+     * @returns {{normal:Vector3,vertices:Vector3[]}}
+     */
+    static #createSurface(axis, sign, ranges) {
+        const other = [0, 1, 2].filter((i) => i !== axis);
+        const normalComponents = [0, 0, 0];
+        normalComponents[axis] = sign;
+        const normal = new Vector3(...normalComponents);
+        const vertices = [
+            [0, 0],
+            [1, 0],
+            [1, 1],
+            [0, 1],
+        ].map(([u, v]) => {
+            const p = [0, 0, 0];
+            p[axis] = sign;
+            p[other[0]] = ranges[other[0]][u];
+            p[other[1]] = ranges[other[1]][v];
+            return new Vector3(...p);
+        });
+        return { normal, vertices };
+    }
+
+    /**
+     * Adds a face, edge or corner preset from its signed-axis vector and clickable surfaces.
+     * @private
+     * @static
+     * @param {ViewCubeRegion[]} regions - Destination region collection.
+     * @param {number[]} axis - Signed direction components.
+     * @param {Array<{normal:Vector3,vertices:Vector3[]}>} surfaces - Surfaces sharing that direction.
+     * @returns {void}
+     */
+    static #addRegion(regions, axis, surfaces) {
+        const direction = new Vector3(...axis).normalize();
+        regions.push({ id: axis.join(","), direction, surfaces, kind: ["", "face", "edge", "corner"][axis.filter(Boolean).length] });
+    }
+
+    /**
+     * 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
+     * @static
+     * @param {number|null} start - Initial extent.
+     * @param {number} end - Destination extent.
+     * @param {number} fallback - Initial extent when absent.
+     * @param {number} eased - Eased transition fraction from 0 to 1.
+     * @returns {number}
+     */
+    static #interpolateExtent(start, end, fallback, eased) {
+        return (start ?? fallback) + (end - (start ?? fallback)) * eased;
+    }
+
+    /**
+     * Projects a cube-space vertex into the overlay SVG using the effective camera projection.
+     * @private
+     * @static
+     * @param {Vector3} vertex - Cube-space vertex.
+     * @param {ViewCubeProjection} projection - Current virtual cube projection.
+     * @returns {{x:number,y:number}}
+     */
+    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 };
+    }
+
+    /**
+     * Updates surface visibility and projected polygon points for the current camera orientation.
+     * @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}>}}
+     */
+    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 };
+    }
+
     /**
      * Converts a quaternion into a new rotation matrix without changing the quaternion.
      * @private
@@ -390,6 +472,37 @@ export default class BabylonJSViewCubeController {
         this.#host.onLayout?.(cubeHeight, sceneHeight);
     }
 
+    /**
+     * Registers an overlay or canvas listener and retains its removal callback for disposal.
+     * @private
+     * @param {EventTarget} element - Event source.
+     * @param {string} name - DOM event name.
+     * @param {EventListener} handler - Handler to register.
+     * @returns {void}
+     */
+    #addListener(element, name, handler) {
+        element.addEventListener(name, handler);
+        this.#listeners.push(() => element.removeEventListener(name, handler));
+    }
+
+    /**
+     * Updates hover feedback for every surface and the outline of one region.
+     * @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) {
+            return;
+        }
+        for (const surface of node.surfaces) {
+            surface.polygon.toggleAttribute("data-hover", active);
+        }
+        node.outline.toggleAttribute("data-hover", active);
+    }
+
     /**
      * 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.
@@ -404,19 +517,10 @@ export default class BabylonJSViewCubeController {
         if (id === this.#hover) {
             return;
         }
-        const update = (key, active) => {
-            const node = this.#nodes.get(key);
-            if (!node) {
-                return;
-            }
-            for (const surface of node.surfaces) {
-                surface.polygon.toggleAttribute("data-hover", active);
-            }
-            node.outline.toggleAttribute("data-hover", active);
-        };
-        update(this.#hover, false);
+
+        this.#setRegionHover(this.#hover, false);
         this.#hover = id;
-        update(id, true);
+        this.#setRegionHover(id, true);
     }
 
     /**
@@ -539,12 +643,12 @@ export default class BabylonJSViewCubeController {
         const position = target.subtract(forward.scale(distance));
         this.#writePose(t.camera, position, target, distance, t.fit);
         if (t.mode === 1) {
-            const lerp = (start, end, fallback) => (start ?? fallback) + (end - (start ?? fallback)) * eased;
+
             const viewport = this.#host.getViewport();
-            t.camera.orthoLeft = lerp(t.start.left, -t.fit.halfWidth, -viewport.width / 2);
-            t.camera.orthoRight = lerp(t.start.right, t.fit.halfWidth, viewport.width / 2);
-            t.camera.orthoBottom = lerp(t.start.bottom, -t.fit.halfHeight, -viewport.height / 2);
-            t.camera.orthoTop = lerp(t.start.top, t.fit.halfHeight, viewport.height / 2);
+            t.camera.orthoLeft = BabylonJSViewCubeController.#interpolateExtent(t.start.left, -t.fit.halfWidth, -viewport.width / 2, eased);
+            t.camera.orthoRight = BabylonJSViewCubeController.#interpolateExtent(t.start.right, t.fit.halfWidth, viewport.width / 2, eased);
+            t.camera.orthoBottom = BabylonJSViewCubeController.#interpolateExtent(t.start.bottom, -t.fit.halfHeight, -viewport.height / 2, eased);
+            t.camera.orthoTop = BabylonJSViewCubeController.#interpolateExtent(t.start.top, t.fit.halfHeight, viewport.height / 2, eased);
         }
         if (p === 1) {
             this.cancel();
@@ -605,22 +709,10 @@ export default class BabylonJSViewCubeController {
             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 project = (vertex) => {
-                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 };
-            };
-            const draw = (surface) => {
-                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(project);
-                surface.polygon.setAttribute("points", points.map((p) => `${p.x},${p.y}`).join(" "));
-                return { shown, points };
-            };
+            const projection = { view, perspective, depthSign, eyeDistance };
             if (geometryChanged) {
                 for (const surface of this.#shell) {
-                    draw(surface);
+                    BabylonJSViewCubeController.#drawSurface(surface, projection);
                 }
             }
             const towardObserver = Vector3.TransformNormal(new Vector3(0, 0, -depthSign), this.#rotationMatrix(pose.rotation)).normalize();
@@ -632,7 +724,7 @@ export default class BabylonJSViewCubeController {
             // 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", translate("prefViewer.viewCube.title", { locale }));
+                this.#svg.setAttribute("aria-label", I18n.translate("prefViewer.viewCube.title", { locale }));
             }
             for (const r of this.#regions) {
                 const node = this.#nodes.get(r.id);
@@ -640,7 +732,7 @@ export default class BabylonJSViewCubeController {
                 const names = parts
                     .map((s, i) =>
                         s
-                            ? translate(
+                            ? I18n.translate(
                                   `prefViewer.viewCube.${
                                       [
                                           ["right", "left"],
@@ -656,7 +748,7 @@ export default class BabylonJSViewCubeController {
                 let visible = false;
                 const outlineSegments = [];
                 for (const surface of node.surfaces) {
-                    const { shown, points } = geometryChanged ? draw(surface) : { shown: surface.polygon.style.display !== "none", points: [] };
+                    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";

package/src/file-storage.js

@@ -130,6 +130,12 @@ export default class FileStorage {
     #maxQuotaEvictionRetries = 5; // max retries after quota error
     #lastCleanupAt = 0; // timestamp of last automatic cleanup run
 
+    /**
+     * Configures the file-cache database and object store; opening is deferred until storage is used.
+     * @public
+     * @param {string} [dbName="FilesDB"] - IndexedDB cache database name.
+     * @param {string} [osName="FilesObjectStore"] - Object store for cached files.
+     */
     constructor(dbName = "FilesDB", osName = "FilesObjectStore") {
         this.dbName = dbName; // database name
         this.osName = osName; // object store name used for file cache
@@ -447,6 +453,7 @@ export default class FileStorage {
      * @private
      * @param {IDBDatabase} db IndexedDB database instance
      * @param {String} osName Object store name
+     * @returns {void}
      */
     #createObjectStore(db, osName) {
         if (!db.objectStoreNames.contains(osName)) {
@@ -466,6 +473,12 @@ export default class FileStorage {
         const self = this;
         try {
             return await openDB(this.dbName, this.#dbVersion, {
+                /**
+                 * Creates the configured cache object store during an IndexedDB schema upgrade.
+                 * @private
+                 * @param {IDBDatabase} db - Database being upgraded.
+                 * @returns {void}
+                 */
                 upgrade(db) {
                     self.#createObjectStore(db, self.osName);
                 },