three-cad-viewer 4.1.2 → 4.2.0

package/Readme.md

@@ -257,7 +257,7 @@ After the initial `viewer.render()`, parts can be added, removed, or updated wit
 `addPart(parentPath, partData)` creates new Three.js objects (meshes, edges, clipping stencils) from the part data and inserts them into the scene graph and navigation tree. `removePart(path)` disposes the Three.js objects and removes the part from the scene.
 
 ```js
-viewer.addPart("/Group", partData);    // creates "/Group/PartName"
+viewer.addPart("/Group", partData); // creates "/Group/PartName"
 viewer.removePart("/Group/PartName");
 ```
 
@@ -296,9 +296,12 @@ Add, remove, and update calls can be freely mixed within a single batch.
 viewer.render(shapes, renderOptions, viewerOptions);
 
 viewer.ensureStencilSize({
-  xmin: -200, xmax: 200,
-  ymin: -200, ymax: 200,
-  zmin: 0,    zmax: 300,
+  xmin: -200,
+  xmax: 200,
+  ymin: -200,
+  ymax: 200,
+  zmin: 0,
+  zmax: 300,
 });
 
 // All updates within these bounds are now stencil-rebuild-free
@@ -340,7 +343,7 @@ Pass a partial keymap to override individual bindings — unspecified keys keep
 
 ```javascript
 const displayOptions = {
-  keymap: { axes: "q", reset: "!" },  // only these two change
+  keymap: { axes: "q", reset: "!" }, // only these two change
 };
 ```
 
@@ -427,3 +430,7 @@ For the deployment, see [Release.md](./Release.md)
 # Changes
 
 see [Changes.md](./Changes.md)
+
+## Credit
+
+- The toycar example is downloaded from https://grabcad.com/library/toy-rider-car-1 and tessellated

package/dist/camera/camera.d.ts

