three-cad-viewer 4.3.8 → 4.3.9

package/dist/three-cad-viewer.js

@@ -81596,9 +81596,13 @@ void main() {
 	}
 	function isEqual(obj1, obj2, tol = 1e-9) {
 	    if (Array.isArray(obj1) && Array.isArray(obj2)) {
-	        return (obj1.length === obj2.length && obj1.every((v, i) => isEqual(v, obj2[i], tol)));
+	        return (obj1.length === obj2.length &&
+	            obj1.every((v, i) => isEqual(v, obj2[i], tol)));
 	    }
-	    else if (obj1 !== null && obj2 !== null && typeof obj1 === "object" && typeof obj2 === "object") {
+	    else if (obj1 !== null &&
+	        obj2 !== null &&
+	        typeof obj1 === "object" &&
+	        typeof obj2 === "object") {
 	        const rec1 = obj1;
 	        const rec2 = obj2;
 	        const keys1 = Object.keys(rec1);
@@ -81633,7 +81637,10 @@ void main() {
 	        gpuTracker.untrack("geometry", geometry);
 	        geometry.dispose();
 	        for (const attr of Object.values(geometry.attributes)) {
-	            if (attr && typeof attr === "object" && "dispose" in attr && typeof attr.dispose === "function") {
+	            if (attr &&
+	                typeof attr === "object" &&
+	                "dispose" in attr &&
+	                typeof attr.dispose === "function") {
 	                attr.dispose();
 	            }
 	        }
@@ -81642,12 +81649,25 @@ void main() {
 	/** All texture map property names on MaterialLike (for iteration) */
 	const MATERIAL_TEXTURE_KEYS = [
 	    // MeshStandardMaterial
-	    "map", "normalMap", "roughnessMap", "metalnessMap",
-	    "aoMap", "emissiveMap", "alphaMap", "bumpMap",
+	    "map",
+	    "normalMap",
+	    "roughnessMap",
+	    "metalnessMap",
+	    "aoMap",
+	    "emissiveMap",
+	    "alphaMap",
+	    "bumpMap",
 	    // MeshPhysicalMaterial
-	    "transmissionMap", "clearcoatMap", "clearcoatRoughnessMap", "clearcoatNormalMap",
-	    "thicknessMap", "specularIntensityMap", "specularColorMap",
-	    "sheenColorMap", "sheenRoughnessMap", "anisotropyMap",
+	    "transmissionMap",
+	    "clearcoatMap",
+	    "clearcoatRoughnessMap",
+	    "clearcoatNormalMap",
+	    "thicknessMap",
+	    "specularIntensityMap",
+	    "specularColorMap",
+	    "sheenColorMap",
+	    "sheenRoughnessMap",
+	    "anisotropyMap",
 	];
 	/**
 	 * Dispose a material and detach its texture references.
@@ -81776,14 +81796,16 @@ void main() {
 	 * Accepts Object3D to allow use in controls where camera type is broader.
 	 */
 	function isOrthographicCamera(obj) {
-	    return "isOrthographicCamera" in obj && obj.isOrthographicCamera === true;
+	    return ("isOrthographicCamera" in obj &&
+	        obj.isOrthographicCamera === true);
 	}
 	/**
 	 * Type guard to check if an object is a PerspectiveCamera.
 	 * Accepts Object3D to allow use in controls where camera type is broader.
 	 */
 	function isPerspectiveCamera(obj) {
-	    return "isPerspectiveCamera" in obj && obj.isPerspectiveCamera === true;
+	    return ("isPerspectiveCamera" in obj &&
+	        obj.isPerspectiveCamera === true);
 	}
 	/**
 	 * Type guard to check if an Object3D is a LineSegments2 (fat line).
@@ -81801,7 +81823,8 @@ void main() {
 	 * Type guard to check if a material is a MeshStandardMaterial.
 	 */
 	function isMeshStandardMaterial(material) {
-	    return "isMeshStandardMaterial" in material && material.isMeshStandardMaterial === true;
+	    return ("isMeshStandardMaterial" in material &&
+	        material.isMeshStandardMaterial === true);
 	}
 	const KeyMapper = new _KeyMapper();
 	class EventListenerManager {
@@ -82027,7 +82050,9 @@ void main() {
 	        if (mesh.userData.excludeFromZebra)
 	            return;
 	        // Store original material (handle array case by taking first)
-	        const currentMaterial = Array.isArray(mesh.material) ? mesh.material[0] : mesh.material;
+	        const currentMaterial = Array.isArray(mesh.material)
+	            ? mesh.material[0]
+	            : mesh.material;
 	        if (!this.originalMaterials.has(mesh.uuid)) {
 	            this.originalMaterials.set(mesh.uuid, currentMaterial);
 	        }
@@ -82039,7 +82064,8 @@ void main() {
 	            if (hasColor(currentMaterial)) {
 	                baseColor = currentMaterial.color.clone();
 	            }
-	            else if (isMeshStandardMaterial(currentMaterial) && currentMaterial.map) {
+	            else if (isMeshStandardMaterial(currentMaterial) &&
+	                currentMaterial.map) {
 	                // If there's a texture but no color, use white as base
 	                baseColor = new Color(1, 1, 1);
 	            }
@@ -82392,7 +82418,8 @@ void main() {
 	     * Skips MeshBasicMaterial and other non-PBR materials.
 	     */
 	    _forEachStandardMaterial(callback) {
-	        if (this.front && this.front.material instanceof MeshStandardMaterial) {
+	        if (this.front &&
+	            this.front.material instanceof MeshStandardMaterial) {
 	            callback(this.front.material);
 	        }
 	        // back can also be MeshStandardMaterial (e.g., for polygon rendering)
@@ -82407,9 +82434,7 @@ void main() {
 	    highlight(flag) {
 	        const hColor = this._getHighlightColor();
 	        // Find primary material (front face, vertices, or edges)
-	        const primaryMaterial = this.front?.material ||
-	            this.vertices?.material ||
-	            this.edgeMaterial;
+	        const primaryMaterial = this.front?.material || this.vertices?.material || this.edgeMaterial;
 	        if (primaryMaterial) {
 	            this.widen(flag);
 	            this._applyColorToMaterial(primaryMaterial, flag ? hColor : this.originalColor);
@@ -82555,12 +82580,29 @@ void main() {
 	                child1.material.visible = flag;
 	            }
 	        }
-	        if (this.back && this.renderback) {
-	            if (this._isStudioMode) {
-	                this.back.visible = flag;
+	        if (this.back) {
+	            // Hide-path: always hide the back when the shape is hidden, even
+	            // when !renderback. Otherwise a back face left visible by a prior
+	            // setBackVisible(true) (clip tab) would remain visible after the
+	            // front goes hidden, appearing as a ghost.
+	            // Show-path: only flip back to visible when renderback is set;
+	            // when !renderback, leave back.visible alone — the clip-tab's
+	            // setBackVisible() owns it.
+	            if (!flag) {
+	                if (this._isStudioMode) {
+	                    this.back.visible = false;
+	                }
+	                else {
+	                    this.back.material.visible = false;
+	                }
 	            }
-	            else {
-	                this.back.material.visible = flag;
+	            else if (this.renderback) {
+	                if (this._isStudioMode) {
+	                    this.back.visible = true;
+	                }
+	                else {
+	                    this.back.material.visible = true;
+	                }
 	            }
 	        }
 	    }
@@ -82774,10 +82816,16 @@ void main() {
 	            this._cadBackMaterial = this.back.material;
 	        }
 	        // Save original colors used by highlight/unhighlight
-	        this._cadOriginalColor = this.originalColor ? this.originalColor.clone() : null;
-	        this._cadOriginalBackColor = this.originalBackColor ? this.originalBackColor.clone() : null;
+	        this._cadOriginalColor = this.originalColor
+	            ? this.originalColor.clone()
+	            : null;
+	        this._cadOriginalBackColor = this.originalBackColor
+	            ? this.originalBackColor.clone()
+	            : null;
 	        // Save edge visibility state
-	        this._cadEdgesVisible = this.edgeMaterial ? this.edgeMaterial.visible : null;
+	        this._cadEdgesVisible = this.edgeMaterial
+	            ? this.edgeMaterial.visible
+	            : null;
 	        // --- Swap front material ---
 	        if (this.front && studioFront) {
 	            // Transfer per-object visibility to mesh.visible (NOT material.visible)
@@ -83294,12 +83342,18 @@ void main() {
 	 * @returns THREE.SRGBColorSpace or THREE.LinearSRGBColorSpace
 	 */
 	function getColorSpaceForMap(mapName) {
-	    return THREEJS_SRGB_MAPS.has(mapName) ? SRGBColorSpace : LinearSRGBColorSpace;
+	    return THREEJS_SRGB_MAPS.has(mapName)
+	        ? SRGBColorSpace
+	        : LinearSRGBColorSpace;
 	}
 
 	/** threejs-materials property keys that hold [r,g,b] color arrays (linear RGB). */
 	const COLOR_ARRAY_KEYS = new Set([
-	    "color", "specularColor", "sheenColor", "emissive", "attenuationColor",
+	    "color",
+	    "specularColor",
+	    "sheenColor",
+	    "emissive",
+	    "attenuationColor",
 	]);
 	/** Map from threejs-materials property names to Three.js texture map property names. */
 	const PROPERTY_TO_MAP = {
@@ -83374,7 +83428,7 @@ void main() {
 	     * Create a standard material for back faces with PBR properties.
 	     * Used for polygon rendering where back faces need full shading.
 	     */
-	    createBackFaceStandardMaterial({ color, alpha, polygonOffsetUnits = 2.0, visible = true }, label) {
+	    createBackFaceStandardMaterial({ color, alpha, polygonOffsetUnits = 2.0, visible = true, }, label) {
 	        const material = new MeshStandardMaterial({
 	            ...this._createBaseProps(alpha),
 	            color: color,
@@ -83392,7 +83446,7 @@ void main() {
 	     * Create a basic material for back faces (no lighting/PBR).
 	     * Used for shape rendering where back faces are simple fills.
 	     */
-	    createBackFaceBasicMaterial({ color, alpha, polygonOffsetUnits = 2.0, visible = true }, label) {
+	    createBackFaceBasicMaterial({ color, alpha, polygonOffsetUnits = 2.0, visible = true, }, label) {
 	        const material = new MeshBasicMaterial({
 	            ...this._createBaseProps(alpha),
 	            color: color,
@@ -83419,7 +83473,7 @@ void main() {
 	    /**
 	     * Create a fat line material (LineMaterial from Three.js examples).
 	     */
-	    createEdgeMaterial({ lineWidth, color, vertexColors = false, visible = true, resolution }, label) {
+	    createEdgeMaterial({ lineWidth, color, vertexColors = false, visible = true, resolution, }, label) {
 	        const material = new LineMaterial({
 	            linewidth: lineWidth,
 	            transparent: true,
@@ -83493,7 +83547,7 @@ void main() {
 	     * @param label - Optional label for GPU tracking
 	     * @returns Configured MeshPhysicalMaterial (or MeshBasicMaterial if unlit)
 	     */
-	    async createStudioMaterial({ materialDef, fallbackColor, fallbackAlpha, textureCache }, label) {
+	    async createStudioMaterial({ materialDef, fallbackColor, fallbackAlpha, textureCache, }, label) {
 	        const def = materialDef;
 	        const side = def.doubleSided ? DoubleSide : FrontSide;
 	        // --- Resolve base color and opacity ---
@@ -83641,11 +83695,13 @@ void main() {
 	     * @param values - Scalar PBR values from threejs-materials
 	     * @param textures - Texture map references from threejs-materials
 	     * @param textureRepeat - Optional [u, v] texture tiling applied to all loaded textures
+	     * @param textureRotation - Optional texture rotation in radians (counterclockwise),
+	     *                          pivoting around the texture center (0.5, 0.5)
 	     * @param textureCache - TextureCache for resolving data URI textures
 	     * @param label - Optional label for GPU tracking
 	     * @returns Configured MeshPhysicalMaterial
 	     */
-	    async createStudioMaterialFromMaterialX(values, textures, textureRepeat, textureCache, label) {
+	    async createStudioMaterialFromMaterialX(values, textures, textureRepeat, textureRotation, textureCache, label) {
 	        // --- Build material options from scalar values ---
 	        const matOptions = {
 	            flatShading: false,
@@ -83661,14 +83717,17 @@ void main() {
 	        }
 	        for (const [key, value] of Object.entries(values)) {
 	            // Skip displacement properties (not supported, would waste GPU memory)
-	            if (key === "displacement" || key === "displacementScale" || key === "displacementBias")
+	            if (key === "displacement" ||
+	                key === "displacementScale" ||
+	                key === "displacementBias")
 	                continue;
 	            // Color arrays → THREE.Color (already linear, no sRGB conversion)
 	            if (COLOR_ARRAY_KEYS.has(key) && Array.isArray(value)) {
 	                const [r, g, b] = value;
 	                matOptions[key] = new Color(r, g, b);
 	            }
-	            else if ((key === "normalScale" || key === "clearcoatNormalScale") && Array.isArray(value)) {
+	            else if ((key === "normalScale" || key === "clearcoatNormalScale") &&
+	                Array.isArray(value)) {
 	                matOptions[key] = new Vector2(value[0], value[1]);
 	            }
 	            else if (key === "iridescenceThicknessRange" && Array.isArray(value)) {
@@ -83687,7 +83746,8 @@ void main() {
 	            matOptions.opacity = 1.0;
 	            matOptions.depthWrite = true;
 	        }
-	        else if (transparentVal === true || (typeof opacityVal === "number" && opacityVal < 1.0)) {
+	        else if (transparentVal === true ||
+	            (typeof opacityVal === "number" && opacityVal < 1.0)) {
 	            matOptions.transparent = true;
 	            matOptions.depthWrite = false;
 	        }
@@ -83712,10 +83772,19 @@ void main() {
 	                    : "normalTexture";
 	                let tex = await textureCache.get(textureRef, roleForCache);
 	                if (tex) {
-	                    if (textureRepeat && (textureRepeat[0] !== 1 || textureRepeat[1] !== 1)) {
+	                    const needsRepeat = textureRepeat &&
+	                        (textureRepeat[0] !== 1 || textureRepeat[1] !== 1);
+	                    const needsRotation = !!textureRotation;
+	                    if (needsRepeat || needsRotation) {
 	                        // Clone to avoid mutating shared cached texture
 	                        tex = tex.clone();
-	                        tex.repeat.set(textureRepeat[0], textureRepeat[1]);
+	                        if (needsRepeat) {
+	                            tex.repeat.set(textureRepeat[0], textureRepeat[1]);
+	                        }
+	                        if (needsRotation) {
+	                            tex.center.set(0.5, 0.5); // pivot around texture center
+	                            tex.rotation = textureRotation;
+	                        }
 	                    }
 	                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
 	                    material[mapName] = tex;
@@ -83927,7 +83996,7 @@ void main() {
 	    // ---------------------------------------------------------------------------
 	    // Metals -- Polished
 	    // ---------------------------------------------------------------------------
-	    "chrome": {
+	    chrome: {
 	        name: "Chrome",
 	        color: [0.98, 0.98, 0.98, 1],
 	        metalness: 1.0,
@@ -83945,19 +84014,19 @@ void main() {
 	        metalness: 1.0,
 	        roughness: 0.1,
 	    },
-	    "gold": {
+	    gold: {
 	        name: "Gold",
 	        color: [1, 0.93, 0, 1],
 	        metalness: 1.0,
 	        roughness: 0.1,
 	    },
-	    "copper": {
+	    copper: {
 	        name: "Copper",
 	        color: [0.98, 0.82, 0.76, 1],
 	        metalness: 1.0,
 	        roughness: 0.15,
 	    },
-	    "brass": {
+	    brass: {
 	        name: "Brass",
 	        color: [0.95, 0.9, 0.7, 1],
 	        metalness: 1.0,
@@ -83985,13 +84054,13 @@ void main() {
 	        metalness: 0.9,
 	        roughness: 0.7,
 	    },
-	    "titanium": {
+	    titanium: {
 	        name: "Titanium",
 	        color: [0.81, 0.79, 0.77, 1],
 	        metalness: 1.0,
 	        roughness: 0.45,
 	    },
-	    "galvanized": {
+	    galvanized: {
 	        name: "Galvanized",
 	        color: [0.88, 0.88, 0.9, 1],
 	        metalness: 0.8,
@@ -84018,7 +84087,7 @@ void main() {
 	        metalness: 0.0,
 	        roughness: 0.4,
 	    },
-	    "nylon": {
+	    nylon: {
 	        name: "Nylon",
 	        color: [0.95, 0.94, 0.92, 1],
 	        metalness: 0.0,
@@ -84128,7 +84197,7 @@ void main() {
 	        roughness: 0.35,
 	        anisotropy: 0.3,
 	    },
-	    "concrete": {
+	    concrete: {
 	        name: "Concrete",
 	        color: [0.83, 0.82, 0.8, 1],
 	        metalness: 0.0,
@@ -84181,6 +84250,7 @@ varying vec3 vTriplanarNormal;
 uniform vec3 triplanarOffset;
 uniform float triplanarScale;
 uniform vec2 triplanarRepeat;
+uniform float triplanarRotation;
 
 // normalMatrix is only declared in the fragment shader for object-space
 // normal maps. We need it for triplanar tangent-space normal mapping too.
@@ -84203,6 +84273,20 @@ void initTriplanarUVs() {
   tri_uvX = p.yz * r;
   tri_uvY = p.xz * r;
   tri_uvZ = p.xy * r;
+
+  // Apply rotation (counterclockwise, radians) if non-zero. The texture
+  // coords are unbounded in triplanar (derived from world-space position),
+  // so the pivot for rotation is the UV origin — for a tiled/repeating
+  // texture this is visually equivalent to any other pivot modulo tile
+  // wrapping, and is the simplest choice.
+  if (triplanarRotation != 0.0) {
+    float c = cos(triplanarRotation);
+    float s = sin(triplanarRotation);
+    mat2 rot = mat2(c, -s, s, c);
+    tri_uvX = rot * tri_uvX;
+    tri_uvY = rot * tri_uvY;
+    tri_uvZ = rot * tri_uvZ;
+  }
 }
 
 // Sample a texture using the global triplanar UVs and blend weights.
@@ -84403,14 +84487,24 @@ float metalnessFactor = metalness;
 	    // Uniform values (captured by closure, per-object)
 	    const offset = bb.min.clone();
 	    const scale = 1.0 / maxDim;
-	    // Read texture repeat from the first available texture map
-	    const repeat = (material.map ?? material.roughnessMap ?? material.normalMap ??
-	        material.metalnessMap ?? material.emissiveMap ?? material.aoMap)?.repeat?.clone() ?? new Vector2(1, 1);
+	    // Read texture repeat and rotation from the first available texture map.
+	    // texture.rotation is set by the MaterialX path when textureRotation is
+	    // provided; for triplanar sampling we read it back and apply via uniform
+	    // since the triplanar shader bypasses three.js's texture-matrix transform.
+	    const firstMap = material.map ??
+	        material.roughnessMap ??
+	        material.normalMap ??
+	        material.metalnessMap ??
+	        material.emissiveMap ??
+	        material.aoMap;
+	    const repeat = firstMap?.repeat?.clone() ?? new Vector2(1, 1);
+	    const rotation = firstMap?.rotation ?? 0;
 	    material.onBeforeCompile = (shader) => {
 	        // Custom uniforms
 	        shader.uniforms.triplanarOffset = { value: offset };
 	        shader.uniforms.triplanarScale = { value: scale };
 	        shader.uniforms.triplanarRepeat = { value: repeat };
+	        shader.uniforms.triplanarRotation = { value: rotation };
 	        // --- Vertex shader ---
 	        // Declare varyings
 	        shader.vertexShader = shader.vertexShader.replace("#include <common>", `#include <common>\n${TRIPLANAR_VARYINGS}`);
@@ -84481,11 +84575,22 @@ float metalnessFactor = metalness;
 	 */
 	/** Texture field names on MaterialAppearance that require UV coordinates. */
 	const TEXTURE_FIELDS = [
-	    "map", "normalMap", "aoMap",
-	    "metalnessMap", "roughnessMap", "emissiveMap", "transmissionMap",
-	    "clearcoatMap", "clearcoatRoughnessMap", "clearcoatNormalMap",
-	    "thicknessMap", "specularIntensityMap", "specularColorMap",
-	    "sheenColorMap", "sheenRoughnessMap", "anisotropyMap",
+	    "map",
+	    "normalMap",
+	    "aoMap",
+	    "metalnessMap",
+	    "roughnessMap",
+	    "emissiveMap",
+	    "transmissionMap",
+	    "clearcoatMap",
+	    "clearcoatRoughnessMap",
+	    "clearcoatNormalMap",
+	    "thicknessMap",
+	    "specularIntensityMap",
+	    "specularColorMap",
+	    "sheenColorMap",
+	    "sheenRoughnessMap",
+	    "anisotropyMap",
 	];
 	/** Check whether a resolved MaterialAppearance references any texture. */
 	function materialHasTexture(def) {
@@ -85217,7 +85322,7 @@ float metalnessFactor = metalness;
 	     * 3. Clone BackSide variant for renderback objects
 	     * 4. Auto-generate box-projected UVs when textured but geometry has no UVs
 	     */
-	    async enterStudioMode(textureMapping = "triplanar") {
+	    async enterStudioMode(textureMapping = "parametric") {
 	        // Create TextureCache lazily
 	        if (!this._textureCache) {
 	            this._textureCache = new TextureCache();
@@ -85251,7 +85356,8 @@ float metalnessFactor = metalness;
 	                try {
 	                    if (resolved && isMaterialXMaterial(resolved)) {
 	                        // --- threejs-materials path ---
-	                        studioMaterial = await this.materialFactory.createStudioMaterialFromMaterialX(resolved.values, resolved.textures, resolved.textureRepeat, this._textureCache);
+	                        studioMaterial =
+	                            await this.materialFactory.createStudioMaterialFromMaterialX(resolved.values, resolved.textures, resolved.textureRepeat, resolved.textureRotation, this._textureCache);
 	                        if (materialXHasTextures(resolved)) {
 	                            this._texturedMaterialKeys.add(sharingKey);
 	                        }
@@ -85301,7 +85407,8 @@ float metalnessFactor = metalness;
 	            if (textured) {
 	                logger.debug(`Studio "${path}": ${needsTriplanar ? "using triplanar" : "using parametric UVs"}`);
 	            }
-	            if (needsTriplanar && studioMaterial instanceof MeshPhysicalMaterial) {
+	            if (needsTriplanar &&
+	                studioMaterial instanceof MeshPhysicalMaterial) {
 	                const triKey = `${sharingKey}:tri:${path}`;
 	                let triMat = this._studioMaterialCache.get(triKey);
 	                if (!triMat) {
@@ -85313,7 +85420,8 @@ float metalnessFactor = metalness;
 	            }
 	            // Build back-face variant if needed
 	            let studioBack = null;
-	            if (obj.renderback && studioMaterial instanceof MeshPhysicalMaterial) {
+	            if (obj.renderback &&
+	                studioMaterial instanceof MeshPhysicalMaterial) {
 	                const backKey = needsTriplanar
 	                    ? `${sharingKey}:tri:${path}:back`
 	                    : `${sharingKey}:back`;
@@ -85341,7 +85449,9 @@ float metalnessFactor = metalness;
 	                }
 	            }
 	            // Apply to ObjectGroup
-	            obj.enterStudioMode(studioMaterial instanceof MeshPhysicalMaterial ? studioMaterial : null, studioBack);
+	            obj.enterStudioMode(studioMaterial instanceof MeshPhysicalMaterial
+	                ? studioMaterial
+	                : null, studioBack);
 	        }
 	        this._isStudioMode = true;
 	        return [...unresolvedTags];
@@ -86604,7 +86714,10 @@ float metalnessFactor = metalness;
 	     */
 	    _buildTreeStructure(data) {
 	        const build = (data, path, level) => {
-	            const result = [States.unselected, States.unselected];
+	            const result = [
+	                States.unselected,
+	                States.unselected,
+	            ];
 	            const calcState = (states) => {
 	                for (const s of [0, 1]) {
 	                    if (states[States.mixed][s] ||
@@ -87093,7 +87206,8 @@ float metalnessFactor = metalness;
 	        this.update = (prefix = null) => {
 	            if (!this.container || !this.model)
 	                return;
-	            const visibleElements = this.getVisibleElements().filter((p) => p instanceof HTMLElement && (prefix == null || (p.dataset.path || "").startsWith(prefix)));
+	            const visibleElements = this.getVisibleElements().filter((p) => p instanceof HTMLElement &&
+	                (prefix == null || (p.dataset.path || "").startsWith(prefix)));
 	            for (const el of visibleElements) {
 	                const path = el.dataset.path || "";
 	                const node = this.findNodeByPath(path);
@@ -87729,7 +87843,8 @@ float metalnessFactor = metalness;
 	            this.showChildContainer(node);
 	            const el = this.getDomNode(path);
 	            if (el != null) {
-	                this.scrollContainer.scrollTop = el.offsetTop - this.scrollContainer.offsetTop;
+	                this.scrollContainer.scrollTop =
+	                    el.offsetTop - this.scrollContainer.offsetTop;
 	            }
 	            if (this.debug) {
 	                logger.debug("update => collapsePath");
@@ -87750,7 +87865,8 @@ float metalnessFactor = metalness;
 	        this.model.setExpandedLevel(level);
 	        const el = this.getDomNode(this.getNodePath(this.root));
 	        if (el != null) {
-	            this.scrollContainer.scrollTop = el.offsetTop - this.scrollContainer.offsetTop;
+	            this.scrollContainer.scrollTop =
+	                el.offsetTop - this.scrollContainer.offsetTop;
 	        }
 	        // Multiple updates to ensure all levels are rendered
 	        const maxIterations = level === -1 ? this.maxLevel : level;
@@ -87983,7 +88099,9 @@ float metalnessFactor = metalness;
 	     */
 	    // @ts-expect-error -- THREE.Plane.clone() returns `this`, but we need a concrete CenteredPlane
 	    clone() {
-	        return new CenteredPlane(this.normal.clone(), this.centeredConstant, [...this.center]);
+	        return new CenteredPlane(this.normal.clone(), this.centeredConstant, [
+	            ...this.center,
+	        ]);
 	    }
 	}
 	// ============================================================================
@@ -88193,7 +88311,9 @@ float metalnessFactor = metalness;
 	            let j = 0;
 	            for (const path in this.nestedGroup.groups) {
 	                const group = this.nestedGroup.groups[path];
-	                if (group instanceof ObjectGroup && group.subtype === "solid" && group.front) {
+	                if (group instanceof ObjectGroup &&
+	                    group.subtype === "solid" &&
+	                    group.front) {
 	                    // Store color for each plane-solid combination (mirrors _planeMeshGroup order)
 	                    const frontMesh = group.front;
 	                    const material = frontMesh.material;
@@ -88713,7 +88833,8 @@ float metalnessFactor = metalness;
 	            }
 	            else {
 	                // Non-binary format: nested number[][] arrays
-	                if (!Array.isArray(shape.triangles) || !Array.isArray(shape.triangles[0])) {
+	                if (!Array.isArray(shape.triangles) ||
+	                    !Array.isArray(shape.triangles[0])) {
 	                    throw new Error("Expected nested array for triangles in non-binary format");
 	                }
 	                // After validation, we know shape.triangles is number[][] (TypeScript can't infer this)
@@ -88841,7 +88962,8 @@ float metalnessFactor = metalness;
 	            else {
 	                // Non-binary format: nested number[][] arrays
 	                const edgesRaw = shape.edges;
-	                if (!Array.isArray(edgesRaw) || (edgesRaw.length > 0 && !Array.isArray(edgesRaw[0]))) {
+	                if (!Array.isArray(edgesRaw) ||
+	                    (edgesRaw.length > 0 && !Array.isArray(edgesRaw[0]))) {
 	                    throw new Error("Expected nested array for edges in non-binary format");
 	                }
 	                // After validation, we know this is number[][] (TypeScript can't infer from the check)
@@ -92986,8 +93108,14 @@ float metalnessFactor = metalness;
 	        rear: { pos: new Vector3(0, 1, 0), quat: null },
 	        left: { pos: new Vector3(-1, 0, 0), quat: null },
 	        right: { pos: new Vector3(1, 0, 0), quat: null },
-	        top: { pos: new Vector3(0, 0, 1), quat: new Quaternion(0, 0, 0, 1) },
-	        bottom: { pos: new Vector3(0, 0, -1), quat: new Quaternion(1, 0, 0, 0) },
+	        top: {
+	            pos: new Vector3(0, 0, 1),
+	            quat: new Quaternion(0, 0, 0, 1),
+	        },
+	        bottom: {
+	            pos: new Vector3(0, 0, -1),
+	            quat: new Quaternion(1, 0, 0, 0),
+	        },
 	    },
 	    legacy: {
 	        // legacy Z up
@@ -93511,7 +93639,10 @@ float metalnessFactor = metalness;
 	            const object = obj.object;
 	            // Accept Mesh (faces), Points (vertices), and Line (edges)
 	            const isValidType = isMesh(object) || isPoints(object) || isLine(object);
-	            if (isValidType && object.visible && !Array.isArray(object.material) && object.material.visible) {
+	            if (isValidType &&
+	                object.visible &&
+	                !Array.isArray(object.material) &&
+	                object.material.visible) {
 	                validObjs.push(obj);
 	            }
 	        }
@@ -93531,7 +93662,9 @@ float metalnessFactor = metalness;
 	                const isValidType = isMesh(obj) || isPoints(obj) || isLine(obj);
 	                if (!isValidType)
 	                    continue;
-	                if (!obj.visible || Array.isArray(obj.material) || !obj.material.visible)
+	                if (!obj.visible ||
+	                    Array.isArray(obj.material) ||
+	                    !obj.material.visible)
 	                    continue;
 	                const objectGroup = object.object.parent;
 	                if (!isObjectGroup(objectGroup))
@@ -93560,7 +93693,9 @@ float metalnessFactor = metalness;
 	 * Type guard to check if a value is a number array of specific length.
 	 */
 	function isNumberArray(value, length) {
-	    return Array.isArray(value) && value.length === length && value.every((v) => typeof v === "number");
+	    return (Array.isArray(value) &&
+	        value.length === length &&
+	        value.every((v) => typeof v === "number"));
 	}
 	/**
 	 * Type guard to check if a value is a Record<string, number[]> (bounding box data).
@@ -93711,9 +93846,17 @@ float metalnessFactor = metalness;
 	 * Skip list for technical fields that should not be rendered in panels.
 	 */
 	const SKIP_KEYS = [
-	    "type", "tool_type", "subtype", "info",
-	    "refpoint", "refpoint1", "refpoint2",
-	    "shape_type", "geom_type", "groups", "result",
+	    "type",
+	    "tool_type",
+	    "subtype",
+	    "info",
+	    "refpoint",
+	    "refpoint1",
+	    "refpoint2",
+	    "shape_type",
+	    "geom_type",
+	    "groups",
+	    "result",
 	];
 	/**
 	 * Render entries from a group object into a tbody.
@@ -94131,7 +94274,10 @@ float metalnessFactor = metalness;
 	            e.stopPropagation();
 	        };
 	        this._movePanel = () => {
-	            if (!this.panel || !this.viewer || !this.viewer.camera || !this.panel.isVisible())
+	            if (!this.panel ||
+	                !this.viewer ||
+	                !this.viewer.camera ||
+	                !this.panel.isVisible())
 	                return;
 	            const canvasRect = this.viewer.renderer.domElement.getBoundingClientRect();
 	            const panelRect = this.panel.html.getBoundingClientRect();
@@ -94331,8 +94477,15 @@ float metalnessFactor = metalness;
 	                    responseData = {
 	                        groups: [
 	                            { distance: 2.345, info: "center" },
-	                            { "point 1": this.point1.toArray(), "point 2": this.point2.toArray() },
-	                            { angle: 43.21, "reference 1": "Plane (Face)", "reference 2": "Plane (Face)" },
+	                            {
+	                                "point 1": this.point1.toArray(),
+	                                "point 2": this.point2.toArray(),
+	                            },
+	                            {
+	                                angle: 43.21,
+	                                "reference 1": "Plane (Face)",
+	                                "reference 2": "Plane (Face)",
+	                            },
 	                        ],
 	                        type: "backend_response",
 	                        refpoint1: this.point1.toArray(),
@@ -94351,10 +94504,21 @@ float metalnessFactor = metalness;
 	                        geom_type: "EllipseArc",
 	                        refpoint: this.point1.toArray(),
 	                        groups: [
-	                            { center: this.point1.toArray(), "major radius": 0.4, "minor radius": 0.2 },
+	                            {
+	                                center: this.point1.toArray(),
+	                                "major radius": 0.4,
+	                                "minor radius": 0.2,
+	                            },
 	                            { start: [2.4, -1, 0.0], end: [1.8, -0.8267949192431111, 0.0] },
 	                            { length: 0.6868592404716374 },
-	                            { bb: { min: [1.8, -1, 0.0], center: [2.1, -0.9, 0.0], max: [2.4, -0.8, 0.0], size: [0.56, 0.2, 0.0] } },
+	                            {
+	                                bb: {
+	                                    min: [1.8, -1, 0.0],
+	                                    center: [2.1, -0.9, 0.0],
+	                                    max: [2.4, -0.8, 0.0],
+	                                    size: [0.56, 0.2, 0.0],
+	                                },
+	                            },
 	                        ],
 	                    };
 	                }
@@ -94466,7 +94630,8 @@ float metalnessFactor = metalness;
 	        this.debug = debug;
 	    }
 	    _createPanel() {
-	        if (isDistancePanel(this.panel) && isDistanceResponseData(this.responseData)) {
+	        if (isDistancePanel(this.panel) &&
+	            isDistanceResponseData(this.responseData)) {
 	            this.panel.createTable(this.responseData);
 	        }
 	    }
@@ -94526,7 +94691,8 @@ float metalnessFactor = metalness;
 	        this.debug = debug;
 	    }
 	    _createPanel() {
-	        if (isPropertiesPanel(this.panel) && isPropertiesResponseData(this.responseData)) {
+	        if (isPropertiesPanel(this.panel) &&
+	            isPropertiesResponseData(this.responseData)) {
 	            this.panel.createTable(this.responseData);
 	        }
 	    }
@@ -94534,7 +94700,8 @@ float metalnessFactor = metalness;
 	        return 1;
 	    }
 	    _getPoint() {
-	        if (isPropertiesResponseData(this.responseData) && this.responseData.refpoint) {
+	        if (isPropertiesResponseData(this.responseData) &&
+	            this.responseData.refpoint) {
 	            this.point1 = new Vector3(...this.responseData.refpoint);
 	        }
 	    }
@@ -94801,7 +94968,7 @@ float metalnessFactor = metalness;
 	    }
 	}
 
-	const version = "4.3.8";
+	const version = "4.3.9";
 
 	/**
 	 * Clean room environment for Studio mode PMREM generation.
@@ -94906,7 +95073,7 @@ float metalnessFactor = metalness;
 	    const indices = [];
 	    const sign = -1 ;
 	    for (let i = 0; i <= segments; i++) {
-	        const angle = (i / segments) * Math.PI / 2;
+	        const angle = ((i / segments) * Math.PI) / 2;
 	        const h = sign * radius * Math.sin(angle); // horizontal offset toward wall
 	        const y = radius * (1 - Math.cos(angle)); // vertical offset above floor
 	        const nh = sign * Math.sin(angle); // normal toward wall
@@ -95455,7 +95622,7 @@ float metalnessFactor = metalness;
 	    }
 	    if (exponent === 31) {
 	        // Infinity or NaN
-	        return mantissa ? NaN : (sign ? -Infinity : Infinity);
+	        return mantissa ? NaN : sign ? -Infinity : Infinity;
 	    }
 	    return (sign ? -1 : 1) * Math.pow(2, exponent - 15) * (1 + mantissa / 1024);
 	}
@@ -95486,7 +95653,7 @@ float metalnessFactor = metalness;
 	    for (let sy = 0; sy < height; sy++) {
 	        const gy = Math.min(Math.floor((sy / height) * GRID_H), GRID_H - 1);
 	        // cos(latitude) weighting: equator has more area than poles
-	        const phi = ((0.5 - sy / height)) * Math.PI;
+	        const phi = (0.5 - sy / height) * Math.PI;
 	        const cosWeight = Math.cos(phi);
 	        for (let sx = 0; sx < width; sx++) {
 	            const gx = Math.min(Math.floor((sx / width) * GRID_W), GRID_W - 1);
@@ -95525,7 +95692,9 @@ float metalnessFactor = metalness;
 	        }
 	    }
 	    // 2. Compute median luminance and threshold
-	    const sorted = Array.from(grid).filter(v => v > 0).sort((a, b) => a - b);
+	    const sorted = Array.from(grid)
+	        .filter((v) => v > 0)
+	        .sort((a, b) => a - b);
 	    if (sorted.length === 0) {
 	        return { lights: [], wasAnalyzed: true };
 	    }
@@ -95621,9 +95790,9 @@ float metalnessFactor = metalness;
 	        let color;
 	        if (colorTotal > 0) {
 	            color = [
-	                c.totalR / colorTotal * 3,
-	                c.totalG / colorTotal * 3,
-	                c.totalB / colorTotal * 3,
+	                (c.totalR / colorTotal) * 3,
+	                (c.totalG / colorTotal) * 3,
+	                (c.totalB / colorTotal) * 3,
 	            ];
 	            // Clamp to 0-1
 	            color = [
@@ -95784,14 +95953,6 @@ float metalnessFactor = metalness;
 	    constructor(options = {}) {
 	        /** Cached PMREM render targets keyed by environment name or URL */
 	        this._cache = new Map();
-	        /**
-	         * Cached raw equirectangular HDR textures keyed by the same name/URL.
-	         * Preserved (not disposed after PMREM generation) so `scene.background`
-	         * can sample the original HDR at full source resolution instead of the
-	         * 256² PMREM cubemap. Only populated by `_loadHdr` — procedural
-	         * environments have no source HDR.
-	         */
-	        this._hdrCache = new Map();
 	        /** Cached light detection results keyed by environment name or URL */
 	        this._lightDetectionCache = new Map();
 	        /** In-flight load promises keyed by environment name or URL */
@@ -95806,13 +95967,6 @@ float metalnessFactor = metalness;
 	        this._hdrLoader = null;
 	        /** The last loaded PMREM texture (stateful — used by apply() for IBL) */
 	        this._currentTexture = null;
-	        /**
-	         * Raw HDR texture corresponding to `_currentTexture`, used for
-	         * `scene.background` to keep the backdrop at source resolution. Null when
-	         * the current environment is procedural ("studio" RoomEnvironment) — in
-	         * that case the background falls back to `_currentTexture` (the PMREM).
-	         */
-	        this._currentBackgroundTexture = null;
 	        /** Whether this manager has been disposed */
 	        this._disposed = false;
 	        /**
@@ -95837,7 +95991,8 @@ float metalnessFactor = metalness;
 	         * re-apply once the texture is ready.
 	         */
 	        this._deferredApply = null;
-	        this._userOverrides = options.presetUrls ?? {};
+	        this._userOverrides =
+	            options.presetUrls ?? {};
 	        this._presetUrls = {
 	            ..._buildPresetUrls(false),
 	            ...this._userOverrides,
@@ -95866,7 +96021,6 @@ float metalnessFactor = metalness;
 	        }
 	        if (name === "none") {
 	            this._currentTexture = null;
-	            this._currentBackgroundTexture = null;
 	            return null;
 	        }
 	        // Check cache first (name is the cache key for presets; URL string for custom)
@@ -95875,7 +96029,6 @@ float metalnessFactor = metalness;
 	        if (cached) {
 	            logger.debug(`Environment "${cacheKey}" loaded from cache`);
 	            this._currentTexture = cached.texture;
-	            this._currentBackgroundTexture = this._hdrCache.get(cacheKey) ?? null;
 	            return cached.texture;
 	        }
 	        // Check in-flight promise — await and set _currentTexture
@@ -95884,7 +96037,6 @@ float metalnessFactor = metalness;
 	            logger.debug(`Environment "${cacheKey}" already loading, reusing promise`);
 	            const texture = await inflight;
 	            this._currentTexture = texture;
-	            this._currentBackgroundTexture = this._hdrCache.get(cacheKey) ?? null;
 	            return texture;
 	        }
 	        // Start new load
@@ -95893,7 +96045,6 @@ float metalnessFactor = metalness;
 	        try {
 	            const texture = await promise;
 	            this._currentTexture = texture;
-	            this._currentBackgroundTexture = this._hdrCache.get(cacheKey) ?? null;
 	            // Self-healing: if apply() was called with "environment" background
 	            // while texture was null, re-apply now that the texture is ready.
 	            if (this._deferredApply) {
@@ -95933,8 +96084,13 @@ float metalnessFactor = metalness;
 	            scene.environmentIntensity = envIntensity;
 	            // HDR maps assume Y-up; rotate 90° around X to align with Z-up scenes.
 	            // Additional rotation for user-controlled azimuthal rotation.
+	            // Note: Z-up branch uses "ZYX" Euler order so the matrix is
+	            // Rz(rotY) · Rx(PI/2). With the default "XYZ" order, the rotation
+	            // would land on the wrong axis (around World -Y, the depth axis,
+	            // instead of World Z, the vertical axis) because of how matrix
+	            // multiplication composes the X-tilt with the user rotation.
 	            if (upIsZ) {
-	                scene.environmentRotation.set(Math.PI / 2, 0, rotY);
+	                scene.environmentRotation.set(Math.PI / 2, 0, rotY, "ZYX");
 	            }
 	            else {
 	                scene.environmentRotation.set(0, rotY, 0);
@@ -95971,13 +96127,14 @@ float metalnessFactor = metalness;
 	                break;
 	            case "environment":
 	                if (this._currentTexture) {
-	                    // Prefer the raw HDR for the background so the backdrop samples
-	                    // at source resolution (2K/4K) rather than the 256² PMREM cubemap.
-	                    // Falls back to PMREM for procedural "studio" (no source HDR).
-	                    const bgTex = this._currentBackgroundTexture ?? this._currentTexture;
+	                    // Use PMREM (CubeUVReflectionMapping) for the background. Raw
+	                    // equirectangular HDR can't be used here: three.js's WebGLBackground
+	                    // routes non-cubemap textures through a flat planeMesh path that
+	                    // ignores scene.backgroundRotation, so env-rotation breaks. PMREM
+	                    // takes the cubemap path and rotation works correctly.
 	                    // Always use render-to-texture with a fixed-FOV bgCamera so the
 	                    // background zoom level is identical in perspective and ortho modes.
-	                    this._setupEnvBackground(scene, bgTex, upIsZ, rotY);
+	                    this._setupEnvBackground(scene, this._currentTexture, upIsZ, rotY);
 	                    this._deferredApply = null;
 	                }
 	                else {
@@ -96062,15 +96219,11 @@ float metalnessFactor = metalness;
 	                this._lightDetectionCache.delete(slug);
 	                logger.debug(`Evicted cached environment "${slug}" for resolution switch`);
 	            }
-	            const cachedHdr = this._hdrCache.get(slug);
-	            if (cachedHdr) {
-	                gpuTracker.untrack("texture", cachedHdr);
-	                cachedHdr.dispose();
-	                this._hdrCache.delete(slug);
-	            }
 	        }
 	        // Reload the current environment at the new resolution
-	        if (currentEnvName && currentEnvName !== "none" && currentEnvName !== "studio") {
+	        if (currentEnvName &&
+	            currentEnvName !== "none" &&
+	            currentEnvName !== "studio") {
 	            return this.loadEnvironment(currentEnvName, renderer);
 	        }
 	        return this._currentTexture;
@@ -96128,7 +96281,9 @@ float metalnessFactor = metalness;
 	        const size = renderer.getDrawingBufferSize(_bgSizeVec);
 	        const w = size.x;
 	        const h = size.y;
-	        if (!this._bgRenderTarget || this._bgRenderTarget.width !== w || this._bgRenderTarget.height !== h) {
+	        if (!this._bgRenderTarget ||
+	            this._bgRenderTarget.width !== w ||
+	            this._bgRenderTarget.height !== h) {
 	            this._bgRenderTarget?.dispose();
 	            this._bgRenderTarget = new WebGLRenderTarget(w, h);
 	        }
@@ -96166,7 +96321,6 @@ float metalnessFactor = metalness;
 	    dispose() {
 	        this._disposed = true;
 	        this._currentTexture = null;
-	        this._currentBackgroundTexture = null;
 	        this._deferredApply = null;
 	        this._teardownEnvBackground();
 	        this._bgScene = null;
@@ -96182,13 +96336,6 @@ float metalnessFactor = metalness;
 	            logger.debug(`Disposed cached environment render target: ${key}`);
 	        }
 	        this._cache.clear();
-	        // Dispose all cached raw HDR textures
-	        for (const [key, hdrTexture] of this._hdrCache) {
-	            gpuTracker.untrack("texture", hdrTexture);
-	            hdrTexture.dispose();
-	            logger.debug(`Disposed cached HDR background: ${key}`);
-	        }
-	        this._hdrCache.clear();
 	        this._lightDetectionCache.clear();
 	        // Clear in-flight promises (they'll resolve but won't be cached)
 	        this._inflight.clear();
@@ -96224,8 +96371,9 @@ float metalnessFactor = metalness;
 	        this._bgScene.background = texture;
 	        this._bgScene.backgroundIntensity = 1.0;
 	        this._bgScene.backgroundBlurriness = 0;
+	        // See apply() for the "ZYX" rationale.
 	        if (upIsZ) {
-	            this._bgScene.backgroundRotation.set(Math.PI / 2, 0, rotY);
+	            this._bgScene.backgroundRotation.set(Math.PI / 2, 0, rotY, "ZYX");
 	        }
 	        else {
 	            this._bgScene.backgroundRotation.set(0, rotY, 0);
@@ -96343,10 +96491,9 @@ float metalnessFactor = metalness;
 	     * Load an HDR file and generate a PMREM texture from it.
 	     *
 	     * Uses HDRLoader to fetch the .hdr file, then PMREMGenerator.fromEquirectangular()
-	     * to create the PMREM cubemap for IBL. The source equirectangular HDR is
-	     * preserved and cached separately (in `_hdrCache`) so that "environment"
-	     * background mode can sample the full-resolution equirectangular texture
-	     * instead of the 256² PMREM cubemap.
+	     * to create the PMREM cubemap. The source equirectangular HDR is disposed
+	     * after PMREM generation. The PMREM texture itself serves as both the IBL
+	     * environment and the background (in "environment" mode).
 	     *
 	     * @param url - URL of the .hdr file
 	     * @param cacheKey - Cache key for the resulting PMREM render target
@@ -96372,19 +96519,21 @@ float metalnessFactor = metalness;
 	        const renderTarget = pmremGenerator.fromEquirectangular(hdrTexture);
 	        // Analyze HDR pixel data for dominant light sources BEFORE disposing.
 	        // hdrTexture.image.data is Uint16Array (HalfFloatType) from HDRLoader.
-	        if (hdrTexture.image?.data && hdrTexture.image.width && hdrTexture.image.height) {
+	        if (hdrTexture.image?.data &&
+	            hdrTexture.image.width &&
+	            hdrTexture.image.height) {
 	            const result = detectDominantLights(hdrTexture.image.data, hdrTexture.image.width, hdrTexture.image.height);
 	            this._lightDetectionCache.set(cacheKey, result);
 	        }
-	        // Preserve the equirectangular HDR for use as `scene.background` at
-	        // source resolution. PMREM's base mip is a 256² cubemap — good for IBL
-	        // (roughness-weighted prefilter) but visibly soft as a backdrop.
-	        hdrTexture.mapping = EquirectangularReflectionMapping;
-	        // Cache render target and HDR; track both.
+	        // Dispose the source equirectangular texture (PMREM is now in GPU memory).
+	        // Note: we cannot use the raw HDR for scene.background because three.js's
+	        // WebGLBackground routes non-cubemap textures through a flat planeMesh
+	        // path that ignores backgroundRotation; PMREM (CubeUVReflectionMapping)
+	        // takes the cubemap path which respects rotation.
+	        hdrTexture.dispose();
+	        // Cache render target and track its texture
 	        this._cache.set(cacheKey, renderTarget);
-	        this._hdrCache.set(cacheKey, hdrTexture);
 	        gpuTracker.trackTexture(renderTarget.texture, `PMREM environment: ${cacheKey}`);
-	        gpuTracker.trackTexture(hdrTexture, `HDR background: ${cacheKey}`);
 	        logger.debug(`Loaded HDR environment from "${url}", cached as "${cacheKey}"`);
 	        return renderTarget.texture;
 	    }
@@ -96454,7 +96603,8 @@ float metalnessFactor = metalness;
 	     */
 	    setShadowIntensity(intensity) {
 	        if (this._shadowPlane) {
-	            this._shadowPlane.material.opacity = intensity * 1.0;
+	            this._shadowPlane.material.opacity =
+	                intensity * 1.0;
 	        }
 	    }
 	    /** Dispose all GPU resources. */
@@ -96470,7 +96620,10 @@ float metalnessFactor = metalness;
 	    _createShadowPlane(zPosition, sceneSize) {
 	        const floorSize = sceneSize * 6;
 	        const geometry = new PlaneGeometry(floorSize, floorSize);
-	        const material = new ShadowMaterial({ opacity: 0.5, depthWrite: false });
+	        const material = new ShadowMaterial({
+	            opacity: 0.5,
+	            depthWrite: false,
+	        });
 	        const plane = new Mesh(geometry, material);
 	        plane.position.z = zPosition;
 	        plane.receiveShadow = true;
@@ -103931,13 +104084,17 @@ void main() {
 	 * Only instantiated when Studio mode is active. Non-Studio rendering
 	 * bypasses this entirely and uses direct `renderer.render()`.
 	 */
-	// ---------------------------------------------------------------------------
-	// Tone-mapping: maps viewer strings to postprocessing ToneMappingMode
-	// ---------------------------------------------------------------------------
+	// Tone mapping runs as a post-process effect in the EffectPass, before SMAA,
+	// so SMAA's edge detection sees LDR luma in its calibrated [0,1] range.
+	// Per-fragment tone mapping in the main RenderPass would be a no-op:
+	// three.js forces NoToneMapping when rendering to a non-canvas render target
+	// (see WebGLPrograms.getParameters), and the composer's input is a HalfFloat
+	// HDR FBO. Exposure is read from renderer.toneMappingExposure by three.js's
+	// shared <tonemapping_pars_fragment> chunk that ToneMappingEffect includes.
 	const TONE_MAP_MODE = {
-	    "neutral": ToneMappingMode.NEUTRAL,
-	    "ACES": ToneMappingMode.ACES_FILMIC,
-	    "none": ToneMappingMode.LINEAR,
+	    neutral: ToneMappingMode.NEUTRAL,
+	    ACES: ToneMappingMode.ACES_FILMIC,
+	    none: ToneMappingMode.LINEAR,
 	};
 	// Scratch color to avoid per-frame allocation
 	const _savedClearColor = new Color();
@@ -103995,7 +104152,7 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	     * @param width    - Canvas width in pixels
 	     * @param height   - Canvas height in pixels
 	     */
-	    constructor(renderer, scene, camera, width, height) {
+	    constructor(renderer, scene, camera, width, height, onSmaaReady) {
 	        /** Solid background color to protect from tone mapping, or null. */
 	        this._bgProtectColor = null;
 	        // Shadow mask pipeline — two separate masks to avoid depth-discontinuity halos
@@ -104016,15 +104173,17 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        this._camera = camera;
 	        this._width = width;
 	        this._height = height;
-	        // Postprocessing library requires renderer.toneMapping = NoToneMapping.
-	        // Tone mapping is handled by ToneMappingEffect in the pipeline.
+	        // ToneMappingEffect handles the tone curve in the EffectPass. The
+	        // postprocessing library requires renderer.toneMapping = NoToneMapping
+	        // so the renderer doesn't try to apply it as well.
 	        this._renderer.toneMapping = NoToneMapping;
 	        // HDR pipeline with HalfFloat framebuffer.
-	        // multisampling = 0: MSAA conflicts with depth-based AO passes;
-	        // antialiasing is handled by SMAAEffect instead.
+	        // multisampling = 4: WebGL2 MSAA on the composer's input RT. Most GPUs
+	        // clamp half-float MSAA to 4 samples anyway, and Studio mode applies
+	        // additional supersampling via renderer.setPixelRatio to compensate.
 	        this._composer = new EffectComposer(renderer, {
 	            frameBufferType: HalfFloatType,
-	            multisampling: 0,
+	            multisampling: 4,
 	        });
 	        // --- Pass 1: scene render ---
 	        this._renderPass = new RenderPass(scene, camera);
@@ -104044,11 +104203,23 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        this._n8aoPass.enabled = false; // off by default
 	        this._composer.addPass(this._n8aoPass);
 	        // --- Pass 3: shadow mask compositing + tone mapping + SMAA ---
+	        // ShadowMask runs first in linear HDR (where shadow math is correct).
+	        // ToneMapping next so SMAA sees LDR luma in its calibrated [0,1] range.
 	        this._toneMappingEffect = new ToneMappingEffect({
 	            mode: ToneMappingMode.NEUTRAL,
 	        });
-	        const smaaEffect = new SMAAEffect({ preset: SMAAPreset.HIGH });
-	        // ShadowMaskEffect is first so it runs in linear space before tone mapping
+	        const smaaEffect = new SMAAEffect({ preset: SMAAPreset.ULTRA });
+	        // SMAA loads its lookup textures (search/area) asynchronously via
+	        // `new Image(); image.src = "data:..."`. Even though the source is a
+	        // data URL, the `load` event fires in a microtask — so the very first
+	        // render after composer construction has no SMAA textures attached and
+	        // produces aliased edges. We notify on `load` so the caller can trigger
+	        // another render and the user sees AA without having to interact.
+	        if (onSmaaReady) {
+	            // postprocessing's TS types only declare "change"; SMAA dispatches
+	            // "load" at runtime when the lookup textures finish decoding.
+	            smaaEffect.addEventListener("load", () => onSmaaReady());
+	        }
 	        this._shadowMaskEffect = new ShadowMaskEffect();
 	        this._effectPass = new EffectPass(camera, this._shadowMaskEffect, this._toneMappingEffect, smaaEffect);
 	        this._composer.addPass(this._effectPass);
@@ -104116,6 +104287,9 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        else {
 	            this._toneMappingEffect.mode = mapped;
 	        }
+	        // ToneMappingEffect's GLSL reads toneMappingExposure from the
+	        // <tonemapping_pars_fragment> chunk, which three.js auto-populates
+	        // from this renderer property each frame.
 	        this._renderer.toneMappingExposure = exposure;
 	    }
 	    // -----------------------------------------------------------------------
@@ -104215,7 +104389,9 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        this._composer.setSize(width, height, false);
 	        this._n8aoPass.setSize(width, height);
 	        // Resize shadow mask RTs at half resolution
-	        if (this._shadowMaskRT && this._blurredObjectMaskRT && this._blurredFloorMaskRT) {
+	        if (this._shadowMaskRT &&
+	            this._blurredObjectMaskRT &&
+	            this._blurredFloorMaskRT) {
 	            const halfW = Math.max(1, Math.floor(width / 2));
 	            const halfH = Math.max(1, Math.floor(height / 2));
 	            this._shadowMaskRT.setSize(halfW, halfH);
@@ -104242,8 +104418,11 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	    render(deltaTime) {
 	        // Two-pass shadow mask: objects and floor are blurred separately to
 	        // avoid depth-discontinuity halos at their boundary.
-	        if (this._shadowMaskEnabled && this._shadowMaskRT && this._blurPass
-	            && this._blurredObjectMaskRT && this._blurredFloorMaskRT) {
+	        if (this._shadowMaskEnabled &&
+	            this._shadowMaskRT &&
+	            this._blurPass &&
+	            this._blurredObjectMaskRT &&
+	            this._blurredFloorMaskRT) {
 	            this._renderer.shadowMap.autoUpdate = false;
 	            this._renderer.shadowMap.needsUpdate = true;
 	            // Pass 1: object shadow mask (floor hidden, generates shadow map)
@@ -104254,8 +104433,10 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            this._renderShadowMask("floor");
 	            this._blurPass.render(this._renderer, this._shadowMaskRT, this._blurredFloorMaskRT);
 	            // Feed both blurred masks to the compositing effect
-	            this._shadowMaskEffect.uniforms.get("shadowMaskObjects").value = this._blurredObjectMaskRT.texture;
-	            this._shadowMaskEffect.uniforms.get("shadowMaskFloor").value = this._blurredFloorMaskRT.texture;
+	            this._shadowMaskEffect.uniforms.get("shadowMaskObjects").value =
+	                this._blurredObjectMaskRT.texture;
+	            this._shadowMaskEffect.uniforms.get("shadowMaskFloor").value =
+	                this._blurredFloorMaskRT.texture;
 	            this._renderer.shadowMap.autoUpdate = true;
 	        }
 	        // Hide floor during main render — blurred shadow mask provides floor shadow
@@ -104388,26 +104569,86 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	 */
 	const STATE_KEYS = new Set([
 	    // Display
-	    "theme", "cadWidth", "treeWidth", "treeHeight", "height", "pinning", "glass", "tools",
-	    "keymap", "newTreeBehavior", "measureTools", "selectTool", "explodeTool", "zscaleTool",
-	    "zebraTool", "studioTool", "measurementDebug",
+	    "theme",
+	    "cadWidth",
+	    "treeWidth",
+	    "treeHeight",
+	    "height",
+	    "pinning",
+	    "glass",
+	    "tools",
+	    "keymap",
+	    "newTreeBehavior",
+	    "measureTools",
+	    "selectTool",
+	    "explodeTool",
+	    "zscaleTool",
+	    "zebraTool",
+	    "studioTool",
+	    "measurementDebug",
 	    // Render
-	    "ambientIntensity", "directIntensity", "metalness", "roughness", "defaultOpacity",
-	    "edgeColor", "normalLen",
+	    "ambientIntensity",
+	    "directIntensity",
+	    "metalness",
+	    "roughness",
+	    "defaultOpacity",
+	    "edgeColor",
+	    "normalLen",
 	    // Viewer
-	    "axes", "axes0", "grid", "ortho", "transparent", "blackEdges", "collapse",
-	    "clipIntersection", "clipPlaneHelpers", "clipObjectColors", "clipNormal0", "clipNormal1",
-	    "clipNormal2", "clipSlider0", "clipSlider1", "clipSlider2", "control", "holroyd", "up",
-	    "ticks", "gridFontSize", "centerGrid", "position", "quaternion", "target", "zoom",
-	    "panSpeed", "rotateSpeed", "zoomSpeed", "timeit",
+	    "axes",
+	    "axes0",
+	    "grid",
+	    "ortho",
+	    "transparent",
+	    "blackEdges",
+	    "collapse",
+	    "clipIntersection",
+	    "clipPlaneHelpers",
+	    "clipObjectColors",
+	    "clipNormal0",
+	    "clipNormal1",
+	    "clipNormal2",
+	    "clipSlider0",
+	    "clipSlider1",
+	    "clipSlider2",
+	    "control",
+	    "holroyd",
+	    "up",
+	    "ticks",
+	    "gridFontSize",
+	    "centerGrid",
+	    "position",
+	    "quaternion",
+	    "target",
+	    "zoom",
+	    "panSpeed",
+	    "rotateSpeed",
+	    "zoomSpeed",
+	    "timeit",
 	    // Zebra
-	    "zebraCount", "zebraOpacity", "zebraDirection", "zebraColorScheme", "zebraMappingMode",
+	    "zebraCount",
+	    "zebraOpacity",
+	    "zebraDirection",
+	    "zebraColorScheme",
+	    "zebraMappingMode",
 	    // Studio
-	    "studioEnvironment", "studioEnvIntensity", "studioBackground",
-	    "studioToneMapping", "studioExposure", "studio4kEnvMaps", "studioTextureMapping",
-	    "studioEnvRotation", "studioShadowIntensity", "studioShadowSoftness", "studioAOIntensity",
+	    "studioEnvironment",
+	    "studioEnvIntensity",
+	    "studioBackground",
+	    "studioToneMapping",
+	    "studioExposure",
+	    "studio4kEnvMaps",
+	    "studioTextureMapping",
+	    "studioEnvRotation",
+	    "studioShadowIntensity",
+	    "studioShadowSoftness",
+	    "studioAOIntensity",
 	    // Runtime
-	    "activeTool", "animationMode", "animationSliderValue", "zscaleActive", "highlightedButton",
+	    "activeTool",
+	    "animationMode",
+	    "animationSliderValue",
+	    "zscaleActive",
+	    "highlightedButton",
 	    "activeTab",
 	]);
 	/**
@@ -104614,7 +104855,8 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            const value = updates[key];
 	            // Skip undefined/null, except for keys where null is a valid value (reset to default)
 	            const KEYS_WITH_VALID_NULL = ["position", "quaternion", "target"];
-	            if (value === undefined || (value === null && !KEYS_WITH_VALID_NULL.includes(key)))
+	            if (value === undefined ||
+	                (value === null && !KEYS_WITH_VALID_NULL.includes(key)))
 	                continue;
 	            const oldValue = this._state[key];
 	            if (!valuesEqual(oldValue, value)) {
@@ -104640,8 +104882,13 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	     * Converts Vector3Tuple/QuaternionTuple to THREE objects.
 	     */
 	    updateViewerState(options, notify = true) {
-	        // Extract properties that need conversion to THREE objects
-	        const { clipNormal0, clipNormal1, clipNormal2, position, quaternion, target, ...rest } = options;
+	        // Extract properties that need conversion to THREE objects.
+	        // `tab` is also extracted: it's not a state key directly (state uses
+	        // `activeTab`), and setting activeTab here would trigger switchToTab
+	        // before the scene is built. Viewer.render() applies it after
+	        // scene-building completes (suppressing the CAD-mode paint when a
+	        // non-default tab is the target).
+	        const { tab: _tab, clipNormal0, clipNormal1, clipNormal2, position, quaternion, target, ...rest } = options;
 	        const converted = { ...rest };
 	        // Convert tuple values to THREE objects
 	        if (clipNormal0 !== undefined) {
@@ -104657,7 +104904,9 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            converted.position = position ? new Vector3(...position) : null;
 	        }
 	        if (quaternion !== undefined) {
-	            converted.quaternion = quaternion ? new Quaternion(...quaternion) : null;
+	            converted.quaternion = quaternion
+	                ? new Quaternion(...quaternion)
+	                : null;
 	        }
 	        if (target !== undefined) {
 	            converted.target = target ? new Vector3(...target) : null;
@@ -104781,9 +105030,15 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	                // Apply transform if defined (e.g., slider 0-1000 → relative 0-1)
 	                const transform = STATE_NOTIFICATION_TRANSFORM[key];
 	                const notifyChange = transform
-	                    ? { old: change.old != null ? transform(change.old) : null, new: transform(change.new) }
+	                    ? {
+	                        old: change.old != null ? transform(change.old) : null,
+	                        new: transform(change.new),
+	                    }
 	                    : change;
-	                this._externalNotifyCallback({ key: notificationKey, change: notifyChange });
+	                this._externalNotifyCallback({
+	                    key: notificationKey,
+	                    change: notifyChange,
+	                });
 	            }
 	        }
 	    }
@@ -104861,12 +105116,39 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	    glass: false,
 	    tools: true,
 	    keymap: {
-	        shift: "shiftKey", ctrl: "ctrlKey", meta: "metaKey", alt: "altKey",
-	        axes: "a", axes0: "A", grid: "g", gridxy: "G", perspective: "p", transparent: "t", blackedges: "b",
-	        reset: "R", resize: "r",
-	        iso: "5", front: "1", rear: "3", top: "8", bottom: "2", left: "4", right: "6",
-	        explode: "x", zscale: "L", distance: "D", properties: "P", select: "S", help: "h", play: " ", stop: "Escape",
-	        tree: "T", clip: "C", material: "M", zebra: "Z", studio: "s",
+	        shift: "shiftKey",
+	        ctrl: "ctrlKey",
+	        meta: "metaKey",
+	        alt: "altKey",
+	        axes: "a",
+	        axes0: "A",
+	        grid: "g",
+	        gridxy: "G",
+	        perspective: "p",
+	        transparent: "t",
+	        blackedges: "b",
+	        reset: "R",
+	        resize: "r",
+	        iso: "5",
+	        front: "1",
+	        rear: "3",
+	        top: "8",
+	        bottom: "2",
+	        left: "4",
+	        right: "6",
+	        explode: "x",
+	        zscale: "L",
+	        distance: "D",
+	        properties: "P",
+	        select: "S",
+	        help: "h",
+	        play: " ",
+	        stop: "Escape",
+	        tree: "T",
+	        clip: "C",
+	        material: "M",
+	        zebra: "Z",
+	        studio: "s",
 	    },
 	    newTreeBehavior: true,
 	    measureTools: true,
@@ -104944,7 +105226,12 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	    studioToneMapping: "neutral",
 	    studioExposure: 1.0,
 	    studio4kEnvMaps: false,
-	    studioTextureMapping: "triplanar",
+	    // "parametric" is the right default when the tessellator emits UVs:
+	    // each object's `nestedgroup.ts:applyTriplanarMapping` only kicks in
+	    // when the chosen mode is "triplanar" OR the geometry has no `uv`
+	    // attribute. So with the default "parametric", textured objects with
+	    // UVs use them; objects without UVs auto-fall back to triplanar.
+	    studioTextureMapping: "parametric",
 	    studioEnvRotation: 0,
 	    studioShadowIntensity: 0.5,
 	    studioShadowSoftness: 0.2,
@@ -104981,6 +105268,13 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        this._active = false;
 	        this._savedClippingState = null;
 	        this._shadowLights = [];
+	        /**
+	         * Renderer pixel ratio saved on Studio entry, restored on leave.
+	         * Studio mode bumps the pixel ratio to apply supersampling, which
+	         * compensates for low DPR (e.g., VSCode webviews report DPR=1 even
+	         * on Retina displays) and improves AA on shallow-angle edges.
+	         */
+	        this._savedPixelRatio = null;
 	        // -------------------------------------------------------------------------
 	        // Mode enter/leave
 	        // -------------------------------------------------------------------------
@@ -105032,9 +105326,28 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	                this._ctx.getDirectLight().intensity = 0;
 	                // Floor
 	                this._configureFloor();
+	                // Studio-only supersampling. Bump pixel ratio so the renderer draws to
+	                // a higher-resolution buffer; the browser downsamples to the canvas
+	                // display size, giving smooth AA on shallow-angle silhouettes that
+	                // MSAA alone leaves stair-stepped. Especially important in webview
+	                // hosts (e.g., VSCode) where window.devicePixelRatio is reported as 1
+	                // even on Retina displays. Restored in leaveStudioMode.
+	                this._savedPixelRatio = renderer.getPixelRatio();
+	                const targetPixelRatio = Math.max(2, window.devicePixelRatio);
+	                if (targetPixelRatio !== this._savedPixelRatio) {
+	                    renderer.setPixelRatio(targetPixelRatio);
+	                    renderer.setSize(state.get("cadWidth"), state.get("height"));
+	                }
 	                // Create composer (must be before shadows)
 	                if (!this._composer) {
-	                    this._composer = new StudioComposer(renderer, scene, camera.getCamera(), state.get("cadWidth"), state.get("height"));
+	                    this._composer = new StudioComposer(renderer, scene, camera.getCamera(), state.get("cadWidth"), state.get("height"), () => {
+	                        // SMAA finished loading its async lookup textures. Re-render so
+	                        // the first visible frame has anti-aliasing — without this the
+	                        // user sees aliased edges until they interact with the scene.
+	                        if (this._active && this._ctx.isRendered()) {
+	                            this._ctx.update(true, false);
+	                        }
+	                    });
 	                }
 	                // Shadows (requires composer)
 	                if (state.get("studioShadowIntensity") > 0) {
@@ -105058,6 +105371,12 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	                    this._composer.dispose();
 	                    this._composer = null;
 	                }
+	                // Restore pixel ratio if we bumped it before failure
+	                if (this._savedPixelRatio !== null) {
+	                    renderer.setPixelRatio(this._savedPixelRatio);
+	                    renderer.setSize(state.get("cadWidth"), state.get("height"));
+	                    this._savedPixelRatio = null;
+	                }
 	                this._active = false;
 	                logger.error("Unexpected error entering studio mode", err);
 	            }
@@ -105074,6 +105393,12 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	                this._composer.dispose();
 	                this._composer = null;
 	            }
+	            // Restore the renderer's pixel ratio that was bumped on Studio entry.
+	            if (this._savedPixelRatio !== null) {
+	                renderer.setPixelRatio(this._savedPixelRatio);
+	                renderer.setSize(state.get("cadWidth"), state.get("height"));
+	                this._savedPixelRatio = null;
+	            }
 	            // 3. Remove environment, disable shadows
 	            this.envManager.remove(this._ctx.getScene());
 	            this._setShadowsEnabled(false);
@@ -105206,7 +105531,9 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        state.subscribe("studioEnvironment", (change) => {
 	            if (!isActive())
 	                return;
-	            this.envManager.loadEnvironment(change.new, this._ctx.renderer).then(() => {
+	            this.envManager
+	                .loadEnvironment(change.new, this._ctx.renderer)
+	                .then(() => {
 	                if (!isActive())
 	                    return;
 	                reapplyEnv();
@@ -105215,7 +105542,8 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	                }
 	                this._ctx.update(true, false);
 	                this._ctx.dispatchEvent(new Event("tcv-studio-ready"));
-	            }).catch((err) => {
+	            })
+	                .catch((err) => {
 	                logger.error("Unexpected error loading studio environment", err);
 	                this._ctx.dispatchEvent(new Event("tcv-studio-ready"));
 	            });
@@ -105306,7 +105634,9 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            if (!isActive())
 	                return;
 	            const envName = state.get("studioEnvironment");
-	            this.envManager.setUse4kEnvMaps(change.new, envName, this._ctx.renderer).then(() => {
+	            this.envManager
+	                .setUse4kEnvMaps(change.new, envName, this._ctx.renderer)
+	                .then(() => {
 	                if (!isActive())
 	                    return;
 	                reapplyEnv();
@@ -105444,7 +105774,9 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            this.floor.setShadowsEnabled(true);
 	            this._ctx.getScene().traverse((obj) => {
 	                if (obj instanceof Mesh && obj.material) {
-	                    const mats = Array.isArray(obj.material) ? obj.material : [obj.material];
+	                    const mats = Array.isArray(obj.material)
+	                        ? obj.material
+	                        : [obj.material];
 	                    for (const m of mats) {
 	                        m.needsUpdate = true;
 	                    }
@@ -105705,7 +106037,9 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        return this._rendered;
 	    }
 	    /** Environment manager — proxied from StudioManager for display.ts access. */
-	    get envManager() { return this._studioManager.envManager; }
+	    get envManager() {
+	        return this._studioManager.envManager;
+	    }
 	    // ---------------------------------------------------------------------------
 	    // Constructor & Initialization
 	    // ---------------------------------------------------------------------------
@@ -105718,6 +106052,10 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	     * @param updateMarker - enforce to redraw orientation marker after every ui activity
 	     */
 	    constructor(display, options, notifyCallback, pinAsPngCallback = null, updateMarker = true) {
+	        // Grid size from the previous render, used to decide whether the new
+	        // geometry is "the same model" for clip-slider preservation.
+	        // Survives clear() so reused viewers remember the previous geometry.
+	        this._previousGridSize = 0;
 	        // ---------------------------------------------------------------------------
 	        // Render Loop & Scene Updates
 	        // ---------------------------------------------------------------------------
@@ -105768,6 +106106,20 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        this.update = (updateMarker, notify = true) => {
 	            if (!this.ready)
 	                return;
+	            // Skip painting while Studio mode is mid-async-load: composer hasn't
+	            // been created yet, so a fall-through to renderer.render() would paint
+	            // the scene with CAD materials (Studio's material swap is also async).
+	            // Without this guard, any setter that calls update() — setCameraZoom,
+	            // setView, setExplode, setTool, etc. — would paint a CAD-materials
+	            // frame before Studio's first proper paint, which is visible as a
+	            // 0.5–1 sec CAD render before Studio takes over. Studio's tab
+	            // handler does its own update() at completion, which is when the
+	            // first painted frame should appear. State changes still propagate
+	            // synchronously and are picked up by that eventual paint.
+	            if (this.state.get("activeTab") === "studio" &&
+	                !this._studioManager.hasComposer) {
+	                return;
+	            }
 	            if (this._externalGl) {
 	                this.renderer.resetState();
 	            }
@@ -105805,7 +106157,10 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            }
 	            if (updateMarker) {
 	                this.renderer.clearDepth(); // ensure orientation Marker is at the top
-	                this.rendered.orientationMarker.update(this.rendered.camera.getPosition().clone().sub(this.rendered.controls.getTarget()), this.rendered.camera.getQuaternion());
+	                this.rendered.orientationMarker.update(this.rendered.camera
+	                    .getPosition()
+	                    .clone()
+	                    .sub(this.rendered.controls.getTarget()), this.rendered.camera.getQuaternion());
 	                this.rendered.orientationMarker.render(this.renderer);
 	            }
 	            if (this.animation) {
@@ -105872,6 +106227,11 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	                            if (!isObjectGroup(objectGroup))
 	                                continue;
 	                            objectGroup.setShapeVisible(compactTree[0] === 1);
+	                            // Re-apply clip-mode back visibility when re-showing — see
+	                            // matching comment in setObject().
+	                            if (compactTree[0] === 1 && this.expandedNestedGroup.backVisible) {
+	                                objectGroup.setBackVisible(true);
+	                            }
 	                            objectGroup.setEdgesVisible(compactTree[1] === 1);
 	                            // Sync state (unless disabled = 3)
 	                            if (leafState[0] !== 3)
@@ -105903,6 +106263,11 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	                        }
 	                    }
 	                    objectGroup.setShapeVisible(shapeVisible);
+	                    // Re-apply clip-mode back visibility when re-showing — see
+	                    // matching comment in setObject().
+	                    if (shapeVisible && this.compactNestedGroup.backVisible) {
+	                        objectGroup.setBackVisible(true);
+	                    }
 	                    objectGroup.setEdgesVisible(edgeVisible);
 	                    // Sync compact state (unless disabled = 3)
 	                    if (compactTree[0] !== 3)
@@ -106044,6 +106409,14 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            if (objectGroup != null && objectGroup instanceof ObjectGroup) {
 	                if (iconNumber === 0) {
 	                    objectGroup.setShapeVisible(state === 1);
+	                    // When re-showing while clip-tab is active, re-apply the clip-mode
+	                    // back-visibility for this object. setShapeVisible's show-path
+	                    // doesn't touch back when !renderback (clip-tab owns it), so a
+	                    // previously-hidden object would otherwise come back with front
+	                    // visible but back still hidden — looking hollow under clipping.
+	                    if (state === 1 && this.rendered.nestedGroup.backVisible) {
+	                        objectGroup.setBackVisible(true);
+	                    }
 	                }
 	                else {
 	                    objectGroup.setEdgesVisible(state === 1);
@@ -107281,7 +107654,10 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        this.hasAnimationLoop = false;
 	        this.display = display;
 	        if (options.keymap) {
-	            this.setKeyMap({ ...ViewerState.DISPLAY_DEFAULTS.keymap, ...options.keymap });
+	            this.setKeyMap({
+	                ...ViewerState.DISPLAY_DEFAULTS.keymap,
+	                ...options.keymap,
+	            });
 	        }
 	        else {
 	            this.setKeyMap(ViewerState.DISPLAY_DEFAULTS.keymap);
@@ -107602,7 +107978,8 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        this.renderer.renderLists.dispose();
 	        this.renderer.dispose();
 	        // Skip context loss for externally provided WebGL contexts
-	        if (!this._externalGl && typeof this.renderer.forceContextLoss === "function") {
+	        if (!this._externalGl &&
+	            typeof this.renderer.forceContextLoss === "function") {
 	            this.renderer.forceContextLoss();
 	        }
 	        console.debug("three-cad-viewer: WebGL context disposed");
@@ -107705,6 +108082,19 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            deepDispose(this.compactNestedGroup);
 	            this.compactNestedGroup = null;
 	        }
+	        // Reset scene-derived fields so the next render() recomputes them
+	        // from the new geometry. Without this, reuse (clear() + render())
+	        // re-uses stale values from the previous scene, producing wrong
+	        // camera framing and stale bookkeeping.
+	        this.bbox = null;
+	        this.bb_max = 0;
+	        this.bb_radius = 0;
+	        this.lastBbox = null;
+	        this.materialSettings = null;
+	        this.renderOptions = null;
+	        this.tree = null;
+	        this.compactTree = null;
+	        this.expandedTree = null;
 	    }
 	    /**
 	     * Build nestedGroup and treeview for initial render.
@@ -108003,16 +108393,28 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        this.setDirectLight(this.state.get("directIntensity"));
 	        this.display.setSliderLimits(this.gridSize / 2);
 	        this.display.syncClipSlidersFromState();
-	        // Compute clip slider values (used later after ready=true)
-	        const clipSlider0 = viewerOptions.clipSlider0 != null
-	            ? viewerOptions.clipSlider0
-	            : this.gridSize / 2;
-	        const clipSlider1 = viewerOptions.clipSlider1 != null
-	            ? viewerOptions.clipSlider1
-	            : this.gridSize / 2;
-	        const clipSlider2 = viewerOptions.clipSlider2 != null
-	            ? viewerOptions.clipSlider2
-	            : this.gridSize / 2;
+	        // Compute clip slider values (used later after ready=true).
+	        //
+	        // Three-tier policy:
+	        //   1. Caller passed a value (viewerOptions.clipSliderN != null) → use
+	        //      it. Caller intent always wins.
+	        //   2. Same geometry as last render (gridSize unchanged) AND state has
+	        //      a real value (≠ -1, the default sentinel) → reuse state. This
+	        //      preserves the user's slider drag when re-rendering the same
+	        //      model.
+	        //   3. New geometry (or first render) → default to gridSize/2.
+	        const gridSizeChanged = this._previousGridSize !== this.gridSize;
+	        this._previousGridSize = this.gridSize;
+	        const resolveSlider = (passed, stateValue) => {
+	            if (passed != null)
+	                return passed;
+	            if (!gridSizeChanged && stateValue !== -1)
+	                return stateValue;
+	            return this.gridSize / 2;
+	        };
+	        const clipSlider0 = resolveSlider(viewerOptions.clipSlider0, this.state.get("clipSlider0"));
+	        const clipSlider1 = resolveSlider(viewerOptions.clipSlider1, this.state.get("clipSlider1"));
+	        const clipSlider2 = resolveSlider(viewerOptions.clipSlider2, this.state.get("clipSlider2"));
 	        nestedGroup.setClipPlanes(clipping.clipPlanes);
 	        this.setLocalClipping(false); // only allow clipping when Clipping tab is selected
 	        clipping.setVisible(false);
@@ -108033,15 +108435,29 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            this.display.showToolsPanel(false);
 	            this.rendered.orientationMarker.setVisible(false);
 	        }
-	        // Apply clip settings AFTER ready=true (clip setters check this.ready)
-	        // Set normals first (if provided), passing slider values to avoid reset to gridSize/2
-	        this.setClipNormal(0, viewerOptions.clipNormal0 ?? null, clipSlider0, true);
-	        this.setClipNormal(1, viewerOptions.clipNormal1 ?? null, clipSlider1, true);
-	        this.setClipNormal(2, viewerOptions.clipNormal2 ?? null, clipSlider2, true);
-	        // Set sliders for any planes without custom normals (setClipNormal returns early if normal is null)
-	        this.setClipSlider(0, clipSlider0, true);
-	        this.setClipSlider(1, clipSlider1, true);
-	        this.setClipSlider(2, clipSlider2, true);
+	        // Apply clip settings AFTER ready=true (clip setters check this.ready).
+	        //
+	        // Same three-tier policy as clipSlider above (caller wins → reuse state
+	        // on same geometry → reset on new geometry). The default normals are
+	        // the axis-aligned planes that match the Clipping subsystem's own
+	        // DEFAULT_NORMALS.
+	        //
+	        // Always passing a non-null normal means setClipNormal also handles the
+	        // slider write (it calls setClipSlider internally), so no separate
+	        // setClipSlider follow-up is needed here.
+	        const resolveNormal = (passed, stateValue, defaultTuple) => {
+	            if (passed != null)
+	                return passed;
+	            if (!gridSizeChanged)
+	                return [stateValue.x, stateValue.y, stateValue.z];
+	            return defaultTuple;
+	        };
+	        const clipNormal0 = resolveNormal(viewerOptions.clipNormal0, this.state.get("clipNormal0"), [-1, 0, 0]);
+	        const clipNormal1 = resolveNormal(viewerOptions.clipNormal1, this.state.get("clipNormal1"), [0, -1, 0]);
+	        const clipNormal2 = resolveNormal(viewerOptions.clipNormal2, this.state.get("clipNormal2"), [0, 0, -1]);
+	        this.setClipNormal(0, clipNormal0, clipSlider0, true);
+	        this.setClipNormal(1, clipNormal1, clipSlider1, true);
+	        this.setClipNormal(2, clipNormal2, clipSlider2, true);
 	        this.setClipIntersection(viewerOptions.clipIntersection ?? false, true);
 	        this.setClipObjectColorCaps(viewerOptions.clipObjectColors ?? false, true);
 	        this.setClipPlaneHelpers(viewerOptions.clipPlaneHelpers ?? false, true);
@@ -108053,15 +108469,38 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	                // Computed values from controls/camera
 	                target: { old: null, new: toVector3Tuple(controls.target.toArray()) },
 	                target0: { old: null, new: toVector3Tuple(controls.target0.toArray()) },
-	                position: { old: null, new: this.rendered.camera.getPosition().toArray() },
-	                quaternion: { old: null, new: this.rendered.camera.getQuaternion().toArray() },
+	                position: {
+	                    old: null,
+	                    new: this.rendered.camera.getPosition().toArray(),
+	                },
+	                quaternion: {
+	                    old: null,
+	                    new: this.rendered.camera.getQuaternion().toArray(),
+	                },
 	                zoom: { old: null, new: this.rendered.camera.getZoom() },
 	                // All config values from state
 	                ...this.state.getAllNotifiable(),
 	            });
 	        }
 	        timer.split("notification done");
-	        this.update(true, false);
+	        // Initial paint and tab-landing logic.
+	        //
+	        // viewerOptions.tab can request a non-tree tab as the landing
+	        // tab. To avoid a CAD-mode → target-tab flicker, we skip the default
+	        // CAD update() in that case and let the activeTab subscription's
+	        // switchToTab handler paint the right content (or, for studio, show
+	        // the spinner over a blank canvas while async setup runs).
+	        const targetTab = viewerOptions.tab ?? "tree";
+	        if (targetTab === "tree") {
+	            this.update(true, false);
+	        }
+	        else {
+	            // setActiveTab fires the subscription synchronously; switchToTab
+	            // either paints (clip / zebra / material) or initiates Studio's
+	            // async load (showing the spinner). The first painted frame the
+	            // user sees is the target tab, not CAD.
+	            this.setActiveTab(targetTab);
+	        }
 	        treeview.update();
 	        this.display.setTheme(this.state.get("theme"));
 	        this.setZebraCount(this.state.get("zebraCount"));
@@ -108462,7 +108901,9 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        // Store current state
 	        const camera = this.rendered.camera.getCamera();
 	        const zoom = camera.zoom; // For orthographic cameras
-	        const offset = camera.position.clone().sub(this.rendered.controls.getTarget());
+	        const offset = camera.position
+	            .clone()
+	            .sub(this.rendered.controls.getTarget());
 	        // Update position and target
 	        camera.position.copy(targetVec.clone().add(offset));
 	        camera.updateWorldMatrix(true, false);
@@ -108697,7 +109138,10 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	                version: partData.version,
 	                id: wrapperId,
 	                name: "__addPart_tmp__",
-	                loc: [[0, 0, 0], [0, 0, 0, 1]],
+	                loc: [
+	                    [0, 0, 0],
+	                    [0, 0, 0, 1],
+	                ],
 	                parts: [partData],
 	            };
 	            const wrapperGroup = nestedGroup.renderLoop(wrapper);
@@ -108877,8 +109321,7 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            else {
 	                const edgePosAttr = group.edges.geometry.getAttribute("position");
 	                sameEdges =
-	                    edgePosAttr != null &&
-	                        edgePosAttr.count === flatLen(shape.edges) / 3;
+	                    edgePosAttr != null && edgePosAttr.count === flatLen(shape.edges) / 3;
 	            }
 	        }
 	        if (!sameVertices || !sameTriangles || !sameEdges) {
@@ -109009,7 +109452,8 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        // Only rebuild stencils if geometry grew beyond the region that stencils
 	        // were last built for.  Shrinking geometry still fits within existing
 	        // stencils, so skip the expensive rebuild in that case.
-	        const newCSize = 1.1 * Math.max(Math.abs(this.bbox.min.length()), Math.abs(this.bbox.max.length()));
+	        const newCSize = 1.1 *
+	            Math.max(Math.abs(this.bbox.min.length()), Math.abs(this.bbox.max.length()));
 	        if (newCSize > this._stencilCSize + 1e-6) {
 	            this._stencilCSize = newCSize;
 	            const clipping = this.rendered.clipping;
@@ -109055,9 +109499,7 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        }
 	        const min = new Vector3(bb.xmin, bb.ymin, bb.zmin);
 	        const max = new Vector3(bb.xmax, bb.ymax, bb.zmax);
-	        const center = new Vector3()
-	            .addVectors(min, max)
-	            .multiplyScalar(0.5);
+	        const center = new Vector3().addVectors(min, max).multiplyScalar(0.5);
 	        const requiredCSize = 1.1 * Math.max(Math.abs(min.length()), Math.abs(max.length()));
 	        if (requiredCSize > this._stencilCSize + 1e-6) {
 	            this._stencilCSize = requiredCSize;
@@ -109284,7 +109726,8 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            if (value === undefined)
 	                continue;
 	            if (modifierKeys.has(key)) {
-	                modifiers[key] = value;
+	                modifiers[key] =
+	                    value;
 	            }
 	            else {
 	                actions[key] = value;
@@ -109340,6 +109783,7 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	     */
 	    resizeCadView(cadWidth, treeWidth, height, glass = false) {
 	        this.state.set("cadWidth", cadWidth);
+	        this.state.set("treeWidth", treeWidth);
 	        this.state.set("height", height);
 	        // Adapt renderer dimensions
 	        this.renderer.setSize(cadWidth, height);
@@ -109397,7 +109841,9 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	         * @param notify - Whether to trigger the notification
 	         */
 	        this._notify = (value, notify = true) => {
-	            if (this.type == "plane" && this.notifyCallback && this.index !== undefined) {
+	            if (this.type == "plane" &&
+	                this.notifyCallback &&
+	                this.index !== undefined) {
 	                const change = {};
 	                change[`clip_slider_${this.index - 1}`] = parseFloat(String(value));
 	                this.notifyCallback(change, notify);
@@ -109441,7 +109887,8 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        this.onSetSlider = options.onSetSlider || null;
 	        const sliderEl = container.getElementsByClassName(`tcv_sld_value_${index}`)[0];
 	        const inputEl = container.getElementsByClassName(`tcv_inp_value_${index}`)[0];
-	        if (!(sliderEl instanceof HTMLInputElement) || !(inputEl instanceof HTMLInputElement)) {
+	        if (!(sliderEl instanceof HTMLInputElement) ||
+	            !(inputEl instanceof HTMLInputElement)) {
 	            throw new Error(`Slider elements not found for index "${index}" in container`);
 	        }
 	        this.slider = sliderEl;
@@ -109949,20 +110396,112 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	    return `${val}px`;
 	}
 	const MAT_EDITOR_PARAMS = [
-	    { key: "metalness", label: "Metallic", min: 0, max: 1, step: 0.01, group: "PBR Core" },
-	    { key: "roughness", label: "Roughness", min: 0, max: 1, step: 0.01, group: "PBR Core" },
-	    { key: "clearcoat", label: "Clearcoat", min: 0, max: 1, step: 0.01, group: "Clearcoat" },
-	    { key: "clearcoatRoughness", label: "Clearcoat Rough.", min: 0, max: 1, step: 0.01, group: "Clearcoat" },
-	    { key: "transmission", label: "Transmission", min: 0, max: 1, step: 0.01, group: "Transmission" },
-	    { key: "ior", label: "IOR", min: 1.0, max: 2.5, step: 0.01, group: "Transmission" },
-	    { key: "thickness", label: "Thickness", min: 0, max: 10, step: 0.1, group: "Transmission" },
-	    { key: "attenuationDistance", label: "Atten. Distance", min: 0, max: 100, step: 0.5, group: "Transmission", infinity: true },
+	    {
+	        key: "metalness",
+	        label: "Metallic",
+	        min: 0,
+	        max: 1,
+	        step: 0.01,
+	        group: "PBR Core",
+	    },
+	    {
+	        key: "roughness",
+	        label: "Roughness",
+	        min: 0,
+	        max: 1,
+	        step: 0.01,
+	        group: "PBR Core",
+	    },
+	    {
+	        key: "clearcoat",
+	        label: "Clearcoat",
+	        min: 0,
+	        max: 1,
+	        step: 0.01,
+	        group: "Clearcoat",
+	    },
+	    {
+	        key: "clearcoatRoughness",
+	        label: "Clearcoat Rough.",
+	        min: 0,
+	        max: 1,
+	        step: 0.01,
+	        group: "Clearcoat",
+	    },
+	    {
+	        key: "transmission",
+	        label: "Transmission",
+	        min: 0,
+	        max: 1,
+	        step: 0.01,
+	        group: "Transmission",
+	    },
+	    {
+	        key: "ior",
+	        label: "IOR",
+	        min: 1.0,
+	        max: 2.5,
+	        step: 0.01,
+	        group: "Transmission",
+	    },
+	    {
+	        key: "thickness",
+	        label: "Thickness",
+	        min: 0,
+	        max: 10,
+	        step: 0.1,
+	        group: "Transmission",
+	    },
+	    {
+	        key: "attenuationDistance",
+	        label: "Atten. Distance",
+	        min: 0,
+	        max: 100,
+	        step: 0.5,
+	        group: "Transmission",
+	        infinity: true,
+	    },
 	    { key: "sheen", label: "Sheen", min: 0, max: 1, step: 0.01, group: "Sheen" },
-	    { key: "sheenRoughness", label: "Sheen Roughness", min: 0, max: 1, step: 0.01, group: "Sheen" },
-	    { key: "specularIntensity", label: "Specular Intensity", min: 0, max: 2, step: 0.01, group: "Specular" },
-	    { key: "anisotropy", label: "Anisotropy", min: 0, max: 1, step: 0.01, group: "Anisotropy" },
-	    { key: "anisotropyRotation", label: "Anisotropy Rotation", min: 0, max: 6.28, step: 0.01, group: "Anisotropy" },
-	    { key: "emissiveIntensity", label: "Emissive Intensity", min: 0, max: 5, step: 0.1, group: "Emissive" },
+	    {
+	        key: "sheenRoughness",
+	        label: "Sheen Roughness",
+	        min: 0,
+	        max: 1,
+	        step: 0.01,
+	        group: "Sheen",
+	    },
+	    {
+	        key: "specularIntensity",
+	        label: "Specular Intensity",
+	        min: 0,
+	        max: 2,
+	        step: 0.01,
+	        group: "Specular",
+	    },
+	    {
+	        key: "anisotropy",
+	        label: "Anisotropy",
+	        min: 0,
+	        max: 1,
+	        step: 0.01,
+	        group: "Anisotropy",
+	    },
+	    {
+	        key: "anisotropyRotation",
+	        label: "Anisotropy Rotation",
+	        min: 0,
+	        max: 6.28,
+	        step: 0.01,
+	        group: "Anisotropy",
+	    },
+	    {
+	        key: "emissiveIntensity",
+	        label: "Emissive Intensity",
+	        min: 0,
+	        max: 5,
+	        step: 0.1,
+	        group: "Emissive",
+	    },
 	];
 	function _formatMatValue(value, step) {
 	    const decimals = step < 0.1 ? 2 : 1;
@@ -110411,7 +110950,13 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            if (!(e.target instanceof HTMLSelectElement))
 	                return;
 	            const value = e.target.value;
-	            if (value === "grey" || value === "darkgrey" || value === "white" || value === "gradient" || value === "gradient-dark" || value === "environment" || value === "transparent") {
+	            if (value === "grey" ||
+	                value === "darkgrey" ||
+	                value === "white" ||
+	                value === "gradient" ||
+	                value === "gradient-dark" ||
+	                value === "environment" ||
+	                value === "transparent") {
 	                this.state.set("studioBackground", value);
 	            }
 	        };
@@ -110629,7 +111174,8 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            // Skip if target is a text-entry input element (but allow buttons/checkboxes)
 	            const target = e.target;
 	            if ((target instanceof HTMLInputElement &&
-	                target.type !== "button" && target.type !== "checkbox") ||
+	                target.type !== "button" &&
+	                target.type !== "checkbox") ||
 	                target instanceof HTMLTextAreaElement ||
 	                target instanceof HTMLSelectElement) {
 	                return;
@@ -110773,7 +111319,7 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        this._spinnerEl = this.container.querySelector(".tcv_studio_spinner");
 	        this._warningBannerEl = this.container.querySelector(".tcv_warning_banner");
 	        this.container.addEventListener("tcv-material-warnings", ((e) => {
-	            this._showWarningBanner(`Unresolved material tag(s): ${e.detail.map(t => `"${t}"`).join(", ")}`);
+	            this._showWarningBanner(`Unresolved material tag(s): ${e.detail.map((t) => `"${t}"`).join(", ")}`);
 	        }));
 	        this.tabTree = this.getElement("tcv_tab_tree");
 	        this.tabClip = this.getElement("tcv_tab_clip");
@@ -111591,7 +112137,8 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	    attachCanvas(canvasElement) {
 	        // If the canvas is already attached elsewhere
 	        // do not re-parent it into this display.
-	        if (canvasElement.parentElement && canvasElement.parentElement !== this.cadView) {
+	        if (canvasElement.parentElement &&
+	            canvasElement.parentElement !== this.cadView) {
 	            listeners.add(canvasElement, "click", () => {
 	                if (this.help_shown) {
 	                    this.showHelp(false);
@@ -111642,7 +112189,8 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	    _deactivateToolsForStudio() {
 	        // If a tool is currently active, deactivate it cleanly
 	        const activeTool = this.state.get("activeTool");
-	        if (activeTool && ["distance", "properties", "angle", "select"].includes(activeTool)) {
+	        if (activeTool &&
+	            ["distance", "properties", "angle", "select"].includes(activeTool)) {
 	            this.clickButtons[activeTool]?.set(false);
 	            this.setTool(activeTool, false);
 	            // setTool→toggleTab(false) silently sets activeTab to "tree" (no notification).
@@ -111750,7 +112298,13 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            });
 	        }
 	        // Update tab styling
-	        [this.tabTree, this.tabClip, this.tabZebra, this.tabMaterial, this.tabStudio].forEach((tabEl) => {
+	        [
+	            this.tabTree,
+	            this.tabClip,
+	            this.tabZebra,
+	            this.tabMaterial,
+	            this.tabStudio,
+	        ].forEach((tabEl) => {
 	            tabEl.classList.add("tcv_tab-unselected");
 	            tabEl.classList.remove("tcv_tab-selected");
 	        });
@@ -111847,11 +112401,15 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            originalMat = currentMat;
 	            mat = currentMat.clone();
 	            // Preserve triplanar mapping if the original material uses it
-	            if (currentMat.customProgramCacheKey() === "triplanar" && object.shapeGeometry) {
+	            if (currentMat.customProgramCacheKey() === "triplanar" &&
+	                object.shapeGeometry) {
 	                applyTriplanarMapping(mat, object.shapeGeometry);
 	            }
 	            object.front.material = mat;
-	            this._matEditorClones.set(objectPath, { original: originalMat, clone: mat });
+	            this._matEditorClones.set(objectPath, {
+	                original: originalMat,
+	                clone: mat,
+	            });
 	        }
 	        // Restore elements that _showMatEditorHint may have hidden
 	        const resetBtn = dialog.querySelector(".tcv_mat_editor_reset");
@@ -111902,7 +112460,9 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        try {
 	            groups = this.viewer.rendered.nestedGroup.groups;
 	        }
-	        catch { /* not rendered */ }
+	        catch {
+	            /* not rendered */
+	        }
 	        for (const [path, { original, clone }] of this._matEditorClones.entries()) {
 	            // Restore original material on mesh before disposing the clone
 	            if (groups) {
@@ -111964,7 +112524,8 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            if (!(currentMat instanceof MeshPhysicalMaterial))
 	                continue;
 	            const clone = currentMat.clone();
-	            if (currentMat.customProgramCacheKey() === "triplanar" && group.shapeGeometry) {
+	            if (currentMat.customProgramCacheKey() === "triplanar" &&
+	                group.shapeGeometry) {
 	                applyTriplanarMapping(clone, group.shapeGeometry);
 	            }
 	            for (const [key, value] of Object.entries(changes)) {
@@ -111972,7 +112533,10 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	                clone[key] = value;
 	            }
 	            group.front.material = clone;
-	            this._matEditorClones.set(path, { original: currentMat, clone });
+	            this._matEditorClones.set(path, {
+	                original: currentMat,
+	                clone,
+	            });
 	        }
 	        this._savedMatEditorChanges.clear();
 	    }
@@ -112015,7 +112579,10 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            startX = e.clientX;
 	            startY = e.clientY;
 	            const rect = dialog.getBoundingClientRect();
-	            const parentRect = dialog.offsetParent?.getBoundingClientRect() ?? { left: 0, top: 0 };
+	            const parentRect = dialog.offsetParent?.getBoundingClientRect() ?? {
+	                left: 0,
+	                top: 0,
+	            };
 	            origLeft = rect.left - parentRect.left;
 	            origTop = rect.top - parentRect.top;
 	            // Switch from right-positioning to left-positioning for drag
@@ -112029,8 +112596,8 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	                return;
 	            const dx = e.clientX - startX;
 	            const dy = e.clientY - startY;
-	            dialog.style.left = (origLeft + dx) + "px";
-	            dialog.style.top = (origTop + dy) + "px";
+	            dialog.style.left = origLeft + dx + "px";
+	            dialog.style.top = origTop + dy + "px";
 	        }, { signal });
 	        document.addEventListener("mouseup", () => {
 	            dragging = false;
@@ -112048,7 +112615,8 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	            }
 	            let currentValue = // eslint-disable-next-line @typescript-eslint/no-explicit-any
 	             material[param.key];
-	            const isInfinity = param.infinity === true && (currentValue === Infinity || currentValue == null);
+	            const isInfinity = param.infinity === true &&
+	                (currentValue === Infinity || currentValue == null);
 	            if (isInfinity)
 	                currentValue = param.max;
 	            this._buildMatEditorRow(content, param, currentValue ?? 0, isInfinity, originalMat);
@@ -112060,8 +112628,8 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        // eslint-disable-next-line @typescript-eslint/no-explicit-any
 	        const origValue = originalMat[param.key];
 	        const isChanged = (v) => param.infinity
-	            ? (v >= param.max) !== (origValue === Infinity || origValue == null)
-	                || (v < param.max && Math.abs(v - origValue) > param.step * 0.5)
+	            ? v >= param.max !== (origValue === Infinity || origValue == null) ||
+	                (v < param.max && Math.abs(v - origValue) > param.step * 0.5)
 	            : Math.abs(v - origValue) > param.step * 0.5;
 	        const label = document.createElement("label");
 	        label.className = "tcv_mat_editor_label";
@@ -112081,7 +112649,9 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        const valueDisplay = document.createElement("input");
 	        valueDisplay.className = "tcv_clip_input";
 	        valueDisplay.readOnly = true;
-	        valueDisplay.value = isInfinity ? "\u221E" : _formatMatValue(value, param.step);
+	        valueDisplay.value = isInfinity
+	            ? "\u221E"
+	            : _formatMatValue(value, param.step);
 	        slider.addEventListener("input", () => {
 	            const newValue = parseFloat(slider.value);
 	            const result = this.viewer.getSelectedObjectGroup();
@@ -112170,7 +112740,8 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        this.studioShadowIntensitySlider?.setValueFromState(state.get("studioShadowIntensity") * 100);
 	        this.studioShadowSoftnessSlider?.setValueFromState(state.get("studioShadowSoftness") * 100);
 	        this.studioAOIntensitySlider?.setValueFromState(state.get("studioAOIntensity") * 10);
-	        this.getInputElement("tcv_studio_4k_env_maps").checked = state.get("studio4kEnvMaps");
+	        this.getInputElement("tcv_studio_4k_env_maps").checked =
+	            state.get("studio4kEnvMaps");
 	        this._syncEnvDropdown(state.get("studioEnvironment"));
 	        const bgEl = this.container.querySelector(".tcv_studio_background");
 	        if (bgEl instanceof HTMLSelectElement)
@@ -112199,7 +112770,10 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        }
 	        else {
 	            // Add or update a "Custom" optgroup with the custom HDR entry
-	            const label = envName.split("/").pop()?.replace(/\.hdr$/i, "") || "Custom HDR";
+	            const label = envName
+	                .split("/")
+	                .pop()
+	                ?.replace(/\.hdr$/i, "") || "Custom HDR";
 	            let customGroup = el.querySelector("optgroup[data-custom]");
 	            if (customGroup) {
 	                const opt = customGroup.querySelector("option");
@@ -112230,7 +112804,8 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	        const isPreset = this.viewer.envManager.isPreset(envName);
 	        cb.disabled = !isPreset;
 	        if (!isPreset) {
-	            cb.title = "4K switching is only available for built-in Poly Haven presets";
+	            cb.title =
+	                "4K switching is only available for built-in Poly Haven presets";
 	        }
 	        else {
 	            cb.title = "";
@@ -112263,8 +112838,17 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	    _dispatchAction(action) {
 	        // Toggle buttons
 	        const toggleActions = [
-	            "axes", "axes0", "grid", "perspective", "transparent", "blackedges",
-	            "explode", "zscale", "distance", "properties", "select",
+	            "axes",
+	            "axes0",
+	            "grid",
+	            "perspective",
+	            "transparent",
+	            "blackedges",
+	            "explode",
+	            "zscale",
+	            "distance",
+	            "properties",
+	            "select",
 	        ];
 	        if (toggleActions.includes(action)) {
 	            this._toggleClickButton(action);
@@ -112474,6 +113058,7 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	     * @public
 	     */
 	    setTheme(theme) {
+	        let resolved;
 	        if (theme === "dark" ||
 	            (theme === "browser" &&
 	                window.matchMedia("(prefers-color-scheme: dark)").matches)) {
@@ -112485,7 +113070,7 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	                this.viewer.gridHelper.update(this.viewer.getCameraZoom(), true, "dark");
 	            }
 	            this.viewer.update(true);
-	            return "dark";
+	            resolved = "dark";
 	        }
 	        else {
 	            this.container.setAttribute("data-theme", "light");
@@ -112496,8 +113081,14 @@ void mainImage(const in vec4 inputColor, const in vec2 uv, const in float depth,
 	                this.viewer.gridHelper.update(this.viewer.getCameraZoom(), true, "light");
 	            }
 	            this.viewer.update(true);
-	            return "light";
-	        }
+	            resolved = "light";
+	        }
+	        // Keep state.theme in sync with the DOM. Without this, paths that call
+	        // setTheme directly (matchMedia listener, viewer.setTheme, MutationObserver
+	        // bridges) would update the DOM while leaving state.theme stale, and the
+	        // next viewer.render() would re-apply the stale state value
+	        this.viewer.state.set("theme", resolved, false);
+	        return resolved;
 	    }
 	}