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

package/src/babylonjs-ar-glass.js

@@ -0,0 +1,128 @@
+import { Material } from "@babylonjs/core/Materials/material.js";
+import MaterialUtils from "./material-utils.js";
+
+/**
+ * Owns reversible alpha-glass overrides for one model during native AR.
+ * Physical transmission cannot sample the compositor camera image in this viewer's XR path.
+ * Snapshots shared materials once, including MultiMaterial slots; sync on entry/frames and restore on exit.
+ * Leaves colors, textures, reflection parameters, material references and ordinary alpha/opaque materials intact.
+ * The scalar opacity is an approximation, not physical camera refraction or transmission-texture evaluation.
+ * Call restore before replacing/releasing the owning model. Shared textures/materials are never disposed here.
+ */
+export default class BabylonJSARGlass {
+    #materials = new Map();
+    static #MIN_GLASS_OPACITY = 0.28;
+    static #TRANSMISSION_REDUCTION = 0.65;
+
+    /**
+     * Bounds a finite material factor, using the supplied fallback for invalid/missing values.
+     * @param {number|undefined} value - Candidate alpha or transmission factor.
+     * @param {number} [fallback=1] - Value used when the candidate is not finite.
+     * @returns {number} A factor in [0, 1].
+     */
+    static #factor(value, fallback = 1) {
+        return Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : fallback;
+    }
+
+    /**
+     * Collects unique referenced materials and nested multi-material slots, tolerating repeated/cyclic slots.
+     * @param {import("@babylonjs/core").Material|null} material - Mesh or sub-material reference.
+     * @param {Set<import("@babylonjs/core").Material>} used - Current model's material references.
+     * @returns {void}
+     */
+    #collect(material, used) {
+        if (!material || used.has(material)) {
+            return;
+        }
+        used.add(material);
+        for (const child of material.subMaterials ?? []) {
+            this.#collect(child, used);
+        }
+    }
+
+    /**
+     * Snapshots physical glass and switches it to alpha blending without depth occlusion.
+     * Linked refraction uses alpha as inverse transmission, so it is not reused as geometric opacity.
+     * Retains a disposal observer only while the snapshot is owned; disposed materials are forgotten untouched.
+     * @param {import("@babylonjs/core").PBRMaterial} material - Current physical glass not already adapted.
+     * @returns {void} Does not allocate/dispose materials or textures or modify color/reflection properties.
+     */
+    #adapt(material) {
+        const sub = material.subSurface;
+        const alpha = BabylonJSARGlass.#factor(material.alpha);
+        const linked = sub.isRefractionEnabled && sub.linkRefractionWithTransparency;
+        const transmission = Math.max(
+            sub.isRefractionEnabled ? BabylonJSARGlass.#factor(sub.refractionIntensity) * (linked ? 1 - alpha : 1) : 0,
+            sub.isTranslucencyEnabled ? BabylonJSARGlass.#factor(sub.translucencyIntensity) : 0);
+        const saved = {
+            alpha: material.alpha, transparencyMode: material.transparencyMode,
+            disableDepthWrite: material.disableDepthWrite, forceDepthWrite: material.forceDepthWrite,
+            needDepthPrePass: material.needDepthPrePass,
+            isRefractionEnabled: sub.isRefractionEnabled, isTranslucencyEnabled: sub.isTranslucencyEnabled,
+            observer: material.onDisposeObservable.addOnce(() => this.#materials.delete(material)),
+        };
+        this.#materials.set(material, saved);
+        sub.isRefractionEnabled = false;
+        sub.isTranslucencyEnabled = false;
+        material.alpha = (linked ? 1 : alpha) * Math.max(BabylonJSARGlass.#MIN_GLASS_OPACITY,
+            1 - transmission * BabylonJSARGlass.#TRANSMISSION_REDUCTION);
+        material.transparencyMode = Material.MATERIAL_ALPHABLEND;
+        material.disableDepthWrite = true;
+        material.forceDepthWrite = false;
+        material.needDepthPrePass = false;
+    }
+
+    /**
+     * Restores one still-live material's exact saved values and releases its disposal subscription.
+     * @param {import("@babylonjs/core").Material} material - Material previously owned by this adapter.
+     * @returns {void} No-op for already restored/disposed materials.
+     */
+    #restoreMaterial(material) {
+        const saved = this.#materials.get(material);
+        if (!saved) {
+            return;
+        }
+        this.#materials.delete(material);
+        material.onDisposeObservable.remove(saved.observer);
+        material.alpha = saved.alpha;
+        material.transparencyMode = saved.transparencyMode;
+        material.disableDepthWrite = saved.disableDepthWrite;
+        material.forceDepthWrite = saved.forceDepthWrite;
+        material.needDepthPrePass = saved.needDepthPrePass;
+        material.subSurface.isRefractionEnabled = saved.isRefractionEnabled;
+        material.subSurface.isTranslucencyEnabled = saved.isTranslucencyEnabled;
+    }
+
+    /**
+     * Adapts physical glass actually referenced by current model meshes, including material swaps during AR.
+     * Restores materials no longer referenced and does not compound opacity on repeated XR frames.
+     * @param {import("@babylonjs/core").AssetContainer|null} asset - Current model, or null to restore everything.
+     * @returns {void} Ordinary alpha/opaque materials and unrelated scene materials are not changed.
+     */
+    sync(asset) {
+        const used = new Set();
+        for (const mesh of asset?.meshes ?? []) {
+            this.#collect(mesh.material, used);
+        }
+        for (const material of this.#materials.keys()) {
+            if (!used.has(material)) {
+                this.#restoreMaterial(material);
+            }
+        }
+        for (const material of used) {
+            if (!this.#materials.has(material) && MaterialUtils.isPrefViewerPhysicalGlassMaterial(material)) {
+                this.#adapt(material);
+            }
+        }
+    }
+
+    /**
+     * Restores all remaining material snapshots and removes their observers on exit, cancellation or teardown.
+     * @returns {void} Idempotent; does not dispose any shared resource.
+     */
+    restore() {
+        for (const material of this.#materials.keys()) {
+            this.#restoreMaterial(material);
+        }
+    }
+}