@@ -22,6 +22,13 @@ type UpMode = "y_up" | "z_up" | "legacy";
  */
 declare class Camera {
     private static readonly DISTANCE_FACTOR;
+    /**
+     * Near plane factor: near = max(0.1, NEAR_FACTOR * distance).
+     * With far = 100 * distance, this gives a far/near ratio of 10,000:1,
+     * which is comfortable for 24-bit depth buffers and avoids z-fighting
+     * on large models (e.g. toycar at ~1100 unit bounding radius).
+     */
+    private static readonly NEAR_FACTOR;
     target: THREE.Vector3;
     ortho: boolean;
     up: UpMode;
@@ -31,6 +38,11 @@ declare class Camera {
     pCamera: THREE.PerspectiveCamera;
     oCamera: THREE.OrthographicCamera;
     camera: THREE.PerspectiveCamera | THREE.OrthographicCamera;
+    /**
+     * Compute the near clipping plane from the bounding radius.
+     * Keeps the far/near ratio bounded for depth buffer precision.
+     */
+    private static _computeNear;
     /**
      * Create a combined camera (orthographic and perspective).
      * @param width - canvas width.
@@ -42,8 +54,8 @@ declare class Camera {
      */
     constructor(width: number, height: number, distance: number, target: Vector3Tuple, ortho: boolean, up: UpDirection);
     /**
-     * Update the far clipping plane for both cameras.
-     * @param distance - The new bounding radius to base the far plane on.
+     * Update the near/far clipping planes for both cameras.
+     * @param distance - The new bounding radius to base the clipping planes on.
      */
     updateFarPlane(distance: number): void;
     /**

package/dist/core/studio-manager.d.ts

@@ -0,0 +1,91 @@
+/**
+ * StudioManager — orchestrates Studio mode rendering.
+ *
+ * Extracted from viewer.ts to reduce its complexity. Owns the Studio-specific
+ * resources (composer, floor, shadow lights, environment manager) and handles
+ * all Studio subscriptions and mode enter/leave logic.
+ *
+ * Communicates with the Viewer via the StudioManagerContext interface to avoid
+ * a circular dependency.
+ */
+import * as THREE from "three";
+import { EnvironmentManager } from "../rendering/environment.js";
+import { StudioFloor } from "../rendering/studio-floor.js";
+import { ViewerState } from "./viewer-state.js";
+import type { NestedGroup, ObjectGroup } from "../scene/nestedgroup.js";
+import type { Camera } from "../camera/camera.js";
+import type { Clipping } from "../scene/clipping.js";
+import type { BoundingBox } from "../scene/bbox.js";
+/**
+ * Abstraction over Viewer that StudioManager uses. Keeps the dependency
+ * one-directional (StudioManager → context, never StudioManager → Viewer).
+ */
+export interface StudioManagerContext {
+    renderer: THREE.WebGLRenderer;
+    state: ViewerState;
+    /** Whether viewer has rendered content. */
+    isRendered(): boolean;
+    getScene(): THREE.Scene;
+    getCamera(): Camera;
+    getAmbientLight(): THREE.AmbientLight;
+    getDirectLight(): THREE.DirectionalLight;
+    getNestedGroup(): NestedGroup;
+    getClipping(): Clipping;
+    getBbox(): BoundingBox | null;
+    getLastBboxId(): string | null;
+    setAxes(flag: boolean, notify?: boolean): void;
+    setGrids(grids: [boolean, boolean, boolean], notify?: boolean): void;
+    setOrtho(flag: boolean, notify?: boolean): void;
+    update(updateMarker: boolean, notify?: boolean): void;
+    dispatchEvent(event: Event): void;
+    onSelectionChanged(id: string | null): void;
+}
+declare class StudioManager {
+    readonly envManager: EnvironmentManager;
+    readonly floor: StudioFloor;
+    private _composer;
+    private _active;
+    private _savedClippingState;
+    private _savedViewState;
+    private _shadowLights;
+    private _ctx;
+    constructor(ctx: StudioManagerContext);
+    get isActive(): boolean;
+    get hasComposer(): boolean;
+    /** Render via composer (call from Viewer.update / _animate). */
+    render(): void;
+    /** Update composer camera (call from Viewer.switchCamera). */
+    setCamera(camera: THREE.Camera): void;
+    /** Resize composer (call from Viewer.resize). */
+    setSize(width: number, height: number): void;
+    /** Whether env background needs per-frame update. */
+    get isEnvBackgroundActive(): boolean;
+    /** Update env background (ortho workaround, call per frame). */
+    updateEnvBackground(renderer: THREE.WebGLRenderer, camera: THREE.Camera): void;
+    /** Check if an environment name is a Poly Haven preset. */
+    isEnvPreset(name: string): boolean;
+    /**
+     * Get the ObjectGroup and path for the currently selected object.
+     * Returns null if nothing selected or Studio mode inactive.
+     */
+    getSelectedObjectGroup(): {
+        object: ObjectGroup;
+        path: string;
+    } | null;
+    enterStudioMode: () => Promise<void>;
+    leaveStudioMode: () => void;
+    resetStudio: () => void;
+    /**
+     * Dispose all Studio resources. Called from Viewer.dispose().
+     * Must be called BEFORE renderer.dispose().
+     */
+    dispose(): void;
+    private _setupSubscriptions;
+    private _configureFloor;
+    private _configureShadowLights;
+    private _removeShadowLights;
+    private _setShadowsEnabled;
+    private _applyToneMapping;
+    private _rebuildMaterials;
+}
+export { StudioManager };

package/dist/core/types.d.ts

@@ -15,11 +15,24 @@ export type UpDirection = "Z" | "Y" | "legacy";
 /** Animation mode */
 export type AnimationMode = "none" | "animation" | "explode";
 /** Active sidebar tab */
-export type ActiveTab = "tree" | "clip" | "material" | "zebra";
+export type ActiveTab = "tree" | "clip" | "material" | "zebra" | "studio";
 /** Zebra color scheme */
 export type ZebraColorScheme = "blackwhite" | "colorful" | "grayscale";
 /** Zebra mapping mode */
 export type ZebraMappingMode = "reflection" | "normal";
+/**
+ * Studio environment preset name.
+ * - "studio": Built-in procedural RoomEnvironment (zero network)
+ * - "none": No environment map
+ * - Any other string: Poly Haven HDR preset slug or custom HDR URL
+ */
+export type StudioEnvironment = string;
+/** Studio tone mapping algorithm */
+export type StudioToneMapping = "neutral" | "ACES" | "none";
+/** Studio background mode */
+export type StudioBackground = "grey" | "darkgrey" | "white" | "gradient" | "gradient-dark" | "environment" | "transparent";
+/** Studio texture mapping mode */
+export type StudioTextureMapping = "triplanar" | "parametric";
 /** Shape type */
 export type ShapeType = "shapes" | "edges" | "vertices";
 /** Shape subtype */
@@ -43,6 +56,8 @@ export declare enum CollapseState {
 export type ColorValue = number | string;
 /** RGB color as tuple [r, g, b] with values 0-1 */
 export type RGBColor = [number, number, number];
+/** RGBA color as tuple [r, g, b, a] with values 0-1 */
+export type RGBAColor = [number, number, number, number];
 /** Axis colors per theme - array of RGB colors for X, Y, Z axes */
 export type AxisColors = Record<Theme, RGBColor[]>;
 /** Flat axis colors per theme - all RGB values concatenated for line geometry */
@@ -126,7 +141,7 @@ export interface ChangeNotification {
 /** Callback for notifications */
 export type NotificationCallback = (change: ChangeNotification) => void;
 /** Action shortcut names for toolbar buttons and tabs */
-export type ActionShortcutName = "axes" | "axes0" | "grid" | "gridxy" | "perspective" | "transparent" | "blackedges" | "zscale" | "reset" | "resize" | "iso" | "front" | "rear" | "top" | "bottom" | "left" | "right" | "explode" | "distance" | "properties" | "select" | "help" | "play" | "stop" | "tree" | "clip" | "material" | "zebra";
+export type ActionShortcutName = "axes" | "axes0" | "grid" | "gridxy" | "perspective" | "transparent" | "blackedges" | "zscale" | "reset" | "resize" | "iso" | "front" | "rear" | "top" | "bottom" | "left" | "right" | "explode" | "distance" | "properties" | "select" | "help" | "play" | "stop" | "tree" | "clip" | "material" | "zebra" | "studio";
 /** Action keymap: action name → key character */
 export type ActionKeymap = Partial<Record<ActionShortcutName, string>>;
 /** Combined keymap: modifier keys + action shortcuts */
@@ -168,28 +183,34 @@ export interface DisplayOptions {
     zscaleTool?: boolean;
     /** Show zebra tool (default: true) */
     zebraTool?: boolean;
+    /** Show studio tool (default: true) */
+    studioTool?: boolean;
     /** Enable measurement debug mode (default: false) */
     measurementDebug?: boolean;
+    /** External canvas element to use for the WebGL renderer, enabling shared WebGL context scenarios (default: undefined — renderer creates its own canvas) */
+    canvas?: HTMLCanvasElement;
+    /** External WebGL context to use for the renderer. When provided together with `canvas`, the renderer will use this context instead of creating a new one. Useful for sharing a context with other renderers like PixiJS. (default: undefined) */
+    gl?: WebGLRenderingContext | WebGL2RenderingContext;
 }
 /** Render options */
 export interface RenderOptions {
     /** Default edge color (default: 0x707070) */
     edgeColor?: number;
-    /** Ambient light intensity (default: 0.5) */
+    /** Ambient light intensity (default: 1) */
     ambientIntensity?: number;
-    /** Direct light intensity (default: 0.6) */
+    /** Direct light intensity (default: 1.1) */
     directIntensity?: number;
-    /** Metalness (default: 0.7) */
+    /** Metalness (default: 0.3) */
     metalness?: number;
-    /** Roughness (default: 0.7) */
+    /** Roughness (default: 0.65) */
     roughness?: number;
     /** Default opacity level for transparency (default: 0.5) */
     defaultOpacity?: number;
     /** Show triangle normals when normalLen > 0 (default: 0) */
     normalLen?: number;
 }
-/** Viewer options */
-export interface ViewerOptions {
+/** Viewer options (includes studio mode configuration) */
+export interface ViewerOptions extends StudioModeOptions {
     /** Use OrbitControls or TrackballControls (default: "orbit") */
     control?: ControlType;
     /** Show X-, Y-, Z-axes (default: false) */
@@ -264,8 +285,33 @@ export interface ZebraOptions {
     /** Zebra mapping mode (default: "reflection") */
     zebraMappingMode?: ZebraMappingMode;
 }
+/** Studio mode options (environment, tone mapping, edges) */
+export interface StudioModeOptions {
+    /** Environment preset or custom HDR URL (default: "studio") */
+    studioEnvironment?: string;
+    /** Environment map intensity, 0-1 (default: 0.5) */
+    studioEnvIntensity?: number;
+    /** Background mode (default: "environment") */
+    studioBackground?: StudioBackground;
+    /** Tone mapping algorithm (default: "neutral") */
+    studioToneMapping?: StudioToneMapping;
+    /** Tone mapping exposure, 0-2 (default: 1.0) */
+    studioExposure?: number;
+    /** Use 4K environment maps instead of 2K (default: false) */
+    studio4kEnvMaps?: boolean;
+    /** Texture mapping mode: triplanar projection or parametric UVs (default: "triplanar") */
+    studioTextureMapping?: StudioTextureMapping;
+    /** Environment map rotation in degrees, 0-360 (default: 0) */
+    studioEnvRotation?: number;
+    /** Shadow intensity, 0-1 (default: 0 = off) */
+    studioShadowIntensity?: number;
+    /** Shadow softness, 0-1 (default: 0.3) */
+    studioShadowSoftness?: number;
+    /** Ambient occlusion intensity, 0-3.0 (default: 0 = off) */
+    studioAOIntensity?: number;
+}
 /** Combined options for initialization */
-export type CombinedOptions = DisplayOptions & RenderOptions & ViewerOptions & ZebraOptions;
+export type CombinedOptions = DisplayOptions & RenderOptions & ViewerOptions & ZebraOptions & StudioModeOptions;
 /** Complete state shape with all properties */
 export interface ViewerStateShape {
     theme: Theme;
@@ -283,6 +329,7 @@ export interface ViewerStateShape {
     explodeTool: boolean;
     zscaleTool: boolean;
     zebraTool: boolean;
+    studioTool: boolean;
     measurementDebug: boolean;
     ambientIntensity: number;
     directIntensity: number;
@@ -326,6 +373,17 @@ export interface ViewerStateShape {
     zebraDirection: number;
     zebraColorScheme: ZebraColorScheme;
     zebraMappingMode: ZebraMappingMode;
+    studioEnvironment: string;
+    studioEnvIntensity: number;
+    studioBackground: StudioBackground;
+    studioToneMapping: StudioToneMapping;
+    studioExposure: number;
+    studio4kEnvMaps: boolean;
+    studioTextureMapping: StudioTextureMapping;
+    studioEnvRotation: number;
+    studioShadowIntensity: number;
+    studioShadowSoftness: number;
+    studioAOIntensity: number;
     activeTool: string | null;
     animationMode: AnimationMode;
     animationSliderValue: number;
@@ -335,6 +393,176 @@ export interface ViewerStateShape {
 }
 /** Keys of ViewerStateShape */
 export type StateKey = keyof ViewerStateShape;
+/**
+ * Material appearance definition for Studio mode.
+ *
+ * All fields are optional. Only provided fields override defaults.
+ * In Studio mode the viewer uses MeshPhysicalMaterial; properties left
+ * unset default to their "off" values (transmission=0, clearcoat=0, etc.)
+ * which the shader skips at near-zero cost.
+ *
+ * This is a data-format interface (describes JSON input), not a Three.js material.
+ * Texture string fields reference either a key in the root-level `textures` table,
+ * a data URI, or a URL resolved against the HTML page.
+ */
+export interface MaterialAppearance {
+    /** Display name */
+    name?: string;
+    /** Reference to a built-in preset (e.g., "stainless-steel", "car-paint") */
+    builtin?: string;
+    /** sRGB base color. Accepts RGBA tuple [r,g,b,a] (0-1) or CSS hex string "#rrggbb". */
+    color?: RGBAColor | string;
+    /** Texture reference for base color */
+    map?: string;
+    /** Metalness factor, 0-1 (default: 0.0) */
+    metalness?: number;
+    /** Roughness factor, 0-1 (default: 0.5) */
+    roughness?: number;
+    /** Normal map texture reference */
+    normalMap?: string;
+    /** Ambient occlusion texture reference */
+    aoMap?: string;
+    /** Metalness map texture reference */
+    metalnessMap?: string;
+    /** Roughness map texture reference */
+    roughnessMap?: string;
+    /** Emissive color, linear RGB */
+    emissive?: RGBColor;
+    /** Emissive map texture reference */
+    emissiveMap?: string;
+    /** Emissive intensity multiplier (default: 1.0) */
+    emissiveIntensity?: number;
+    /** Alpha blending mode */
+    alphaMode?: "OPAQUE" | "MASK" | "BLEND";
+    /** Alpha cutoff threshold for MASK mode (default: 0.5) */
+    alphaCutoff?: number;
+    /** Transmission factor, 0-1 */
+    transmission?: number;
+    /** Transmission map texture reference */
+    transmissionMap?: string;
+    /** Clearcoat intensity, 0-1 */
+    clearcoat?: number;
+    /** Clearcoat roughness */
+    clearcoatRoughness?: number;
+    /** Clearcoat intensity texture reference */
+    clearcoatMap?: string;
+    /** Clearcoat roughness texture reference */
+    clearcoatRoughnessMap?: string;
+    /** Clearcoat normal map texture reference */
+    clearcoatNormalMap?: string;
+    /** Thickness for volume effects */
+    thickness?: number;
+    /** Thickness map texture reference */
+    thicknessMap?: string;
+    /** Attenuation distance for volume absorption */
+    attenuationDistance?: number;
+    /** Attenuation color, linear RGB */
+    attenuationColor?: RGBColor;
+    /** Index of refraction (default: 1.5) */
+    ior?: number;
+    /** Specular intensity, 0-1 */
+    specularIntensity?: number;
+    /** Specular tint color, linear RGB */
+    specularColor?: RGBColor;
+    /** Specular intensity texture reference */
+    specularIntensityMap?: string;
+    /** Specular color texture reference */
+    specularColorMap?: string;
+    /** Sheen intensity, 0-1 (required to enable sheen layer) */
+    sheen?: number;
+    /** Sheen tint color, linear RGB */
+    sheenColor?: RGBColor;
+    /** Sheen roughness */
+    sheenRoughness?: number;
+    /** Sheen color texture reference */
+    sheenColorMap?: string;
+    /** Sheen roughness texture reference */
+    sheenRoughnessMap?: string;
+    /** Anisotropy strength, 0-1 */
+    anisotropy?: number;
+    /** Anisotropy rotation in radians */
+    anisotropyRotation?: number;
+    /** Anisotropy direction texture reference */
+    anisotropyMap?: string;
+    /** Use MeshBasicMaterial (unlit, no shading) */
+    unlit?: boolean;
+    /** Render both sides of faces (THREE.DoubleSide) */
+    doubleSided?: boolean;
+}
+/**
+ * Material definition from threejs-materials (Three.js MeshPhysicalMaterial-compatible).
+ *
+ * This format is produced by the threejs-materials Python library, which catalogs
+ * PBR materials from ambientCG, GPUOpen, PolyHaven, and PhysicallyBased.
+ * The `properties` dict uses simplified property names (e.g., "color", "roughness",
+ * "normal") where each entry has an optional `value` (scalar or color array in
+ * linear RGB) and/or `texture` (inline data URI).
+ *
+ * Detected by the presence of the `properties` key.
+ * Extra keys from threejs-materials (id, name, source, url, license) pass through
+ * harmlessly and are not part of this interface.
+ */
+export interface MaterialXMaterial {
+    /** Material properties from threejs-materials. Each key maps to { value?, texture? } */
+    properties: Record<string, {
+        value?: unknown;
+        texture?: string;
+    }>;
+    /** Optional texture tiling [u, v], default [1, 1]. Applied to all textures. */
+    textureRepeat?: [number, number];
+}
+/**
+ * Type guard to check if a material entry is a threejs-materials format dict.
+ * Detected by the presence of the `properties` key.
+ */
+export declare function isMaterialXMaterial(m: unknown): m is MaterialXMaterial;
+/**
+ * Entry in the root-level `textures` table.
+ *
+ * Each entry is either embedded (base64-encoded image data) or a URL reference
+ * loaded on demand. At least one of `data`+`format` or `url` must be provided.
+ * An empty TextureEntry is invalid and will be ignored at runtime.
+ * Multiple builtin preset texture fields can reference the same key for
+ * deduplication. threejs-materials carry their own textures as inline data URIs.
+ */
+export interface TextureEntry {
+    /** Base64-encoded image data (for embedded textures) */
+    data?: string;
+    /** Image format, e.g., "png", "jpg", "webp" (required when data is provided) */
+    format?: string;
+    /** URL to load the texture from (for URL-referenced textures) */
+    url?: string;
+}
+/**
+ * Root-level Studio mode configuration.
+ *
+ * Optional configuration for the rendering environment, only used when
+ * the Studio tab is active. Fields map directly to ViewerState keys on load.
+ */
+export interface StudioOptions {
+    /** Environment preset slug, custom HDR URL, or "none" (default: "studio") */
+    environment?: StudioEnvironment;
+    /** Environment map intensity, 0-1 (default: 0.5) */
+    envIntensity?: number;
+    /** Background mode (default: "environment") */
+    background?: StudioBackground;
+    /** Tone mapping algorithm (default: "neutral") */
+    toneMapping?: StudioToneMapping;
+    /** Tone mapping exposure (default: 1.0) */
+    toneMappingExposure?: number;
+    /** Use 4K environment maps instead of 2K (default: false) */
+    use4kEnvMaps?: boolean;
+    /** Texture mapping mode (default: "triplanar") */
+    textureMapping?: StudioTextureMapping;
+    /** Environment map rotation in degrees (default: 0) */
+    envRotation?: number;
+    /** Shadow intensity, 0-1 (default: 0 = off) */
+    shadowIntensity?: number;
+    /** Shadow softness, 0-1 (default: 0.3) */
+    shadowSoftness?: number;
+    /** Ambient occlusion intensity, 0-3.0 (default: 0 = off) */
+    aoIntensity?: number;
+}
 /** Encoded texture */
 export interface Texture {
     height: number;
@@ -370,6 +598,8 @@ export interface Shape {
     triangles_per_face?: number[] | Uint32Array;
     /** Number of segments per edge (when edges is flat) */
     segments_per_edge?: number[] | Uint32Array;
+    /** UV coordinates (2 floats per vertex, same indexing as vertices) */
+    uvs?: number[] | Float32Array;
 }
 /**
  * Shape with flat binary format (TypedArrays with per-face/per-edge counts).
@@ -397,6 +627,15 @@ export interface ShapeNested {
     edge_types: number[];
     face_types: number[];
 }
+/**
+ * Shape reference for the instanced/compressed format.
+ * Before decoding, a part's shape field may be `{ ref: N }` referencing
+ * the Nth entry in the instances array. After decoding, all ShapeRefs
+ * are replaced with full Shape objects.
+ */
+export interface ShapeRef {
+    ref: number;
+}
 /**
  * Check if shape uses binary format (has triangles_per_face).
  */
@@ -471,6 +710,18 @@ export interface Shapes {
     width?: number | undefined;
     /** Vertex size in pixels (added during decomposition for vertex shapes) */
     size?: number | undefined;
+    /** Material tag referencing materials table or built-in preset (leaf nodes) */
+    material?: string | undefined;
+    /** User-defined material library (root node).
+     *  Values can be:
+     *  - string: builtin preset reference (e.g., "builtin:car-paint")
+     *  - MaterialXMaterial: threejs-materials format (detected by `properties` key)
+     *  - MaterialAppearance: preset with overrides (e.g., { builtin: "acrylic-clear", color: "#55a0e3" })
+     */
+    materials?: Record<string, string | MaterialXMaterial | MaterialAppearance> | undefined;
+    /** Shared texture table for builtin preset materials (root node).
+     *  threejs-materials carry their own textures inline. */
+    textures?: Record<string, TextureEntry> | undefined;
 }
 /** Callback for DOM events */
 export type DomEventCallback = (event: Event) => void;

package/dist/core/viewer-state.d.ts

@@ -1,5 +1,5 @@
 import * as THREE from "three";
-import { CollapseState, type Theme, type ThemeInput, type ControlType, type UpDirection, type AnimationMode, type ActiveTab, type ZebraColorScheme, type ZebraMappingMode, type Keymap, type StateChange, type StateSubscriber, type GlobalStateSubscriber, type SubscribeOptions, type RenderOptions, type ViewerOptions } from "./types";
+import { CollapseState, type Theme, type ThemeInput, type ControlType, type UpDirection, type AnimationMode, type ActiveTab, type ZebraColorScheme, type ZebraMappingMode, type StudioBackground, type StudioToneMapping, type StudioTextureMapping, type Keymap, type StateChange, type StateSubscriber, type GlobalStateSubscriber, type SubscribeOptions, type RenderOptions, type ViewerOptions, type StudioOptions } from "./types";
 /**
  * Display configuration defaults
  */
@@ -19,6 +19,7 @@ interface DisplayDefaults {
     explodeTool: boolean;
     zscaleTool: boolean;
     zebraTool: boolean;
+    studioTool: boolean;
     measurementDebug: boolean;
 }
 /**
@@ -78,6 +79,22 @@ interface ZebraDefaults {
     zebraColorScheme: ZebraColorScheme;
     zebraMappingMode: ZebraMappingMode;
 }
+/**
+ * Studio mode defaults
+ */
+interface StudioModeDefaults {
+    studioEnvironment: string;
+    studioEnvIntensity: number;
+    studioBackground: StudioBackground;
+    studioToneMapping: StudioToneMapping;
+    studioExposure: number;
+    studio4kEnvMaps: boolean;
+    studioTextureMapping: StudioTextureMapping;
+    studioEnvRotation: number;
+    studioShadowIntensity: number;
+    studioShadowSoftness: number;
+    studioAOIntensity: number;
+}
 /**
  * Runtime state defaults
  */
@@ -92,7 +109,7 @@ interface RuntimeDefaults {
 /**
  * Complete state shape
  */
-type StateShape = DisplayDefaults & RenderDefaults & ViewerDefaults & ZebraDefaults & RuntimeDefaults;
+type StateShape = DisplayDefaults & RenderDefaults & ViewerDefaults & ZebraDefaults & StudioModeDefaults & RuntimeDefaults;
 /**
  * Keys of the state shape
  */
@@ -160,6 +177,10 @@ declare class ViewerState {
      * Zebra tool settings
      */
     static ZEBRA_DEFAULTS: ZebraDefaults;
+    /**
+     * Studio mode settings
+     */
+    static STUDIO_MODE_DEFAULTS: StudioModeDefaults;
     /**
      * Runtime state (not from options, changes during execution)
      */
@@ -198,6 +219,11 @@ declare class ViewerState {
      * Converts Vector3Tuple/QuaternionTuple to THREE objects.
      */
     updateViewerState(options: ViewerOptions, notify?: boolean): void;
+    /**
+     * Update studio state from StudioOptions (shapes.studioOptions).
+     * Maps short field names to prefixed state keys.
+     */
+    updateStudioState(options: StudioOptions): void;
     /**
      * Get all state as a plain object (for serialization)
      */