softbox 4.18.0 → 4.20.0

package/dist/index.d.cts

@@ -132,6 +132,12 @@ export declare enum ControlType {
     OrbitControls = "OrbitControls"
 }
 
+/** The scene every viewer stands in when none is set. */
+export declare const DEFAULT_SCENE: ViewerScene;
+
+/** The grade the studio environment is built with when none is set. */
+export declare const DEFAULT_STUDIO_LOOK: StudioLook;
+
 /**
  * Default options using the new format structure
  */
@@ -203,6 +209,8 @@ export declare interface EnvironmentOptions {
      * Runtime-tunable via `updateOptions` — presets drive this live.
      */
     environmentIntensity?: number;
+    /** Grade of the built-in studio environment; ignored when `url` is set. */
+    studioLook?: StudioLook;
 }
 
 export declare enum ErrorCode {
@@ -225,6 +233,7 @@ export declare enum ErrorCode {
     INVALID_STATE = "INVALID_STATE",
     INVALID_PARAMETER = "INVALID_PARAMETER",
     OPERATION_FAILED = "OPERATION_FAILED",
+    POST_PROCESSING_FAILED = "POST_PROCESSING_FAILED",
     UNKNOWN = "UNKNOWN"
 }
 
@@ -418,6 +427,13 @@ export declare interface PathTracingOptions {
 export declare interface RendererOptions {
     antialias?: boolean;
     alpha?: boolean;
+    premultipliedAlpha?: boolean;
+    /**
+     * Note: the viewer forces this ON regardless — a completed path-traced
+     * frame must survive on the canvas for captureStill to read back.
+     */
+    preserveDrawingBuffer?: boolean;
+    powerPreference?: 'high-performance' | 'low-power' | 'default';
     shadowMapEnabled?: boolean;
     pixelRatio?: number;
     /** A `THREE.ShadowMapType` constant (e.g. `THREE.PCFShadowMap` === 1). */
@@ -474,6 +490,9 @@ export declare interface RenderingOptions {
 /** The partial options for a preset, or an empty object when none is set. */
 export declare function resolvePreset(preset?: ViewerPreset): Partial<SimpleViewerOptions>;
 
+/** The partial options for a scene, or an empty object when none is set. */
+export declare function resolveScene(scene?: ViewerScene): Partial<SimpleViewerOptions>;
+
 /**
  * Click-picking and hotspot-occlusion raycast options.
  */
@@ -532,6 +551,11 @@ export declare interface SimpleViewerHandle {
     /**
      * Replace the environment map (reflections + background) at runtime with the
      * equirectangular HDRI/LDR image at `url`. Cached by URL, so re-applying is cheap.
+     *
+     * Like the capture APIs, the environment APIs throw (async ones reject) with
+     * INVALID_STATE when the viewer was disposed — including a dispose that lands
+     * while the map is still loading. Fire-and-forget callers should attach a
+     * `.catch` if unmount races are possible (e.g. React StrictMode in dev).
      */
     setEnvironmentMap: (url: string) => Promise<void>;
     /** Restore the built-in studio environment and clean gradient background. */
@@ -553,6 +577,13 @@ export declare interface SimpleViewerOptions {
      * pass overrides the preset's values.
      */
     preset?: ViewerPreset;
+    /**
+     * A one-word scene (`studio_dome`, `studio_soft`) that selects the physical
+     * set — floor, backdrop and how the studio environment is built. The
+     * structural counterpart of `preset`: switching a scene rebuilds the viewer.
+     * Any other option you pass overrides the scene's values.
+     */
+    scene?: ViewerScene;
     /**
      * Length unit the model geometry is authored in (default `'meters'`).
      * Non-meter models are rescaled on load — without touching the model's own
@@ -693,6 +724,16 @@ export declare interface SimpleViewerProps {
     children?: React_2.ReactNode;
 }
 
+/**
+ * How the built-in procedural studio environment is graded when it is built.
+ * `crisp` (the default) darkens the surround and boosts the soft-box panels so
+ * glossy materials show distinct highlights; `soft` uses the studio room
+ * as-built for an even, low-contrast wraparound light. Structural — the
+ * environment is baked once at construction, so changing it rebuilds the
+ * viewer. Scenes (`SimpleViewerOptions.scene`) drive this.
+ */
+export declare type StudioLook = 'crisp' | 'soft';
+
 export declare class ThreeViewerError extends Error {
     readonly code: ErrorCode;
     readonly context?: ErrorContext | undefined;
@@ -756,6 +797,16 @@ declare interface Vec3Like {
  */
 export declare const VIEWER_PRESETS: Record<ViewerPreset, Partial<SimpleViewerOptions>>;
 
+/**
+ * Scenes: named SETS layered over the defaults (deep-merged), the structural
+ * counterpart of `VIEWER_PRESETS`. Where a preset grades the picture (runtime
+ * look fields, applied live), a scene selects the physical set the model
+ * stands in — floor, backdrop and how the studio environment is built — so
+ * each scene only sets **structural** fields and switching one rebuilds the
+ * viewer. Explicit user options always win.
+ */
+export declare const VIEWER_SCENES: Record<ViewerScene, Partial<SimpleViewerOptions>>;
+
 /**
  * The public, Three.js-typed view of the viewer event contract — the shape
  * consumers see on the viewer handle's `events` emitter. Shares its single
@@ -842,4 +893,21 @@ declare interface ViewerEventMap_2<TObject, TCamera, TControls, THandle> {
  */
 export declare type ViewerPreset = 'studio' | 'product' | 'neutral' | 'dark' | 'outdoor';
 
+/**
+ * A one-word scene that selects the physical SET the model stands in — the
+ * floor, the backdrop geometry and how the built-in studio environment is
+ * built. Set it on `SimpleViewerOptions.scene`. The scene is the structural
+ * counterpart of the tonal `preset` axis: presets grade the picture live,
+ * scenes swap the set (switching one rebuilds the viewer). Any explicit
+ * option you pass overrides the scene's values.
+ *
+ * - `studio_dome` — the default set: invisible shadow-catcher floor, baked
+ *   soft contact shadow, crisp contrast-pushed studio environment (distinct
+ *   highlights on glossy materials) and the path-traced infinity dome.
+ * - `studio_soft` — the same set lit softly: the studio environment is used
+ *   as-built, without the contrast push, for an even, low-drama wraparound
+ *   light that flatters matte materials and softens speculars.
+ */
+export declare type ViewerScene = 'studio_dome' | 'studio_soft';
+
 export { }

package/dist/index.d.ts

@@ -132,6 +132,12 @@ export declare enum ControlType {
     OrbitControls = "OrbitControls"
 }
 
+/** The scene every viewer stands in when none is set. */
+export declare const DEFAULT_SCENE: ViewerScene;
+
+/** The grade the studio environment is built with when none is set. */
+export declare const DEFAULT_STUDIO_LOOK: StudioLook;
+
 /**
  * Default options using the new format structure
  */
@@ -203,6 +209,8 @@ export declare interface EnvironmentOptions {
      * Runtime-tunable via `updateOptions` — presets drive this live.
      */
     environmentIntensity?: number;
+    /** Grade of the built-in studio environment; ignored when `url` is set. */
+    studioLook?: StudioLook;
 }
 
 export declare enum ErrorCode {
@@ -225,6 +233,7 @@ export declare enum ErrorCode {
     INVALID_STATE = "INVALID_STATE",
     INVALID_PARAMETER = "INVALID_PARAMETER",
     OPERATION_FAILED = "OPERATION_FAILED",
+    POST_PROCESSING_FAILED = "POST_PROCESSING_FAILED",
     UNKNOWN = "UNKNOWN"
 }
 
@@ -418,6 +427,13 @@ export declare interface PathTracingOptions {
 export declare interface RendererOptions {
     antialias?: boolean;
     alpha?: boolean;
+    premultipliedAlpha?: boolean;
+    /**
+     * Note: the viewer forces this ON regardless — a completed path-traced
+     * frame must survive on the canvas for captureStill to read back.
+     */
+    preserveDrawingBuffer?: boolean;
+    powerPreference?: 'high-performance' | 'low-power' | 'default';
     shadowMapEnabled?: boolean;
     pixelRatio?: number;
     /** A `THREE.ShadowMapType` constant (e.g. `THREE.PCFShadowMap` === 1). */
@@ -474,6 +490,9 @@ export declare interface RenderingOptions {
 /** The partial options for a preset, or an empty object when none is set. */
 export declare function resolvePreset(preset?: ViewerPreset): Partial<SimpleViewerOptions>;
 
+/** The partial options for a scene, or an empty object when none is set. */
+export declare function resolveScene(scene?: ViewerScene): Partial<SimpleViewerOptions>;
+
 /**
  * Click-picking and hotspot-occlusion raycast options.
  */
@@ -532,6 +551,11 @@ export declare interface SimpleViewerHandle {
     /**
      * Replace the environment map (reflections + background) at runtime with the
      * equirectangular HDRI/LDR image at `url`. Cached by URL, so re-applying is cheap.
+     *
+     * Like the capture APIs, the environment APIs throw (async ones reject) with
+     * INVALID_STATE when the viewer was disposed — including a dispose that lands
+     * while the map is still loading. Fire-and-forget callers should attach a
+     * `.catch` if unmount races are possible (e.g. React StrictMode in dev).
      */
     setEnvironmentMap: (url: string) => Promise<void>;
     /** Restore the built-in studio environment and clean gradient background. */
@@ -553,6 +577,13 @@ export declare interface SimpleViewerOptions {
      * pass overrides the preset's values.
      */
     preset?: ViewerPreset;
+    /**
+     * A one-word scene (`studio_dome`, `studio_soft`) that selects the physical
+     * set — floor, backdrop and how the studio environment is built. The
+     * structural counterpart of `preset`: switching a scene rebuilds the viewer.
+     * Any other option you pass overrides the scene's values.
+     */
+    scene?: ViewerScene;
     /**
      * Length unit the model geometry is authored in (default `'meters'`).
      * Non-meter models are rescaled on load — without touching the model's own
@@ -693,6 +724,16 @@ export declare interface SimpleViewerProps {
     children?: React_2.ReactNode;
 }
 
+/**
+ * How the built-in procedural studio environment is graded when it is built.
+ * `crisp` (the default) darkens the surround and boosts the soft-box panels so
+ * glossy materials show distinct highlights; `soft` uses the studio room
+ * as-built for an even, low-contrast wraparound light. Structural — the
+ * environment is baked once at construction, so changing it rebuilds the
+ * viewer. Scenes (`SimpleViewerOptions.scene`) drive this.
+ */
+export declare type StudioLook = 'crisp' | 'soft';
+
 export declare class ThreeViewerError extends Error {
     readonly code: ErrorCode;
     readonly context?: ErrorContext | undefined;
@@ -756,6 +797,16 @@ declare interface Vec3Like {
  */
 export declare const VIEWER_PRESETS: Record<ViewerPreset, Partial<SimpleViewerOptions>>;
 
+/**
+ * Scenes: named SETS layered over the defaults (deep-merged), the structural
+ * counterpart of `VIEWER_PRESETS`. Where a preset grades the picture (runtime
+ * look fields, applied live), a scene selects the physical set the model
+ * stands in — floor, backdrop and how the studio environment is built — so
+ * each scene only sets **structural** fields and switching one rebuilds the
+ * viewer. Explicit user options always win.
+ */
+export declare const VIEWER_SCENES: Record<ViewerScene, Partial<SimpleViewerOptions>>;
+
 /**
  * The public, Three.js-typed view of the viewer event contract — the shape
  * consumers see on the viewer handle's `events` emitter. Shares its single
@@ -842,4 +893,21 @@ declare interface ViewerEventMap_2<TObject, TCamera, TControls, THandle> {
  */
 export declare type ViewerPreset = 'studio' | 'product' | 'neutral' | 'dark' | 'outdoor';
 
+/**
+ * A one-word scene that selects the physical SET the model stands in — the
+ * floor, the backdrop geometry and how the built-in studio environment is
+ * built. Set it on `SimpleViewerOptions.scene`. The scene is the structural
+ * counterpart of the tonal `preset` axis: presets grade the picture live,
+ * scenes swap the set (switching one rebuilds the viewer). Any explicit
+ * option you pass overrides the scene's values.
+ *
+ * - `studio_dome` — the default set: invisible shadow-catcher floor, baked
+ *   soft contact shadow, crisp contrast-pushed studio environment (distinct
+ *   highlights on glossy materials) and the path-traced infinity dome.
+ * - `studio_soft` — the same set lit softly: the studio environment is used
+ *   as-built, without the contrast push, for an even, low-drama wraparound
+ *   light that flatters matte materials and softens speculars.
+ */
+export declare type ViewerScene = 'studio_dome' | 'studio_soft';
+
 export { }