package/src/babylonjs-ar-placement-feedback.js

@@ -0,0 +1,449 @@
+import { Mesh } from "@babylonjs/core/Meshes/mesh.js";
+import { VertexData } from "@babylonjs/core/Meshes/mesh.vertexData.js";
+import { TransformNode } from "@babylonjs/core/Meshes/transformNode.js";
+import { StandardMaterial } from "@babylonjs/core/Materials/standardMaterial.js";
+import { Material } from "@babylonjs/core/Materials/material.js";
+import { ImageProcessingConfiguration } from "@babylonjs/core/Materials/imageProcessingConfiguration.js";
+import { Constants } from "@babylonjs/core/Engines/constants.js";
+import { Color3 } from "@babylonjs/core/Maths/math.color.js";
+import { Vector3 } from "@babylonjs/core/Maths/math.vector.js";
+import { PrefViewerStyleVariables } from "./styles.js";
+
+/**
+ * Owns reusable planar gesture glyphs; each arrow is one joined shaft/head surface with an exterior-only border.
+ * Arrow geometry has no overlapping shaft/head or border/fill faces, including faint hidden passes.
+ * Frozen detected-floor axes orient glyphs and their movement emphasis independently of subsequent camera/model yaw.
+ * Primary-color emphasis follows the owning viewer canvas and marks translation/rotation direction and committed floor taps.
+ * Centralized appearance properties control opaque foregrounds, translucent outlines and a faint occluded pass.
+ * Isolated material image processing preserves UI sRGB colors without scene exposure/tone mapping or fog.
+ * Hidden portions remain readable without clearing scene depth or changing model transparency. Dispose before releasing the owning scene.
+ */
+export default class BabylonJSARPlacementFeedback {
+    /** @type {string} Black outline color for all glyphs. */
+    #outlineColor = "#000000";
+    /** @type {string} Normal reticle/arrow foreground color. */
+    #indicatorColor = "#ffffff";
+    /** @type {string} Accent follows the primary style, refreshed for each gesture/frame. */
+    #highlightColor = PrefViewerStyleVariables.colorPrimary;
+    /** @type {number} Normal outline opacity, in the inclusive range 0..1. */
+    #outlineOpacity = .4;
+    /** @type {number} Normal/primary foreground opacity, in the inclusive range 0..1. */
+    #indicatorOpacity = 1;
+    /** @type {number} Half the 24 cm triangular arrowhead base width, in metres. */
+    #headHalfWidth = .12;
+    /** @type {number} Half the 8 cm circle stroke width, in metres. */
+    #reticleCircleHalfWidth = .04;
+    /** @type {number} Half the 2 cm cross stroke width, in metres. */
+    #reticleCrossHalfWidth = .01;
+    /** @type {number} Exterior reticle-border offset, in metres. */
+    #reticleOutlineOffset = .01;
+    /** @type {number} Half the 8 cm arrow shaft width, in metres. */
+    #arrowStrokeHalfWidth = .04;
+    /** @type {number} Perpendicular exterior arrow-border offset, in metres. */
+    #arrowOutlineOffset = .01;
+    /** @type {number} Arrowhead tip-to-base length in metres. */
+    #arrowHeadLength = .10;
+    /** @type {number} Frozen detected-floor yaw; movement feedback uses the same axes. */
+    #floorYaw = 0;
+
+    #scene;
+    #root = null;
+    #groups = {};
+    #parts = [];
+    #materials = [];
+    #ghostMaterials = [];
+    #expires = 0;
+    static #OCCLUDED_OPACITY_FACTOR = .22;
+
+    /**
+     * Retains the scene without allocating meshes until an eligible interaction.
+     * @param {import("@babylonjs/core").Scene} scene - Owning render/depth context.
+     */
+    constructor(scene) {
+        this.#scene = scene;
+    }
+
+    /**
+     * Adds a non-pickable normal/occluded pair sharing geometry and scene depth, without owning model resources.
+     * Both passes blend after opaque scene geometry and never write depth; explicit order preserves outlines.
+     * @param {string} mode - Gesture group.
+     * @param {Mesh} mesh - Newly allocated normal-pass mesh transferred to this owner.
+     * @param {number} shade - Default color index (0 outline, 1 foreground).
+     * @param {?number} [direction=null] - Translation quadrant or signed XZ arc direction.
+     * @param {string} [geometry="stroke"] - Semantic geometry kind for diagnostics/tests.
+     * @returns {void}
+     */
+    #attach(mode, mesh, shade, direction = null, geometry = "stroke") {
+        mesh.parent = this.#groups[mode];
+        mesh.material = this.#materials[shade];
+        const ghost = mesh.clone(`${mesh.name}-occluded`, mesh.parent, true);
+        ghost.material = this.#ghostMaterials[shade];
+        for (const [pass, part] of [["visible", mesh], ["occluded", ghost]]) {
+            part.isPickable = false;
+            part.doNotSerialize = true;
+            part.alphaIndex = shade;
+            part.metadata = { prefViewerARFeedback: true, mode, direction, pass, shade, geometry };
+        }
+        this.#parts.push({ mode, direction, shade, mesh, ghost });
+    }
+
+    /**
+     * Creates the closed planar reticle band and an exterior-only contour on both sides of its stroke.
+     * @param {Vector3[]} path - Ring centreline with repeated closing endpoint.
+     * @returns {void} Owns indexed meshes without overlapping fill/border faces.
+     */
+    #ring(path) {
+        const points = path.slice(0, -1);
+        const vertices = [];
+        for (const halfWidth of [this.#reticleCircleHalfWidth, this.#reticleCircleHalfWidth + this.#reticleOutlineOffset]) {
+            for (let i = 0; i < points.length; i++) {
+                const point = points[i];
+                const incoming = point.subtract(points[(i + points.length - 1) % points.length]).normalize();
+                const outgoing = points[(i + 1) % points.length].subtract(point).normalize();
+                const side = new Vector3(-outgoing.z, 0, outgoing.x);
+                const miter = new Vector3(-incoming.z, 0, incoming.x).add(side).normalize();
+                const offset = miter.scale(halfWidth / Vector3.Dot(miter, side));
+                vertices.push(point.add(offset), point.subtract(offset));
+            }
+        }
+        const fill = [];
+        const border = [];
+        const count = points.length * 2;
+        for (let i = 0; i < points.length; i++) {
+            const a = i * 2;
+            const b = ((i + 1) % points.length) * 2;
+            fill.push(a, b, a + 1, a + 1, b, b + 1);
+            for (const side of [0, 1]) {
+                border.push(a + side, b + side, a + side + count,
+                    b + side, b + side + count, a + side + count);
+            }
+        }
+        for (const [points, triangles, shade] of [[vertices, border, 0], [vertices.slice(0, count), fill, 1]]) {
+            const data = new VertexData();
+            data.positions = points.flatMap(point => [point.x, 0, point.z]);
+            data.normals = points.flatMap(() => [0, 1, 0]);
+            data.indices = triangles;
+            const mesh = new Mesh("PrefViewerARFeedback-tap-ring", this.#scene);
+            data.applyToMesh(mesh);
+            this.#attach("tap", mesh, shade, null, "ring");
+        }
+    }
+
+    /**
+     * Creates a single joined cross with a 2 cm stroke and an exterior-only 1 cm contour.
+     * @returns {void} The centre is triangulated once, so confirmation/hidden alpha cannot accumulate there.
+     */
+    #cross() {
+        const w = this.#reticleCrossHalfWidth;
+        const length = .08;
+        const points = [[-w,-length],[w,-length],[w,-w],[length,-w],[length,w],[w,w],
+            [w,length],[-w,length],[-w,w],[-length,w],[-length,-w],[-w,-w]]
+            .map(([x,z]) => new Vector3(x,0,z));
+        this.#silhouette("tap", points, points.map((_, i) => i), null, "cross", this.#reticleOutlineOffset);
+    }
+
+    /**
+     * Offsets every edge of a simple planar arrow silhouette outward by the configured distance.
+     * Intersecting adjacent offset lines gives mitered convex/concave corners and a true perpendicular border.
+     * @param {Vector3[]} points - Ordered, non-repeated boundary vertices with no degenerate edges.
+     * @param {number} offset - Perpendicular exterior distance in metres.
+     * @returns {Vector3[]} Corresponding outer vertices; arrow-size constraints keep the offset simple.
+     */
+    #outerBoundary(points, offset) {
+        const area = points.reduce((sum, point, i) => {
+            const next = points[(i + 1) % points.length];
+            return sum + point.x * next.z - next.x * point.z;
+        }, 0);
+        const orientation = area < 0 ? 1 : -1;
+        return points.map((point, i) => {
+            const incoming = point.subtract(points[(i + points.length - 1) % points.length]).normalize();
+            const outgoing = points[(i + 1) % points.length].subtract(point).normalize();
+            const first = new Vector3(-incoming.z, 0, incoming.x).scale(orientation);
+            const second = new Vector3(-outgoing.z, 0, outgoing.x).scale(orientation);
+            const miter = first.add(second).normalize();
+            return point.add(miter.scale(offset / Vector3.Dot(miter, second)));
+        });
+    }
+
+    /**
+     * Triangulates a simple arrow silhouette by clipping convex ears, preserving concave shaft/head junctions.
+     * @param {Vector3[]} points - Ordered XZ polygon without repeated endpoints or intersecting edges.
+     * @returns {number[]} Triangle indices into the supplied boundary, with no overlapping interiors.
+     * @throws {Error} If an invalid/self-intersecting boundary cannot be triangulated.
+     */
+    #triangulate(points) {
+        const remaining = points.map((_, index) => index);
+        const triangles = [];
+        const area = points.reduce((sum, p, i) => {
+            const q = points[(i + 1) % points.length];
+            return sum + p.x * q.z - q.x * p.z;
+        }, 0);
+        const orientation = Math.sign(area);
+        /** @param {Vector3} a - First point. @param {Vector3} b - Second point. @param {Vector3} c - Third point. @returns {number} Oriented 2D cross product. */
+        const cross = (a, b, c) => orientation * ((b.x - a.x) * (c.z - a.z) - (b.z - a.z) * (c.x - a.x));
+        while (remaining.length > 3) {
+            let clipped = false;
+            for (let i = 0; i < remaining.length; i++) {
+                const a = remaining[(i + remaining.length - 1) % remaining.length];
+                const b = remaining[i];
+                const c = remaining[(i + 1) % remaining.length];
+                if (cross(points[a], points[b], points[c]) <= 1e-10) {
+                    continue;
+                }
+                const occupied = remaining.some(index => index !== a && index !== b && index !== c
+                    && cross(points[a], points[b], points[index]) >= -1e-10
+                    && cross(points[b], points[c], points[index]) >= -1e-10
+                    && cross(points[c], points[a], points[index]) >= -1e-10);
+                if (!occupied) {
+                    triangles.push(a, b, c);
+                    remaining.splice(i, 1);
+                    clipped = true;
+                    break;
+                }
+            }
+            if (!clipped) {
+                throw new Error("PrefViewer: invalid AR arrow boundary");
+            }
+        }
+        triangles.push(...remaining);
+        return triangles;
+    }
+
+    /**
+     * Creates one connected, non-overlapping arrow fill and one exterior-only border ring.
+     * Retains a 10 cm head length and 24 cm head base. Trim the shaft at the head base and triangulate the complete concave silhouette as a single polygon.
+     * The contour is an offset of the complete silhouette, with no internal seam or black backing under the fill.
+     * @param {string} mode - Translation or rotation group.
+     * @param {Vector3[]} path - Shaft centreline continuing toward the head; only points behind its base are retained.
+     * @param {Vector3} tip - Triangle tip.
+     * @param {Vector3} tangent - Unit forward direction of the head.
+     * @param {number} direction - Translation quadrant or signed rotation sense.
+     * @returns {void} Owns planar fill/border meshes and shared-geometry occluded counterparts.
+     */
+    #arrow(mode, path, tip, tangent, direction) {
+        const base = tip.subtract(tangent.scale(this.#arrowHeadLength));
+        // A sufficiently long final segment avoids tiny reflex edges whose border would fold at the neck.
+        const centres = path.filter(point => Vector3.Dot(tip.subtract(point), tangent) > this.#arrowHeadLength + 1e-6
+            && Vector3.Distance(point, base) > this.#arrowStrokeHalfWidth * 2);
+        centres.push(base);
+        const side = new Vector3(-tangent.z, 0, tangent.x);
+        const vertices = [];
+        for (let i = 0; i < centres.length; i++) {
+            const previous = centres[Math.max(0, i - 1)];
+            const next = centres[Math.min(centres.length - 1, i + 1)];
+            const incoming = (i ? centres[i].subtract(previous) : next.subtract(centres[i])).normalize();
+            const outgoing = i === centres.length - 1 ? tangent : next.subtract(centres[i]).normalize();
+            const normal = new Vector3(-outgoing.z, 0, outgoing.x);
+            const miter = new Vector3(-incoming.z, 0, incoming.x).add(normal).normalize();
+            const offset = i === centres.length - 1 ? side.scale(this.#arrowStrokeHalfWidth)
+                : miter.scale(this.#arrowStrokeHalfWidth / Vector3.Dot(miter, normal));
+            vertices.push(centres[i].add(offset), centres[i].subtract(offset));
+        }
+        const head = vertices.length;
+        vertices.push(base.add(side.scale(this.#headHalfWidth)), tip, base.subtract(side.scale(this.#headHalfWidth)));
+        const boundaryIndices = [];
+        for (let i = 0; i < head; i += 2) {
+            boundaryIndices.push(i);
+        }
+        boundaryIndices.push(head, head + 1, head + 2);
+        for (let i = head - 1; i >= 1; i -= 2) {
+            boundaryIndices.push(i);
+        }
+        this.#silhouette(mode, vertices, boundaryIndices, direction, "arrow", this.#arrowOutlineOffset);
+    }
+
+    /**
+     * Triangulates one planar silhouette and its non-overlapping exterior contour.
+     * @param {string} mode - Gesture group.
+     * @param {Vector3[]} vertices - Fill vertices, including all ordered boundary points.
+     * @param {number[]} boundaryIndices - Boundary order into fill vertices.
+     * @param {?number} direction - Directional highlight identifier, or null for a reticle.
+     * @param {string} geometry - Semantic glyph kind.
+     * @param {number} offset - Perpendicular border distance in metres.
+     * @returns {void} Owns foreground/border mesh pairs with shared occluded geometry.
+     */
+    #silhouette(mode, vertices, boundaryIndices, direction, geometry, offset) {
+        const inner = boundaryIndices.map(index => vertices[index]);
+        const indices = this.#triangulate(inner).map(index => boundaryIndices[index]);
+        const outer = this.#outerBoundary(inner, offset);
+        const borderVertices = [...inner, ...outer];
+        const borderIndices = [];
+        for (let i = 0; i < inner.length; i++) {
+            const next = (i + 1) % inner.length;
+            borderIndices.push(i, next, i + inner.length, next, next + inner.length, i + inner.length);
+        }
+        for (const [points, triangles, shade] of [[borderVertices, borderIndices, 0], [vertices, indices, 1]]) {
+            const data = new VertexData();
+            data.positions = points.flatMap(point => [point.x, 0, point.z]);
+            data.indices = triangles;
+            data.normals = points.flatMap(() => [0, 1, 0]);
+            const mesh = new Mesh(`PrefViewerARFeedback-${mode}-arrow`, this.#scene);
+            data.applyToMesh(mesh);
+            this.#attach(mode, mesh, shade, direction, geometry);
+        }
+    }
+
+    /**
+     * Allocates reusable glyphs and two depth-filtered material sets once.
+     * Visible parts use class-configured outline/foreground opacity; hidden parts multiply it by a faintness factor.
+     * LEQUAL/GREATER share scene depth. A private disabled image-processing configuration prevents inherited
+     * post-process linear output, exposure/ACES tone mapping and fog from altering UI sRGB colors.
+     * Model materials and the scene image-processing configuration remain unchanged.
+     * @returns {void} Does not change scene clearing, rendering groups or model materials.
+     */
+    #ensure() {
+        if (this.#root) {
+            return;
+        }
+        this.#root = new TransformNode("PrefViewerARFeedback", this.#scene);
+        this.#root.doNotSerialize = true;
+        this.#root.metadata = { prefViewerARFeedback: true };
+        const imageProcessing = new ImageProcessingConfiguration();
+        imageProcessing.isEnabled = false;
+        for (const [ghost, materials] of [[false, this.#materials], [true, this.#ghostMaterials]]) {
+            for (const [color, opacity] of [[this.#outlineColor, this.#outlineOpacity],
+                [this.#indicatorColor, this.#indicatorOpacity], [this.#highlightColor, this.#indicatorOpacity]]) {
+                const material = new StandardMaterial("PrefViewerARFeedback", this.#scene);
+                material.disableLighting = true;
+                material.fogEnabled = false;
+                material.imageProcessingConfiguration = imageProcessing;
+                material.emissiveColor = Color3.FromHexString(color);
+                material.alpha = opacity * (ghost ? BabylonJSARPlacementFeedback.#OCCLUDED_OPACITY_FACTOR : 1);
+                material.transparencyMode = Material.MATERIAL_ALPHABLEND;
+                material.disableDepthWrite = true;
+                material.backFaceCulling = false;
+                material.depthFunction = ghost ? Constants.GREATER : Constants.LEQUAL;
+                materials.push(material);
+            }
+        }
+        for (const name of ["tap", "drag", "rotate"]) {
+            const group = new TransformNode(`PrefViewerARFeedback-${name}`, this.#scene);
+            group.parent = this.#root;
+            group.doNotSerialize = true;
+            group.metadata = { prefViewerARFeedback: true };
+            this.#groups[name] = group;
+        }
+        const circle = Array.from({ length: 49 }, (_, i) => new Vector3(Math.cos(i * Math.PI / 24) * .2, 0, Math.sin(i * Math.PI / 24) * .2));
+        this.#ring(circle);
+        this.#cross();
+        for (let i = 0; i < 4; i++) {
+            const angle = i * Math.PI / 2;
+            const tangent = new Vector3(Math.cos(angle), 0, Math.sin(angle));
+            this.#arrow("drag", [tangent.scale(.12), tangent.scale(.4)], tangent.scale(.4), tangent, i);
+        }
+        for (const direction of [-1, 1]) {
+            const arc = Array.from({ length: 25 }, (_, i) => {
+                const angle = direction * i * Math.PI / 30;
+                return new Vector3(Math.cos(angle) * .32, 0, Math.sin(angle) * .32);
+            });
+            const angle = direction * 24 * Math.PI / 30;
+            const tangent = new Vector3(-Math.sin(angle), 0, Math.cos(angle)).scale(direction);
+            this.#arrow("rotate", arc, arc.at(-1), tangent, direction);
+        }
+        this.hide();
+    }
+
+    /**
+     * Colors foreground and faint counterparts together while retaining dark outlines.
+     * @param {object} part - Owned visual pair.
+     * @param {boolean} highlighted - Whether this foreground uses the primary color.
+     * @returns {void}
+     */
+    #shade(part, highlighted) {
+        const shade = part.shade && highlighted ? 2 : part.shade;
+        part.mesh.material = this.#materials[shade];
+        part.ghost.material = this.#ghostMaterials[shade];
+    }
+
+    /**
+     * Retains a frozen floor-axis yaw for every glyph without moving the model or opening feedback.
+     * @param {number} [yaw=0] - Scene-space floor yaw; invalid values use reference-space axes.
+     * @returns {void} Updates the existing root, if allocated; reset at session end.
+     */
+    setFloorYaw(yaw = 0) {
+        this.#floorYaw = Number.isFinite(yaw) ? yaw : 0;
+        if (this.#root) {
+            this.#root.rotation.y = this.#floorYaw;
+        }
+    }
+
+    /**
+     * Shows a retained-plane destination/gesture; markers are not new physical surface evidence.
+     * @param {"tap"|"drag"|"rotate"} mode - Gesture group.
+     * @param {Vector3} point - Bottom anchor or floor candidate.
+     * @param {?Vector3} [movement=null] - Horizontal drag displacement.
+     * @param {number} [rotationDelta=0] - Applied scene-space yaw in radians; sign selects a curved arrow.
+     * Movement emphasis is transformed into frozen floor axes before choosing the matching arrow.
+     * @returns {void} Reads the owning canvas primary style (global fallback for standalone/headless scenes) and reuses geometry/materials, cancelling confirmation expiry.
+     */
+    show(mode, point, movement = null, rotationDelta = 0) {
+        const canvas = this.#scene.getEngine().getRenderingCanvas?.();
+        const primary = canvas?.ownerDocument?.defaultView?.getComputedStyle(canvas).getPropertyValue("--pref-viewer-color-primary").trim();
+        this.#highlightColor = /^#[0-9a-f]{6}$/i.test(primary ?? "") ? primary : PrefViewerStyleVariables.colorPrimary;
+        this.#ensure();
+        for (const materials of [this.#materials, this.#ghostMaterials]) {
+            materials[2].emissiveColor.copyFrom(Color3.FromHexString(this.#highlightColor));
+        }
+        this.#expires = 0;
+        this.#root.rotation.y = this.#floorYaw;
+        this.#root.position.copyFrom(point);
+        this.#root.position.y += .035;
+        this.#root.setEnabled(true);
+        for (const [name, group] of Object.entries(this.#groups)) {
+            group.setEnabled(name === mode);
+        }
+        let direction = null;
+        if (mode === "drag" && movement && Math.hypot(movement.x, movement.z) > .0001) {
+            const x = Math.cos(this.#floorYaw) * movement.x - Math.sin(this.#floorYaw) * movement.z;
+            const z = Math.sin(this.#floorYaw) * movement.x + Math.cos(this.#floorYaw) * movement.z;
+            direction = (Math.round(Math.atan2(z, x) / (Math.PI / 2)) + 4) % 4;
+        } else if (mode === "rotate" && Math.abs(rotationDelta) > .0001) {
+            // Positive quaternion yaw turns +X toward -Z, opposite the arc's XZ parameter angle.
+            direction = -Math.sign(rotationDelta);
+        }
+        for (const part of this.#parts) {
+            this.#shade(part, mode !== "tap" && part.mode === mode && direction !== null && part.direction === direction);
+        }
+    }
+
+    /**
+     * Highlights a committed tap reticle with the primary style for 500 ms without scheduling timers.
+     * @param {Vector3} point - Committed floor destination.
+     * @returns {void}
+     */
+    confirm(point) {
+        this.show("tap", point);
+        for (const part of this.#parts) {
+            this.#shade(part, part.mode === "tap");
+        }
+        this.#expires = performance.now() + 500;
+    }
+
+    /** @returns {void} Expires confirmation during the owning XR frame loop. */
+    update() {
+        if (this.#expires && performance.now() >= this.#expires) {
+            this.hide();
+        }
+    }
+
+    /** @returns {void} Clears visible and occluded passes on release/cancellation/tracking loss. */
+    hide() {
+        this.#expires = 0;
+        this.#root?.setEnabled(false);
+    }
+
+    /** @returns {void} Releases owned mesh pairs and both material sets, retaining no model resources. */
+    dispose() {
+        this.#root?.dispose(false);
+        for (const material of [...this.#materials, ...this.#ghostMaterials]) {
+            material.dispose();
+        }
+        this.#root = null;
+        this.#groups = {};
+        this.#parts = [];
+        this.#materials = [];
+        this.#ghostMaterials = [];
+        this.#expires = 0;
+        this.#floorYaw = 0;
+    }
+}