three-cad-viewer 4.1.2 → 4.2.0

package/src/ui/display.ts

@@ -15,11 +15,13 @@ import type {
 import { FilterByDropDownMenu } from "../tools/cad_tools/ui.js";
 import { Info } from "./info.js";
 import type { Viewer } from "../core/viewer.js";
+import type { ObjectGroup } from "../scene/objectgroup.js";
 import type { ViewerState } from "../core/viewer-state.js";
 import { isClipIndex, CollapseState } from "../core/types.js";
 import type { Vector3Tuple } from "three";
 import type { ActiveTab, ThemeInput, ClipIndex } from "../core/types.js";
 import type { CameraDirection } from "../camera/camera.js";
+import { applyTriplanarMapping } from "../rendering/triplanar.js";
 
 import template from "./index.html";
 
@@ -41,6 +43,42 @@ function px(val: number): string {
   return `${val}px`;
 }
 
+// ---------------------------------------------------------------------------
+// Material Editor Parameter Definitions
+// ---------------------------------------------------------------------------
+
+interface MatEditorParam {
+  key: string;
+  label: string;
+  min: number;
+  max: number;
+  step: number;
+  group: string;
+  infinity?: boolean;
+}
+
+const MAT_EDITOR_PARAMS: MatEditorParam[] = [
+  { 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" },
+];
+
+function _formatMatValue(value: number, step: number): string {
+  const decimals = step < 0.1 ? 2 : 1;
+  return value.toFixed(decimals);
+}
+
 const buttons = ["plane", "play", "pause", "stop"];
 
 const listeners = new EventListenerManager();
@@ -59,6 +97,7 @@ export interface DisplayOptions {
   explodeTool: boolean;
   zscaleTool: boolean;
   zebraTool: boolean;
+  studioTool: boolean;
   glass: boolean;
   tools: boolean;
   cadWidth: number;
@@ -67,6 +106,8 @@ export interface DisplayOptions {
   treeHeight?: number;
   theme: ThemeInput;
   pinning: boolean;
+  canvas?: HTMLCanvasElement;
+  gl?: WebGLRenderingContext | WebGL2RenderingContext;
 }
 
 /**
@@ -150,17 +191,34 @@ class Display {
   cadTree!: HTMLElement;
   cadTreeScrollContainer!: HTMLElement;
   cadTreeToggles!: HTMLElement;
+  cadClipToggles!: HTMLElement;
+  cadMaterialToggles!: HTMLElement;
+  cadZebraToggles!: HTMLElement;
+  cadStudioToggles!: HTMLElement;
   cadClip!: HTMLElement;
   cadMaterial!: HTMLElement;
   cadZebra!: HTMLElement;
+  cadStudio!: HTMLElement;
+  private _spinnerEl: HTMLElement | null = null;
+  private _warningBannerEl: HTMLElement | null = null;
+  private _warningBannerTimer: ReturnType<typeof setTimeout> | null = null;
+  private _spinnerCount: number = 0;
+  // Material editor state
+  private _matEditorPath: string | null = null;
+  private _matEditorClones: Map<string, { original: THREE.MeshPhysicalMaterial; clone: THREE.MeshPhysicalMaterial }> = new Map();
+  private _savedMatEditorChanges: Map<string, Record<string, number>> = new Map();
+  private _matEditorDragAbort: AbortController | null = null;
+  private _matEditorInputAbort: AbortController | null = null;
   cadInfo!: HTMLElement;
   cadAnim!: HTMLElement;
+  private _animWasVisible: boolean = false;
   cadTools!: HTMLElement;
   cadHelp!: HTMLElement;
   tabTree!: HTMLElement;
   tabClip!: HTMLElement;
   tabMaterial!: HTMLElement;
   tabZebra!: HTMLElement;
+  tabStudio!: HTMLElement;
   tickValueElement!: HTMLElement;
   tickInfoElement!: HTMLElement;
   distanceMeasurementPanel!: HTMLElement;
@@ -186,6 +244,12 @@ class Display {
   zebraCountSlider: Slider | undefined;
   zebraOpacitySlider: Slider | undefined;
   zebraDirectionSlider: Slider | undefined;
+  studioEnvIntensitySlider: Slider | undefined;
+  studioExposureSlider: Slider | undefined;
+  studioEnvRotationSlider: Slider | undefined;
+  studioShadowIntensitySlider: Slider | undefined;
+  studioShadowSoftnessSlider: Slider | undefined;
+  studioAOIntensitySlider: Slider | undefined;
 
   // State - set in setupUI() which is called at end of Viewer constructor
   viewer!: Viewer;
@@ -205,6 +269,7 @@ class Display {
   lastPlaneState: boolean;
   help_shown: boolean;
   info_shown: boolean;
+  tools_shown: boolean;
 
   // Info panel
   _info: Info;
@@ -288,14 +353,27 @@ class Display {
 
     this.cadTree = this.getElement("tcv_cad_tree_container");
     this.cadTreeScrollContainer = this.getElement("tcv_box_content");
-    this.cadTreeToggles = this.getElement("tcv_cad_tree_toggles");
+    this.cadTreeToggles = this.getElement("tcv_toggles_tree");
+    this.cadClipToggles = this.getElement("tcv_toggles_clip");
+    this.cadMaterialToggles = this.getElement("tcv_toggles_material");
+    this.cadZebraToggles = this.getElement("tcv_toggles_zebra");
+    this.cadStudioToggles = this.getElement("tcv_toggles_studio");
     this.cadClip = this.getElement("tcv_cad_clip_container");
     this.cadMaterial = this.getElement("tcv_cad_material_container");
     this.cadZebra = this.getElement("tcv_cad_zebra_container");
+    this.cadStudio = this.getElement("tcv_cad_studio_container");
+    this._spinnerEl = this.container.querySelector(".tcv_studio_spinner") as HTMLElement | null;
+    this._warningBannerEl = this.container.querySelector(".tcv_warning_banner") as HTMLElement | null;
+    this.container.addEventListener("tcv-material-warnings", ((e: CustomEvent<string[]>) => {
+      this._showWarningBanner(
+        `Unresolved material tag(s): ${e.detail.map(t => `"${t}"`).join(", ")}`,
+      );
+    }) as EventListener);
     this.tabTree = this.getElement("tcv_tab_tree");
     this.tabClip = this.getElement("tcv_tab_clip");
-    this.tabMaterial = this.getElement("tcv_tab_material");
     this.tabZebra = this.getElement("tcv_tab_zebra");
+    this.tabMaterial = this.getElement("tcv_tab_material");
+    this.tabStudio = this.getElement("tcv_tab_studio");
     this.cadInfo = this.getElement("tcv_cad_info_container");
     this._info = new Info(this.cadInfo);
     this.tickValueElement = this.getElement("tcv_tick_size_value");
@@ -305,6 +383,9 @@ class Display {
     if (!options.zebraTool) {
       this.tabZebra.style.display = "none";
     }
+    if (options.studioTool === false) {
+      this.tabStudio.style.display = "none";
+    }
     this.cadHelp = this.getElement("tcv_cad_help");
     listeners.add(this.cadHelp, "contextmenu", (e) => {
       e.preventDefault();
@@ -331,6 +412,7 @@ class Display {
     this.cadClip.style.display = "none";
     this.cadMaterial.style.display = "none";
     this.cadZebra.style.display = "none";
+    this.cadStudio.style.display = "none";
     this.clipSliders = null;
 
     // Note: activeTool is managed by ViewerState, not stored locally
@@ -338,6 +420,7 @@ class Display {
     this.lastPlaneState = false;
     this.help_shown = true;
     this.info_shown = !this.glass;
+    this.tools_shown = true;
 
     const theme = options.theme;
     this.theme = theme;
@@ -623,6 +706,15 @@ class Display {
     this._events.push(["change", name, fn]);
   }
 
+  /**
+   * Wire a select element's change event
+   */
+  private setupSelectEvent(name: string, fn: EventListener): void {
+    const el = this.getElement(name);
+    listeners.add(el, "change", fn);
+    this._events.push(["change", name, fn]);
+  }
+
   /**
    * Get a DOM element by class name (internal use only).
    * @param name - Name of the DOM element class
@@ -693,10 +785,21 @@ class Display {
     this.zebraCountSlider?.dispose();
     this.zebraOpacitySlider?.dispose();
     this.zebraDirectionSlider?.dispose();
+    this.studioEnvIntensitySlider?.dispose();
+    this.studioExposureSlider?.dispose();
+    this.studioEnvRotationSlider?.dispose();
+    this.studioAOIntensitySlider?.dispose();
+
+    // Clean up material editor
+    this._matEditorDragAbort?.abort();
+    this.disposeMatEditorClones();
 
     // Clear DOM content (elements remain valid until Display is GC'd)
     this.cadTree.innerHTML = "";
-    this.cadView.removeChild(this.cadView.children[2]);
+    const attachedCanvas = this.cadView.querySelector("canvas");
+    if (attachedCanvas && attachedCanvas.parentElement === this.cadView) {
+      this.cadView.removeChild(attachedCanvas);
+    }
     this.container.innerHTML = "";
   }
 
@@ -790,6 +893,7 @@ class Display {
       this.height = options.height;
       this.cadView.style.height = px(options.height);
     }
+
     if (options.treeWidth) {
       this.treeWidth = options.treeWidth;
       this.cadTree.parentElement!.parentElement!.style.width = px(
@@ -856,9 +960,12 @@ class Display {
     this.setupClickEvent("tcv_collapse_all", this.handleCollapseNodes);
     this.setupClickEvent("tcv_expand", this.handleCollapseNodes);
 
+    this.setupClickEvent("tcv_clip_reset", this.handleClipReset);
     this.setupClickEvent("tcv_material_reset", this.handleMaterialReset);
+    this.setupClickEvent("tcv_zebra_reset", this.handleZebraReset);
 
     this.setupClickEvent("tcv_toggle_info", this.toggleInfo);
+    this.setupClickEvent("tcv_toggle_tools_wrapper", this.toggleToolsPanel);
 
     this.help_shown = true;
     this.info_shown = !this.glass;
@@ -866,8 +973,9 @@ class Display {
     const tabs = [
       "tcv_tab_tree",
       "tcv_tab_clip",
-      "tcv_tab_material",
       "tcv_tab_zebra",
+      "tcv_tab_material",
+      "tcv_tab_studio",
     ];
     tabs.forEach((name) => {
       this.setupClickEvent(name, this.selectTab);
@@ -975,6 +1083,101 @@ class Display {
       this.setupRadioEvent(`tcv_zebra_mapping${id}`, this.setZebraMappingMode);
     });
 
+    // Studio tab controls
+    this.studioEnvIntensitySlider = new Slider(
+      "studio_env_intensity",
+      0,
+      300,
+      this.container,
+      {
+        handler: this.handleStudioEnvIntensity,
+        percentage: true,
+        isReadyCheck: viewerReadyCheck,
+      },
+    );
+    this.studioExposureSlider = new Slider(
+      "studio_exposure",
+      0,
+      300,
+      this.container,
+      {
+        handler: this.handleStudioExposure,
+        percentage: true,
+        isReadyCheck: viewerReadyCheck,
+      },
+    );
+    this.studioEnvRotationSlider = new Slider(
+      "studio_env_rotation",
+      0,
+      360,
+      this.container,
+      {
+        handler: this.handleStudioEnvRotation,
+        isReadyCheck: viewerReadyCheck,
+      },
+    );
+
+    this.studioShadowIntensitySlider = new Slider(
+      "studio_shadow_intensity",
+      0,
+      100,
+      this.container,
+      {
+        handler: this.handleStudioShadowIntensity,
+        percentage: true,
+        isReadyCheck: viewerReadyCheck,
+      },
+    );
+    this.studioShadowSoftnessSlider = new Slider(
+      "studio_shadow_softness",
+      0,
+      100,
+      this.container,
+      {
+        handler: this.handleStudioShadowSoftness,
+        percentage: true,
+        isReadyCheck: viewerReadyCheck,
+      },
+    );
+    this.studioAOIntensitySlider = new Slider(
+      "studio_ao_intensity",
+      0,
+      30,
+      this.container,
+      {
+        handler: this.handleStudioAOIntensity,
+        isReadyCheck: viewerReadyCheck,
+      },
+    );
+    this.setupCheckEvent(
+      "tcv_studio_4k_env_maps",
+      this.handleStudio4kEnvMaps,
+      false,
+    );
+
+    this.setupSelectEvent(
+      "tcv_studio_environment",
+      this.handleStudioEnvironment,
+    );
+    this.setupSelectEvent(
+      "tcv_studio_background",
+      this.handleStudioBackground,
+    );
+    this.setupSelectEvent(
+      "tcv_studio_tone_mapping",
+      this.handleStudioToneMapping,
+    );
+    this.setupSelectEvent(
+      "tcv_studio_texture_mapping",
+      this.handleStudioTextureMapping,
+    );
+
+    this.setupClickEvent("tcv_studio_reset", this.handleStudioReset);
+    this.setupClickEvent("tcv_mat_editor_toggle", this.handleMatEditorToggle);
+    this.setupClickEvent("tcv_mat_editor_close", () => this.closeMatEditor());
+    this.setupClickEvent("tcv_mat_editor_reset", this.handleMatEditorReset);
+    this._initMatEditorDrag();
+
     this.setupClickEvent("tcv_play", this.controlAnimation);
     this.setupClickEvent("tcv_pause", this.controlAnimation);
     this.setupClickEvent("tcv_stop", this.controlAnimation);
@@ -1066,6 +1269,9 @@ class Display {
 
     sub("tools", (change) => {
       this.showTools(change.new);
+      const animationMode = this.state.get("animationMode");
+      this.cadAnim.style.display =
+        change.new && animationMode !== "none" ? "block" : "none";
     });
 
     sub("glass", (change) => {
@@ -1160,13 +1366,78 @@ class Display {
       this.setZebraMappingModeSelect(change.new);
     });
 
+    // Studio tab subscriptions
+    sub("studioEnvironment", (change) => {
+      this._syncEnvDropdown(change.new);
+      this._update4kCheckboxEnabled(change.new);
+    });
+    sub(
+      "studioEnvIntensity",
+      (change) => {
+        this.studioEnvIntensitySlider?.setValueFromState(change.new * 100);
+      },
+      { immediate: true },
+    );
+    sub(
+      "studioEnvRotation",
+      (change) => {
+        this.studioEnvRotationSlider?.setValueFromState(change.new);
+      },
+      { immediate: true },
+    );
+    sub("studioBackground", (change) => {
+      const el = this.container.querySelector(".tcv_studio_background");
+      if (el instanceof HTMLSelectElement) el.value = change.new;
+    });
+    sub("studioToneMapping", (change) => {
+      const el = this.container.querySelector(".tcv_studio_tone_mapping");
+      if (el instanceof HTMLSelectElement) el.value = change.new;
+    });
+    sub("studioTextureMapping", (change) => {
+      const el = this.container.querySelector(".tcv_studio_texture_mapping");
+      if (el instanceof HTMLSelectElement) el.value = change.new;
+    });
+    sub(
+      "studioExposure",
+      (change) => {
+        this.studioExposureSlider?.setValueFromState(change.new * 100);
+      },
+      { immediate: true },
+    );
+    sub(
+      "studioShadowIntensity",
+      (change) => {
+        this.studioShadowIntensitySlider?.setValueFromState(change.new * 100);
+      },
+      { immediate: true },
+    );
+    sub(
+      "studioShadowSoftness",
+      (change) => {
+        this.studioShadowSoftnessSlider?.setValueFromState(change.new * 100);
+      },
+      { immediate: true },
+    );
+    sub(
+      "studioAOIntensity",
+      (change) => {
+        this.studioAOIntensitySlider?.setValueFromState(change.new * 10);
+      },
+      { immediate: true },
+    );
+    sub("studio4kEnvMaps", (change) => {
+      this.getInputElement("tcv_studio_4k_env_maps").checked = change.new;
+    });
+
     // Animation/Explode mode subscription - controls slider visibility, label, and explode button
     sub(
       "animationMode",
       (change) => {
         const mode = change.new;
-        // Show/hide slider control
-        this.cadAnim.style.display = mode !== "none" ? "block" : "none";
+        const toolsEnabled = this.state.get("tools");
+        // Show/hide slider control (only when tools panel is enabled)
+        this.cadAnim.style.display =
+          toolsEnabled && mode !== "none" ? "block" : "none";
         // Set label: "A" for animation, "E" for explode
         this.getElement("tcv_animation_label").innerHTML =
           mode === "explode" ? "E" : "A";
@@ -1263,9 +1534,10 @@ class Display {
     this.lastPlaneState =
       typeof clipPlaneHelpers === "boolean" ? clipPlaneHelpers : false;
 
-    // Sync material and zebra sliders with current state values
+    // Sync material, zebra, and studio sliders with current state values
     this.syncMaterialSlidersFromState();
     this.syncZebraSlidersFromState();
+    this.syncStudioSlidersFromState();
   }
 
   // ---------------------------------------------------------------------------
@@ -1286,6 +1558,17 @@ class Display {
    * @param canvasElement - The canvas to attach.
    */
   private attachCanvas(canvasElement: HTMLCanvasElement): void {
+    // If the canvas is already attached elsewhere
+    // do not re-parent it into this display.
+    if (canvasElement.parentElement && canvasElement.parentElement !== this.cadView) {
+      listeners.add(canvasElement, "click", () => {
+        if (this.help_shown) {
+          this.showHelp(false);
+        }
+      });
+      return;
+    }
+
     const existingCanvas = this.cadView.querySelector("canvas");
     if (existingCanvas) {
       this.cadView.replaceChild(canvasElement, existingCanvas);
@@ -1303,7 +1586,9 @@ class Display {
    * Get the DOM canvas element
    */
   getCanvas(): Element {
-    return this.cadView.children[this.cadView.children.length - 1];
+    const localCanvas = this.cadView.querySelector("canvas");
+    if (localCanvas) return localCanvas;
+    return this.viewer.renderer.domElement;
   }
 
   /**
@@ -1409,6 +1694,10 @@ class Display {
    * Delegates state mutations to Viewer.activateTool() to maintain unidirectional data flow.
    */
   setTool = (name: string, flag: boolean): void => {
+    // Block tool activation while Studio mode is active
+    if (flag && this.viewer.isStudioActive) {
+      return;
+    }
     this.viewer.toggleAnimationLoop(flag);
     const activeTool = this.state.get("activeTool");
     const currentTool = typeof activeTool === "string" ? activeTool : "";
@@ -1469,16 +1758,32 @@ class Display {
     this.tools = flag;
     const tb = this.getElement("tcv_cad_toolbar");
     const cn = this.getElement("tcv_cad_navigation");
+    const tickInfo = this.tickInfoElement;
     if (flag) {
       tb.style.height = "38px";
       tb.style.display = "flex";
       cn.style.height = "38px";
       cn.style.display = "block";
+
+      // Tick size badge belongs to the tools UI. Restore it only when tools are visible and at least one grid is visible.
+      if (tickInfo) {
+        if (this.viewer?.ready) {
+          tickInfo.style.display = this.viewer.rendered.gridHelper.getVisible()
+            ? "block"
+            : "none";
+        } else {
+          tickInfo.style.display = "none";
+        }
+      }
     } else {
       tb.style.height = "0px";
       tb.style.display = "none";
       cn.style.height = "0px";
       cn.style.display = "none";
+
+      if (tickInfo) {
+        tickInfo.style.display = "none";
+      }
     }
   };
 
@@ -1514,6 +1819,38 @@ class Display {
     }
   };
 
+  /**
+   * Deactivate any running tool and hide tool buttons for Studio mode.
+   * Called when entering Studio mode.
+   * @internal
+   */
+  private _deactivateToolsForStudio(): void {
+    // If a tool is currently active, deactivate it cleanly
+    const activeTool = this.state.get("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).
+      // Restore to "studio" so the next tab click correctly detects Studio as oldTab.
+      this.state.set("activeTab", "studio", false);
+    }
+
+    // Hide tool buttons
+    this.showMeasureTools(false);
+    this.showSelectTool(false);
+  }
+
+  /**
+   * Restore tool button visibility after leaving Studio mode.
+   * Respects original feature flags (measureTools, selectTool).
+   * Does not auto-activate any tool.
+   * @internal
+   */
+  private _restoreToolsAfterStudio(): void {
+    this.showMeasureTools(this.measureTools);
+    this.showSelectTool(this.selectTool);
+  }
+
   // ---------------------------------------------------------------------------
   // Clipping Handlers
   // ---------------------------------------------------------------------------
@@ -1629,8 +1966,9 @@ class Display {
     if (
       tabName === "clip" ||
       tabName === "tree" ||
+      tabName === "zebra" ||
       tabName === "material" ||
-      tabName === "zebra"
+      tabName === "studio"
     ) {
       this.viewer.setActiveTab(tabName);
     }
@@ -1640,41 +1978,62 @@ class Display {
    * Switch to a tab (internal, called by activeTab subscription).
    */
   private switchToTab(newTab: ActiveTab, oldTab?: ActiveTab): void {
-    if (!["clip", "tree", "material", "zebra"].includes(newTab)) {
+    if (!["clip", "tree", "zebra", "material", "studio"].includes(newTab)) {
       return;
     }
 
+    // --- Leave the OLD mode FIRST (before _updateVisibility runs) ---
+    // This ensures all state (clipping, materials, etc.) is restored
+    // before the new tab's controls are activated.
+    if (oldTab === "zebra" && newTab !== "zebra") {
+      this.viewer.enableZebraTool(false);
+    }
+    if (oldTab === "studio" && newTab !== "studio") {
+      this.closeMatEditor();
+      this._saveMatEditorChanges();
+      this.disposeMatEditorClones();
+      this.viewer.leaveStudioMode();
+      this._hideWarningBanner();
+      // Restore tool button visibility based on feature flags
+      this._restoreToolsAfterStudio();
+    }
+
     const _updateVisibility = (
       showTree: boolean,
       showClip: boolean,
-      showMaterial: boolean,
       showZebra: boolean,
+      showMaterial: boolean,
+      showStudio: boolean,
     ) => {
       this.cadTree.style.display = showTree ? "block" : "none";
       this.cadTreeToggles.style.display = showTree ? "block" : "none";
+      this.cadClipToggles.style.display = showClip ? "block" : "none";
       this.cadClip.style.display = showClip ? "block" : "none";
-      this.cadMaterial.style.display = showMaterial ? "block" : "none";
+      this.cadZebraToggles.style.display = showZebra ? "block" : "none";
       this.cadZebra.style.display = showZebra ? "block" : "none";
+      this.cadMaterialToggles.style.display = showMaterial ? "block" : "none";
+      this.cadMaterial.style.display = showMaterial ? "block" : "none";
+      this.cadStudioToggles.style.display = showStudio ? "block" : "none";
+      this.cadStudio.style.display = showStudio ? "block" : "none";
 
       this.viewer.clipping.setVisible(showClip);
       this.viewer.setLocalClipping(showClip);
       if (!showClip) {
         this.viewer.setClipPlaneHelpers(false);
       }
-      if (newTab !== "zebra" && oldTab === "zebra") {
-        this.viewer.enableZebraTool(false);
-      }
+      // NOTE: zebra and studio leave calls removed from here --
+      // they now run above, before _updateVisibility is called.
     };
 
     if (newTab === "tree") {
-      _updateVisibility(true, false, false, false);
+      _updateVisibility(true, false, false, false, false);
       this.viewer.nestedGroup.setBackVisible(false);
       // Lazy-rendered tree nodes may be stale if the tree was rebuilt
       // while this tab was hidden (display:none → getBoundingClientRect
       // returns zero, so update() rendered nothing).  Kick it now.
       this.viewer.treeview?.update();
     } else if (newTab === "clip") {
-      _updateVisibility(false, true, false, false);
+      _updateVisibility(false, true, false, false, false);
       this.viewer.nestedGroup.setBackVisible(true);
       const clipIntersection = this.viewer.state.get("clipIntersection");
       if (typeof clipIntersection === "boolean") {
@@ -1682,16 +2041,30 @@ class Display {
       }
       this.viewer.setClipPlaneHelpers(this.lastPlaneState);
       this.viewer.update(true, false);
-    } else if (newTab === "material") {
-      _updateVisibility(false, false, true, false);
-      this.viewer.nestedGroup.setBackVisible(false);
     } else if (newTab === "zebra") {
-      _updateVisibility(false, false, false, true);
+      _updateVisibility(false, false, true, false, false);
       this.viewer.enableZebraTool(true);
+    } else if (newTab === "material") {
+      _updateVisibility(false, false, false, true, false);
+      this.viewer.nestedGroup.setBackVisible(false);
+    } else if (newTab === "studio") {
+      _updateVisibility(false, false, false, false, true);
+      this.viewer.nestedGroup.setBackVisible(false);
+
+      // Disable any active tool before entering Studio mode
+      this._deactivateToolsForStudio();
+
+      this._showSpinner();
+      this.viewer.enterStudioMode().finally(() => {
+        this._hideSpinner();
+        this._reapplyMatEditorChanges();
+        this.syncStudioSlidersFromState();
+        this.viewer.update(true, false);
+      });
     }
 
     // Update tab styling
-    [this.tabTree, this.tabClip, this.tabMaterial, this.tabZebra].forEach(
+    [this.tabTree, this.tabClip, this.tabZebra, this.tabMaterial, this.tabStudio].forEach(
       (tabEl) => {
         tabEl.classList.add("tcv_tab-unselected");
         tabEl.classList.remove("tcv_tab-selected");
@@ -1705,12 +2078,47 @@ class Display {
     } else if (newTab === "clip") {
       this.tabClip.classList.add("tcv_tab-selected");
       this.tabClip.classList.remove("tcv_tab-unselected");
+    } else if (newTab === "zebra") {
+      this.tabZebra.classList.add("tcv_tab-selected");
+      this.tabZebra.classList.remove("tcv_tab-unselected");
     } else if (newTab === "material") {
       this.tabMaterial.classList.add("tcv_tab-selected");
       this.tabMaterial.classList.remove("tcv_tab-unselected");
-    } else if (newTab === "zebra") {
-      this.tabZebra.classList.remove("tcv_tab-unselected");
-      this.tabZebra.classList.add("tcv_tab-selected");
+    } else if (newTab === "studio") {
+      this.tabStudio.classList.add("tcv_tab-selected");
+      this.tabStudio.classList.remove("tcv_tab-unselected");
+    }
+  }
+
+  /** Show the toolbar spinner (ref-counted for overlapping async ops). */
+  private _showSpinner(): void {
+    this._spinnerCount++;
+    if (this._spinnerEl) this._spinnerEl.style.display = "block";
+  }
+
+  /** Hide the toolbar spinner (only when all pending ops complete). */
+  private _hideSpinner(): void {
+    this._spinnerCount = Math.max(0, this._spinnerCount - 1);
+    if (this._spinnerCount === 0 && this._spinnerEl) {
+      this._spinnerEl.style.display = "none";
+    }
+  }
+
+  /** Show a warning banner in the viewport. Auto-hides after 8 seconds. */
+  private _showWarningBanner(message: string): void {
+    if (!this._warningBannerEl) return;
+    this._warningBannerEl.textContent = message;
+    this._warningBannerEl.style.display = "block";
+    if (this._warningBannerTimer) clearTimeout(this._warningBannerTimer);
+    this._warningBannerTimer = setTimeout(() => this._hideWarningBanner(), 8000);
+  }
+
+  /** Hide the warning banner. */
+  private _hideWarningBanner(): void {
+    if (this._warningBannerEl) this._warningBannerEl.style.display = "none";
+    if (this._warningBannerTimer) {
+      clearTimeout(this._warningBannerTimer);
+      this._warningBannerTimer = null;
     }
   }
 
@@ -1745,6 +2153,17 @@ class Display {
     }
   };
 
+  // ---------------------------------------------------------------------------
+  // Clip Reset Handler
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Reset clip planes to default normals and slider positions
+   */
+  handleClipReset = (_e: Event): void => {
+    this.viewer.resetClip();
+  };
+
   // ---------------------------------------------------------------------------
   // Material Handlers
   // ---------------------------------------------------------------------------
@@ -1756,6 +2175,468 @@ class Display {
     this.viewer.resetMaterial();
   };
 
+  /**
+   * Reset zebra tool to default settings
+   */
+  handleZebraReset = (_e: Event): void => {
+    this.viewer.resetZebra();
+  };
+
+  // ---------------------------------------------------------------------------
+  // Studio Tab Handlers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Handler for Studio environment dropdown change
+   */
+  handleStudioEnvironment = (e: Event): void => {
+    if (!(e.target instanceof HTMLSelectElement)) return;
+    this._showSpinner();
+    this.state.set("studioEnvironment", e.target.value);
+    this.container.addEventListener("tcv-studio-ready", () => this._hideSpinner(), { once: true });
+  };
+
+  /**
+   * Handler for Studio env intensity slider change.
+   * Slider range 0-200 with percentage=true, so value arrives as 0-2.
+   */
+  handleStudioEnvIntensity = (value: number): void => {
+    this.state.set("studioEnvIntensity", value);
+  };
+
+  handleStudioEnvRotation = (value: number): void => {
+    this.state.set("studioEnvRotation", value);
+  };
+
+  /**
+   * Handler for Studio background dropdown change.
+   * Validates against the StudioBackground union before setting state.
+   */
+  handleStudioBackground = (e: Event): void => {
+    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") {
+      this.state.set("studioBackground", value);
+    }
+  };
+
+  /**
+   * Handler for Studio tone mapping dropdown change.
+   * Validates against the StudioToneMapping union before setting state.
+   */
+  handleStudioToneMapping = (e: Event): void => {
+    if (!(e.target instanceof HTMLSelectElement)) return;
+    const value = e.target.value;
+    if (value === "neutral" || value === "ACES" || value === "none") {
+      this.state.set("studioToneMapping", value);
+    }
+  };
+
+  /**
+   * Handler for Studio exposure slider change.
+   * Slider range 0-200 with percentage=true, so value arrives as 0-2.
+   */
+  handleStudioTextureMapping = (e: Event): void => {
+    if (!(e.target instanceof HTMLSelectElement)) return;
+    const value = e.target.value;
+    if (value === "triplanar" || value === "parametric") {
+      this._showSpinner();
+      this.state.set("studioTextureMapping", value);
+      this.container.addEventListener("tcv-studio-ready", () => this._hideSpinner(), { once: true });
+    }
+  };
+
+  handleStudioExposure = (value: number): void => {
+    this.state.set("studioExposure", value);
+  };
+
+  handleStudioShadowIntensity = (value: number): void => {
+    this.state.set("studioShadowIntensity", value);
+  };
+
+  handleStudioShadowSoftness = (value: number): void => {
+    this.state.set("studioShadowSoftness", value);
+  };
+
+  /**
+   * Handler for Studio AO intensity slider change.
+   * Slider range 0-30, divided by 10 → state gets 0-3.0.
+   * A value of 0 disables AO.
+   */
+  handleStudioAOIntensity = (value: number): void => {
+    this.state.set("studioAOIntensity", value / 10);
+  };
+
+  /**
+   * Handler for Studio 4K env maps checkbox change.
+   * Shows a "Loading…" indicator while the new resolution downloads.
+   */
+  handleStudio4kEnvMaps = (e: Event): void => {
+    if (!(e.target instanceof HTMLInputElement)) return;
+    this._showSpinner();
+    this.state.set("studio4kEnvMaps", e.target.checked);
+    this.container.addEventListener("tcv-studio-ready", () => this._hideSpinner(), { once: true });
+  };
+
+  /**
+   * Reset Studio tab values to defaults.
+   * Delegates to viewer.resetStudio() (same pattern as handleMaterialReset -> resetMaterial()).
+   */
+  handleStudioReset = (_e: Event): void => {
+    this.viewer.resetStudio();
+  };
+
+  // ---------------------------------------------------------------------------
+  // Material Editor
+  // ---------------------------------------------------------------------------
+
+  handleMatEditorToggle = (_e: Event): void => {
+    const dialog = this.container.querySelector(".tcv_mat_editor") as HTMLElement;
+    if (!dialog) return;
+
+    // Toggle off if visible
+    if (dialog.style.display !== "none") {
+      this.closeMatEditor();
+      return;
+    }
+
+    const result = this.viewer.getSelectedObjectGroup();
+    if (!result || !result.object.front) {
+      this._showMatEditorHint(dialog);
+      return;
+    }
+
+    this.openMatEditor(result.object, result.path);
+  };
+
+  private _showMatEditorHint(dialog: HTMLElement): void {
+    const pathEl = dialog.querySelector(".tcv_mat_editor_path") as HTMLElement;
+    if (pathEl) pathEl.style.display = "none";
+    const resetBtn = dialog.querySelector(".tcv_mat_editor_reset") as HTMLElement;
+    if (resetBtn) resetBtn.style.display = "none";
+    const content = dialog.querySelector(".tcv_mat_editor_content") as HTMLElement;
+    if (content) {
+      content.innerHTML = "";
+      const hint = document.createElement("div");
+      hint.style.padding = "12px 6px";
+      hint.style.textAlign = "center";
+      hint.style.opacity = "0.7";
+      hint.textContent = "Select object by double-click first";
+      content.appendChild(hint);
+    }
+    dialog.style.display = "";
+  }
+
+  private openMatEditor(object: ObjectGroup, objectPath: string): void {
+    const dialog = this.container.querySelector(".tcv_mat_editor") as HTMLElement;
+    if (!dialog || !object.front) return;
+
+    this._matEditorPath = objectPath;
+
+    // Clone material on first edit so changes are per-object (reuse existing clone)
+    let mat: THREE.MeshPhysicalMaterial;
+    let originalMat: THREE.MeshPhysicalMaterial;
+    const existing = this._matEditorClones.get(objectPath);
+    if (existing && object.front.material === existing.clone) {
+      mat = existing.clone;
+      originalMat = existing.original;
+    } else {
+      const currentMat = object.front.material;
+      if (!(currentMat instanceof THREE.MeshPhysicalMaterial)) return;
+      originalMat = currentMat;
+      mat = currentMat.clone();
+      // Preserve triplanar mapping if the original material uses it
+      if (currentMat.customProgramCacheKey() === "triplanar" && object.shapeGeometry) {
+        applyTriplanarMapping(mat, object.shapeGeometry);
+      }
+      object.front.material = mat;
+      this._matEditorClones.set(objectPath, { original: originalMat, clone: mat });
+    }
+
+    // Restore elements that _showMatEditorHint may have hidden
+    const resetBtn = dialog.querySelector(".tcv_mat_editor_reset") as HTMLElement;
+    if (resetBtn) resetBtn.style.display = "";
+
+    // Update path display
+    const pathEl = dialog.querySelector(".tcv_mat_editor_path") as HTMLElement;
+    if (pathEl) {
+      pathEl.style.display = "";
+      const shortName = objectPath.split("/").pop() || objectPath;
+      pathEl.textContent = `${shortName} — ${object.materialTag || "(default)"}`;
+      pathEl.title = objectPath;
+    }
+
+    // Mark toggle active
+    const toggleBtn = this.container.querySelector(".tcv_mat_editor_toggle") as HTMLElement;
+    if (toggleBtn) toggleBtn.classList.add("tcv_active");
+
+    // Populate content — abort previous input listeners before rebuilding
+    this._matEditorInputAbort?.abort();
+    this._matEditorInputAbort = new AbortController();
+
+    const content = dialog.querySelector(".tcv_mat_editor_content") as HTMLElement;
+    if (!content) return;
+    content.innerHTML = "";
+    this._buildMatEditorContent(content, mat, originalMat);
+
+    dialog.style.display = "";
+  }
+
+  closeMatEditor(): void {
+    this._matEditorInputAbort?.abort();
+    this._matEditorInputAbort = null;
+
+    const dialog = this.container.querySelector(".tcv_mat_editor") as HTMLElement;
+    if (dialog) {
+      const content = dialog.querySelector(".tcv_mat_editor_content") as HTMLElement;
+      if (content) content.innerHTML = "";
+      dialog.style.display = "none";
+    }
+    const toggleBtn = this.container.querySelector(".tcv_mat_editor_toggle") as HTMLElement;
+    if (toggleBtn) toggleBtn.classList.remove("tcv_active");
+    this._matEditorPath = null;
+  }
+
+  /** Dispose all cloned materials, restoring originals first (call on Studio mode exit) */
+  disposeMatEditorClones(): void {
+    this._matEditorInputAbort?.abort();
+    this._matEditorInputAbort = null;
+
+    let groups: Record<string, THREE.Object3D> | null = null;
+    try { groups = this.viewer.rendered.nestedGroup.groups; } catch { /* not rendered */ }
+
+    for (const [path, { original, clone }] of this._matEditorClones.entries()) {
+      // Restore original material on mesh before disposing the clone
+      if (groups) {
+        const group = groups[path] as ObjectGroup | undefined;
+        if (group?.front?.material === clone) {
+          group.front.material = original;
+        }
+      }
+      clone.dispose();
+    }
+    this._matEditorClones.clear();
+  }
+
+  /** Save material editor property deltas so they survive a Studio mode leave/enter cycle. */
+  private _saveMatEditorChanges(): void {
+    this._savedMatEditorChanges.clear();
+    for (const [path, { original, clone }] of this._matEditorClones.entries()) {
+      const changes: Record<string, number> = {};
+      for (const param of MAT_EDITOR_PARAMS) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const origVal = (original as any)[param.key] as number;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const cloneVal = (clone as any)[param.key] as number;
+        if (origVal !== cloneVal) {
+          changes[param.key] = cloneVal;
+        }
+      }
+      if (Object.keys(changes).length > 0) {
+        this._savedMatEditorChanges.set(path, changes);
+      }
+    }
+  }
+
+  /** Reapply saved material editor changes after re-entering Studio mode. */
+  private _reapplyMatEditorChanges(): void {
+    if (this._savedMatEditorChanges.size === 0) return;
+    let groups: Record<string, THREE.Object3D>;
+    try { groups = this.viewer.rendered.nestedGroup.groups; } catch { return; }
+
+    for (const [path, changes] of this._savedMatEditorChanges.entries()) {
+      const group = groups[path] as ObjectGroup | undefined;
+      if (!group?.front?.material) continue;
+      const currentMat = group.front.material;
+      if (!(currentMat instanceof THREE.MeshPhysicalMaterial)) continue;
+
+      const clone = currentMat.clone();
+      if (currentMat.customProgramCacheKey() === "triplanar" && group.shapeGeometry) {
+        applyTriplanarMapping(clone, group.shapeGeometry);
+      }
+      for (const [key, value] of Object.entries(changes)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (clone as any)[key] = value;
+      }
+      group.front.material = clone;
+      this._matEditorClones.set(path, { original: currentMat as THREE.MeshPhysicalMaterial, clone });
+    }
+    this._savedMatEditorChanges.clear();
+  }
+
+  /**
+   * Called by viewer.ts when the selected object changes.
+   * Updates or closes the material editor if it's open.
+   */
+  onSelectionChanged(newObjectId: string | null): void {
+    if (!this._matEditorPath) return; // Editor not open
+    if (newObjectId === this._matEditorPath) return; // Same object
+    this.closeMatEditor();
+    // Immediately reopen for the new object if one was selected
+    if (newObjectId) {
+      const result = this.viewer.getSelectedObjectGroup();
+      if (result?.object.front) {
+        this.openMatEditor(result.object, result.path);
+      }
+    }
+  }
+
+  handleMatEditorReset = (_e: Event): void => {
+    if (!this._matEditorPath) return;
+    const result = this.viewer.getSelectedObjectGroup();
+    if (!result?.object.front) return;
+
+    const entry = this._matEditorClones.get(this._matEditorPath);
+    if (entry) {
+      // Restore original material and dispose the clone
+      result.object.front.material = entry.original;
+      entry.clone.dispose();
+      this._matEditorClones.delete(this._matEditorPath);
+    }
+
+    // Reopen to rebuild UI with fresh clone from original
+    this.closeMatEditor();
+    this.openMatEditor(result.object, result.path);
+    this.viewer.update(true, false);
+  };
+
+  /** Make the material editor dialog draggable by its titlebar */
+  private _initMatEditorDrag(): void {
+    const dialog = this.container.querySelector(".tcv_mat_editor") as HTMLElement;
+    const titlebar = this.container.querySelector(".tcv_mat_editor_titlebar") as HTMLElement;
+    if (!dialog || !titlebar) return;
+
+    this._matEditorDragAbort = new AbortController();
+    const { signal } = this._matEditorDragAbort;
+
+    let dragging = false;
+    let startX = 0;
+    let startY = 0;
+    let origLeft = 0;
+    let origTop = 0;
+
+    titlebar.addEventListener("mousedown", (e: MouseEvent) => {
+      // Don't drag if clicking buttons
+      if ((e.target as HTMLElement).tagName === "INPUT") return;
+      dragging = true;
+      startX = e.clientX;
+      startY = e.clientY;
+      const rect = dialog.getBoundingClientRect();
+      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
+      dialog.style.right = "auto";
+      dialog.style.left = origLeft + "px";
+      dialog.style.top = origTop + "px";
+      e.preventDefault();
+    }, { signal });
+
+    document.addEventListener("mousemove", (e: MouseEvent) => {
+      if (!dragging) return;
+      const dx = e.clientX - startX;
+      const dy = e.clientY - startY;
+      dialog.style.left = (origLeft + dx) + "px";
+      dialog.style.top = (origTop + dy) + "px";
+    }, { signal });
+
+    document.addEventListener("mouseup", () => {
+      dragging = false;
+    }, { signal });
+  }
+
+  private _buildMatEditorContent(
+    content: HTMLElement,
+    material: THREE.MeshPhysicalMaterial,
+    originalMat: THREE.MeshPhysicalMaterial,
+  ): void {
+    let currentGroup = "";
+    for (const param of MAT_EDITOR_PARAMS) {
+      if (param.group !== currentGroup) {
+        currentGroup = param.group;
+        const section = document.createElement("div");
+        section.className = "tcv_mat_editor_section";
+        section.textContent = currentGroup;
+        content.appendChild(section);
+      }
+
+      let currentValue = // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (material as any)[param.key] as number;
+      const isInfinity = param.infinity === true && (currentValue === Infinity || currentValue == null);
+      if (isInfinity) currentValue = param.max;
+
+      this._buildMatEditorRow(content, param, currentValue ?? 0, isInfinity, originalMat);
+    }
+  }
+
+  private _buildMatEditorRow(
+    container: HTMLElement,
+    param: MatEditorParam,
+    value: number,
+    isInfinity: boolean,
+    originalMat: THREE.MeshPhysicalMaterial,
+  ): void {
+    const row = document.createElement("div");
+    row.className = "tcv_mat_editor_row";
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const origValue = (originalMat as any)[param.key] as number;
+
+    const isChanged = (v: number) => param.infinity
+      ? (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";
+    if (isChanged(value)) label.classList.add("tcv_mat_editor_changed");
+    label.textContent = param.label;
+    label.title = `${param.key} (${param.min}–${param.max})`;
+
+    const sliderGroup = document.createElement("div");
+    sliderGroup.className = "tcv_mat_editor_slider_group";
+
+    const slider = document.createElement("input");
+    slider.type = "range";
+    slider.className = "tcv_clip_slider";
+    slider.min = String(param.min);
+    slider.max = String(param.max);
+    slider.step = String(param.step);
+    slider.value = String(value);
+
+    const valueDisplay = document.createElement("input");
+    valueDisplay.className = "tcv_clip_input";
+    valueDisplay.readOnly = true;
+    valueDisplay.value = isInfinity ? "\u221E" : _formatMatValue(value, param.step);
+
+    slider.addEventListener("input", () => {
+      const newValue = parseFloat(slider.value);
+      const result = this.viewer.getSelectedObjectGroup();
+      if (!result?.object.front) return;
+      const mat = result.object.front.material;
+
+      if (param.infinity && newValue >= param.max) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (mat as any)[param.key] = Infinity;
+        valueDisplay.value = "\u221E";
+      } else {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (mat as any)[param.key] = newValue;
+        valueDisplay.value = _formatMatValue(newValue, param.step);
+      }
+
+      label.classList.toggle("tcv_mat_editor_changed", isChanged(newValue));
+
+      this.viewer.update(true, false);
+    }, { signal: this._matEditorInputAbort!.signal });
+
+    sliderGroup.appendChild(slider);
+    sliderGroup.appendChild(valueDisplay);
+    row.appendChild(label);
+    row.appendChild(sliderGroup);
+    container.appendChild(row);
+  }
+
   // ---------------------------------------------------------------------------
   // Zebra Tool Handlers
   // ---------------------------------------------------------------------------
@@ -1886,6 +2767,82 @@ class Display {
     this.setZebraMappingModeSelect(state.get("zebraMappingMode"));
   }
 
+  /**
+   * Sync Studio slider/control UI from current state values.
+   */
+  syncStudioSlidersFromState(): void {
+    const state = this.viewer.state;
+    this.studioEnvIntensitySlider?.setValueFromState(state.get("studioEnvIntensity") * 100);
+    this.studioExposureSlider?.setValueFromState(state.get("studioExposure") * 100);
+    this.studioEnvRotationSlider?.setValueFromState(state.get("studioEnvRotation"));
+    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._syncEnvDropdown(state.get("studioEnvironment"));
+    const bgEl = this.container.querySelector(".tcv_studio_background");
+    if (bgEl instanceof HTMLSelectElement) bgEl.value = state.get("studioBackground");
+    const tmEl = this.container.querySelector(".tcv_studio_tone_mapping");
+    if (tmEl instanceof HTMLSelectElement) tmEl.value = state.get("studioToneMapping");
+    const txmEl = this.container.querySelector(".tcv_studio_texture_mapping");
+    if (txmEl instanceof HTMLSelectElement) txmEl.value = state.get("studioTextureMapping");
+    this._update4kCheckboxEnabled(state.get("studioEnvironment"));
+  }
+
+  /**
+   * Ensure the environment dropdown can display a custom HDR URL.
+   * If envName isn't already an option, adds a "Custom HDR" entry.
+   * Removes stale custom entries when switching back to a built-in preset.
+   */
+  private _syncEnvDropdown(envName: string): void {
+    const el = this.container.querySelector(".tcv_studio_environment");
+    if (!(el instanceof HTMLSelectElement)) return;
+
+    // Check if the value matches a built-in option
+    const isBuiltin = Array.from(el.options).some(
+      (opt) => !opt.hasAttribute("data-custom") && opt.value === envName,
+    );
+
+    if (isBuiltin) {
+      el.value = envName;
+    } else {
+      // Add or update a "Custom" optgroup with the custom HDR entry
+      const label = envName.split("/").pop()?.replace(/\.hdr$/i, "") || "Custom HDR";
+      let customGroup = el.querySelector("optgroup[data-custom]") as HTMLOptGroupElement | null;
+      if (customGroup) {
+        const opt = customGroup.querySelector("option")!;
+        opt.value = envName;
+        opt.textContent = label;
+      } else {
+        customGroup = document.createElement("optgroup");
+        customGroup.label = "Custom";
+        customGroup.setAttribute("data-custom", "true");
+        const opt = document.createElement("option");
+        opt.value = envName;
+        opt.textContent = label;
+        customGroup.appendChild(opt);
+        el.appendChild(customGroup);
+      }
+      el.value = envName;
+    }
+  }
+
+  /**
+   * Enable/disable the 4K checkbox based on whether the current environment
+   * is a Poly Haven preset (resolution-switchable) or a custom URL / "studio".
+   */
+  private _update4kCheckboxEnabled(envName: string): void {
+    const cb = this.container.querySelector(".tcv_studio_4k_env_maps") as HTMLInputElement | null;
+    if (!cb) return;
+    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";
+    } else {
+      cb.title = "";
+    }
+  }
+
   /**
    * Refresh clipping plane position
    */
@@ -1945,6 +2902,16 @@ class Display {
   private _handleKeyboardShortcut = (e: Event): void => {
     if (!(e instanceof KeyboardEvent)) return;
 
+    // ESC closes the material editor (works regardless of focus target)
+    if (e.key === "Escape") {
+      const matDialog = this.container.querySelector(".tcv_mat_editor") as HTMLElement;
+      if (matDialog && matDialog.style.display !== "none") {
+        e.preventDefault();
+        this.closeMatEditor();
+        return;
+      }
+    }
+
     // Skip if modifier keys are held (avoid conflicts with modifier-based mouse actions)
     if (e.ctrlKey || e.altKey || e.metaKey) return;
 
@@ -2046,8 +3013,9 @@ class Display {
       }
       case "tree":
       case "clip":
-      case "material":
       case "zebra":
+      case "material":
+      case "studio":
         this.viewer.setActiveTab(action);
         return;
     }
@@ -2091,8 +3059,9 @@ class Display {
     const tabMap: Record<string, { el: HTMLElement | undefined; label: string }> = {
       tree: { el: this.tabTree, label: "Navigation Tree" },
       clip: { el: this.tabClip, label: "Clipping Tool" },
-      material: { el: this.tabMaterial, label: "Material Selection" },
       zebra: { el: this.tabZebra, label: "Zebra Tool" },
+      material: { el: this.tabMaterial, label: "Material Selection" },
+      studio: { el: this.tabStudio, label: "Studio Mode" },
     };
     for (const [action, key] of Object.entries(shortcuts)) {
       const entry = tabMap[action];
@@ -2164,6 +3133,38 @@ class Display {
     this.showInfo(!this.info_shown);
   };
 
+  /**
+   * Show or hide tools panel (tabs + content) in glass mode.
+   * Also toggles the orientation marker and animation/explode slider.
+   */
+  showToolsPanel = (flag: boolean): void => {
+    const cadTree = this.getElement("tcv_cad_tree");
+    cadTree.style.display = flag ? "" : "none";
+    this.getElement("tcv_toggle_tools").innerHTML = flag ? "\u25BE" : "\u25B8";
+    this.tools_shown = flag;
+
+    // Toggle orientation marker
+    if (this.viewer.ready) {
+      this.viewer.rendered.orientationMarker.setVisible(flag);
+      this.viewer.update(true, false);
+    }
+
+    // Toggle animation/explode slider (only if it was visible before hiding)
+    if (!flag) {
+      this._animWasVisible = this.cadAnim.style.display !== "none";
+      this.cadAnim.style.display = "none";
+    } else if (this._animWasVisible) {
+      this.cadAnim.style.display = "block";
+    }
+  };
+
+  /**
+   * Toggle tools panel visibility
+   */
+  toggleToolsPanel = (): void => {
+    this.showToolsPanel(!this.tools_shown);
+  };
+
   // ---------------------------------------------------------------------------
   // Theme & Glass Mode
   // ---------------------------------------------------------------------------
@@ -2197,8 +3198,10 @@ class Display {
       this.getElement("tcv_cad_view").classList.add("tcv_cad_view_glass");
 
       this.getElement("tcv_toggle_info_wrapper").style.display = "block";
+      this.getElement("tcv_toggle_tools_wrapper").style.display = "block";
 
       this.showInfo(false);
+      this.showToolsPanel(true);
       this.glass = true;
       this.autoCollapse();
     } else {
@@ -2209,8 +3212,10 @@ class Display {
       this.getElement("tcv_cad_view").classList.remove("tcv_cad_view_glass");
 
       this.getElement("tcv_toggle_info_wrapper").style.display = "none";
+      this.getElement("tcv_toggle_tools_wrapper").style.display = "none";
 
       this.showInfo(true);
+      this.showToolsPanel(true);
       this.glass = false;
     }
     const options: SizeOptions = {