softbox 4.3.2 → 4.4.1

package/dist/index.d.cts

@@ -2,6 +2,7 @@ import { default as default_2 } from 'react';
 import * as React_2 from 'react';
 import * as THREE from 'three';
 
+/** Uniform fill from every direction; lifts shadows, adds no shading. */
 export declare interface AmbientLightOptions {
     color?: string | number;
     intensity?: number;
@@ -21,12 +22,25 @@ export declare interface AxesHelperOptions {
     size?: number;
 }
 
+/** Perspective camera setup. World units are meters (see `units`). */
 export declare interface CameraOptions {
+    /** Starting camera position as `[x, y, z]`. */
     position?: [number, number, number];
+    /** Point the camera looks at and the controls orbit around. */
     target?: [number, number, number];
+    /** Vertical field of view in degrees. */
     fov?: number;
+    /** Near clipping plane distance. */
     near?: number;
+    /** Far clipping plane distance. */
     far?: number;
+    /**
+     * Frame the loaded model automatically (default `true`): the camera moves
+     * to a standard product-shot view — left-front, slightly elevated — around
+     * the model's center, at a distance computed from its bounds, and the
+     * controls re-target the center. This OVERRIDES `position`/`target`;
+     * disable it to keep your configured view exactly.
+     */
     autoFitToObject?: boolean;
 }
 
@@ -63,19 +77,40 @@ export declare type ControlsInstance = {
     getThreeControls?(): unknown;
 };
 
+/** Mouse/touch camera controls (three.js OrbitControls semantics). */
 export declare interface ControlsOptions {
+    /**
+     * `OrbitControls` (default) orbits around the model like a turntable;
+     * `MapControls` pans on drag instead — the map/floor-plan idiom.
+     */
     type?: ControlType;
+    /** Master switch: `false` freezes all user camera input. */
     enabled?: boolean;
+    /** Inertial easing after a drag ends, instead of an instant stop. */
     enableDamping?: boolean;
+    /** Damping strength: lower = longer glide (softbox default 0.25). */
     dampingFactor?: number;
+    /** Allow dolly/zoom (wheel, pinch). */
     enableZoom?: boolean;
+    /** Allow orbiting (primary-button drag). */
     enableRotate?: boolean;
+    /** Allow panning (secondary-button or two-finger drag). */
     enablePan?: boolean;
+    /**
+     * Turntable mode: the camera orbits the model on its own. Runtime-tunable
+     * via `updateOptions`. While spinning, a path-traced `captureStill()`
+     * rejects — the accumulation resets every frame and can never converge.
+     */
     autoRotate?: boolean;
+    /** Turntable speed: 2.0 ≈ one full orbit in 30 s at 60 fps. */
     autoRotateSpeed?: number;
+    /** Closest dolly distance to the target. */
     minDistance?: number;
+    /** Farthest dolly distance from the target. */
     maxDistance?: number;
+    /** Lowest vertical orbit angle in radians (0 = looking straight down from above). */
     minPolarAngle?: number;
+    /** Highest vertical orbit angle in radians (π = from below; π/2 stops at the horizon). */
     maxPolarAngle?: number;
 }
 
@@ -89,16 +124,29 @@ export declare enum ControlType {
  */
 export declare const defaultOptions: SimpleViewerOptions;
 
+/**
+ * The key light: parallel rays from `position` toward the origin. The only
+ * light that casts shadows — the contact-shadow bake samples it as an area
+ * light, so its direction sets where the floor shadow falls.
+ */
 export declare interface DirectionalLightOptions {
     color?: string | number;
     intensity?: number;
+    /** Direction is position → origin; distance does not attenuate. */
     position?: Vec3Like | [number, number, number];
+    /** Cast real-time shadows (and feed the baked contact shadow). */
     castShadow?: boolean;
+    /** three.js DirectionalLight.shadow tuning; the shadow camera is auto-fitted to the model on load. */
     shadow?: {
+        /** Shadow map resolution — higher is crisper and costs GPU memory. */
         mapSize?: {
             width: number;
             height: number;
         };
+        /**
+         * Orthographic frustum: left/right/top/bottom are overridden by the
+         * auto-fit on load; near/far keep their configured values.
+         */
         camera?: {
             near?: number;
             far?: number;
@@ -107,15 +155,32 @@ export declare interface DirectionalLightOptions {
             top?: number;
             bottom?: number;
         };
+        /** Depth offset against shadow acne (self-shadowing stripes). */
         bias?: number;
+        /** Shadow edge blur in shadow-map texels. */
         radius?: number;
     };
 }
 
+/**
+ * Image-based lighting and background. Without a `url` the viewer lights the
+ * scene with its built-in procedural studio environment — zero network
+ * requests.
+ */
 export declare interface EnvironmentOptions {
+    /**
+     * Equirectangular environment map (`.hdr`, `.exr`, or an LDR image) used
+     * for both lighting and the background.
+     */
     url?: string;
+    /** Blurs the background rendering only (0–1); lighting stays sharp. */
     backgroundBlurriness?: number;
+    /** Brightness multiplier for the background rendering only. */
     backgroundIntensity?: number;
+    /**
+     * Lighting intensity multiplier the environment applies to materials.
+     * Runtime-tunable via `updateOptions` — presets drive this live.
+     */
     environmentIntensity?: number;
 }
 
@@ -185,8 +250,15 @@ export declare interface HelperOptions {
     darkStudioMode?: boolean;
 }
 
+/**
+ * Two-tone gradient fill: one color arriving from above, another bouncing up
+ * from below. The default rig uses a warm pale-yellow sky over a dark navy
+ * ground.
+ */
 export declare interface HemisphereLightOptions {
+    /** Color arriving from above. */
     skyColor?: string | number;
+    /** Color bouncing up from below. */
     groundColor?: string | number;
     intensity?: number;
 }
@@ -213,6 +285,10 @@ export declare interface HotspotProps {
     children?: default_2.ReactNode;
 }
 
+/**
+ * The three-light studio rig. Every light is optional; the defaults are a
+ * balanced product-shot setup (see `defaultOptions.lighting`).
+ */
 export declare interface LightingOptions {
     ambientLight?: AmbientLightOptions;
     hemisphereLight?: HemisphereLightOptions;
@@ -278,13 +354,32 @@ export declare interface LoadingIndicatorOptions {
 /** Length unit the model's geometry is authored in. */
 export declare type ModelUnits = 'meters' | 'centimeters' | 'millimeters' | 'feet' | 'inches';
 
+/**
+ * Progressive path tracing for photoreal stills (three-gpu-pathtracer). The
+ * tracer accumulates samples whenever the camera rests and presents the
+ * converged frame; it ships in a lazy chunk that loads only when enabled.
+ *
+ * The whole object is structural in `<SimpleViewer>`: changing ANY field
+ * rebuilds the viewer (and reloads the model).
+ */
 export declare interface PathTracingOptions {
+    /** Builds the tracer at viewer construction. */
     enabled?: boolean;
+    /**
+     * Samples to accumulate before the frame counts as converged
+     * (`pathtracing:complete`, and what a path-traced `captureStill()` awaits).
+     * More samples = cleaner image, linearly more GPU time.
+     */
     maxSamples?: number;
+    /** Light-path depth: how many surface bounces each ray may take. */
     bounces?: number;
+    /** Extra ray depth through transmissive (glass-like) materials. */
     transmissiveBounces?: number;
+    /** Accumulation resolution as a fraction of canvas size (0.5 = quarter pixels, 4× faster). */
     renderScale?: number;
+    /** Resolution fraction of the fast preview shown while the camera moves. */
     lowResScale?: number;
+    /** Drop to the low-res preview during interaction instead of stalling. */
     dynamicLowRes?: boolean;
 }
 
@@ -435,6 +530,15 @@ export declare interface SimpleViewerOptions {
      */
     animationLoop?: ((time: number) => void) | null;
     replaceWithScreenshotOnComplete?: boolean;
+    /**
+     * When to boot the WebGL engine and fetch the model (default `'eager'`).
+     * `'lazy'` defers everything until the viewer first approaches the
+     * viewport (like `<img loading="lazy">`) — on pages with many viewers
+     * only the visible ones pay for a GL context and a model download. Once
+     * booted a viewer stays booted; where IntersectionObserver is unavailable
+     * the option gracefully degrades to eager.
+     */
+    loading?: 'eager' | 'lazy';
     /**
      * Built-in loading overlay shown while a model loads. `true`/omitted shows the
      * default spinner; `false` hides it (render your own via the loading events);

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { default as default_2 } from 'react';
 import * as React_2 from 'react';
 import * as THREE from 'three';
 
+/** Uniform fill from every direction; lifts shadows, adds no shading. */
 export declare interface AmbientLightOptions {
     color?: string | number;
     intensity?: number;
@@ -21,12 +22,25 @@ export declare interface AxesHelperOptions {
     size?: number;
 }
 
+/** Perspective camera setup. World units are meters (see `units`). */
 export declare interface CameraOptions {
+    /** Starting camera position as `[x, y, z]`. */
     position?: [number, number, number];
+    /** Point the camera looks at and the controls orbit around. */
     target?: [number, number, number];
+    /** Vertical field of view in degrees. */
     fov?: number;
+    /** Near clipping plane distance. */
     near?: number;
+    /** Far clipping plane distance. */
     far?: number;
+    /**
+     * Frame the loaded model automatically (default `true`): the camera moves
+     * to a standard product-shot view — left-front, slightly elevated — around
+     * the model's center, at a distance computed from its bounds, and the
+     * controls re-target the center. This OVERRIDES `position`/`target`;
+     * disable it to keep your configured view exactly.
+     */
     autoFitToObject?: boolean;
 }
 
@@ -63,19 +77,40 @@ export declare type ControlsInstance = {
     getThreeControls?(): unknown;
 };
 
+/** Mouse/touch camera controls (three.js OrbitControls semantics). */
 export declare interface ControlsOptions {
+    /**
+     * `OrbitControls` (default) orbits around the model like a turntable;
+     * `MapControls` pans on drag instead — the map/floor-plan idiom.
+     */
     type?: ControlType;
+    /** Master switch: `false` freezes all user camera input. */
     enabled?: boolean;
+    /** Inertial easing after a drag ends, instead of an instant stop. */
     enableDamping?: boolean;
+    /** Damping strength: lower = longer glide (softbox default 0.25). */
     dampingFactor?: number;
+    /** Allow dolly/zoom (wheel, pinch). */
     enableZoom?: boolean;
+    /** Allow orbiting (primary-button drag). */
     enableRotate?: boolean;
+    /** Allow panning (secondary-button or two-finger drag). */
     enablePan?: boolean;
+    /**
+     * Turntable mode: the camera orbits the model on its own. Runtime-tunable
+     * via `updateOptions`. While spinning, a path-traced `captureStill()`
+     * rejects — the accumulation resets every frame and can never converge.
+     */
     autoRotate?: boolean;
+    /** Turntable speed: 2.0 ≈ one full orbit in 30 s at 60 fps. */
     autoRotateSpeed?: number;
+    /** Closest dolly distance to the target. */
     minDistance?: number;
+    /** Farthest dolly distance from the target. */
     maxDistance?: number;
+    /** Lowest vertical orbit angle in radians (0 = looking straight down from above). */
     minPolarAngle?: number;
+    /** Highest vertical orbit angle in radians (π = from below; π/2 stops at the horizon). */
     maxPolarAngle?: number;
 }
 
@@ -89,16 +124,29 @@ export declare enum ControlType {
  */
 export declare const defaultOptions: SimpleViewerOptions;
 
+/**
+ * The key light: parallel rays from `position` toward the origin. The only
+ * light that casts shadows — the contact-shadow bake samples it as an area
+ * light, so its direction sets where the floor shadow falls.
+ */
 export declare interface DirectionalLightOptions {
     color?: string | number;
     intensity?: number;
+    /** Direction is position → origin; distance does not attenuate. */
     position?: Vec3Like | [number, number, number];
+    /** Cast real-time shadows (and feed the baked contact shadow). */
     castShadow?: boolean;
+    /** three.js DirectionalLight.shadow tuning; the shadow camera is auto-fitted to the model on load. */
     shadow?: {
+        /** Shadow map resolution — higher is crisper and costs GPU memory. */
         mapSize?: {
             width: number;
             height: number;
         };
+        /**
+         * Orthographic frustum: left/right/top/bottom are overridden by the
+         * auto-fit on load; near/far keep their configured values.
+         */
         camera?: {
             near?: number;
             far?: number;
@@ -107,15 +155,32 @@ export declare interface DirectionalLightOptions {
             top?: number;
             bottom?: number;
         };
+        /** Depth offset against shadow acne (self-shadowing stripes). */
         bias?: number;
+        /** Shadow edge blur in shadow-map texels. */
         radius?: number;
     };
 }
 
+/**
+ * Image-based lighting and background. Without a `url` the viewer lights the
+ * scene with its built-in procedural studio environment — zero network
+ * requests.
+ */
 export declare interface EnvironmentOptions {
+    /**
+     * Equirectangular environment map (`.hdr`, `.exr`, or an LDR image) used
+     * for both lighting and the background.
+     */
     url?: string;
+    /** Blurs the background rendering only (0–1); lighting stays sharp. */
     backgroundBlurriness?: number;
+    /** Brightness multiplier for the background rendering only. */
     backgroundIntensity?: number;
+    /**
+     * Lighting intensity multiplier the environment applies to materials.
+     * Runtime-tunable via `updateOptions` — presets drive this live.
+     */
     environmentIntensity?: number;
 }
 
@@ -185,8 +250,15 @@ export declare interface HelperOptions {
     darkStudioMode?: boolean;
 }
 
+/**
+ * Two-tone gradient fill: one color arriving from above, another bouncing up
+ * from below. The default rig uses a warm pale-yellow sky over a dark navy
+ * ground.
+ */
 export declare interface HemisphereLightOptions {
+    /** Color arriving from above. */
     skyColor?: string | number;
+    /** Color bouncing up from below. */
     groundColor?: string | number;
     intensity?: number;
 }
@@ -213,6 +285,10 @@ export declare interface HotspotProps {
     children?: default_2.ReactNode;
 }
 
+/**
+ * The three-light studio rig. Every light is optional; the defaults are a
+ * balanced product-shot setup (see `defaultOptions.lighting`).
+ */
 export declare interface LightingOptions {
     ambientLight?: AmbientLightOptions;
     hemisphereLight?: HemisphereLightOptions;
@@ -278,13 +354,32 @@ export declare interface LoadingIndicatorOptions {
 /** Length unit the model's geometry is authored in. */
 export declare type ModelUnits = 'meters' | 'centimeters' | 'millimeters' | 'feet' | 'inches';
 
+/**
+ * Progressive path tracing for photoreal stills (three-gpu-pathtracer). The
+ * tracer accumulates samples whenever the camera rests and presents the
+ * converged frame; it ships in a lazy chunk that loads only when enabled.
+ *
+ * The whole object is structural in `<SimpleViewer>`: changing ANY field
+ * rebuilds the viewer (and reloads the model).
+ */
 export declare interface PathTracingOptions {
+    /** Builds the tracer at viewer construction. */
     enabled?: boolean;
+    /**
+     * Samples to accumulate before the frame counts as converged
+     * (`pathtracing:complete`, and what a path-traced `captureStill()` awaits).
+     * More samples = cleaner image, linearly more GPU time.
+     */
     maxSamples?: number;
+    /** Light-path depth: how many surface bounces each ray may take. */
     bounces?: number;
+    /** Extra ray depth through transmissive (glass-like) materials. */
     transmissiveBounces?: number;
+    /** Accumulation resolution as a fraction of canvas size (0.5 = quarter pixels, 4× faster). */
     renderScale?: number;
+    /** Resolution fraction of the fast preview shown while the camera moves. */
     lowResScale?: number;
+    /** Drop to the low-res preview during interaction instead of stalling. */
     dynamicLowRes?: boolean;
 }
 
@@ -435,6 +530,15 @@ export declare interface SimpleViewerOptions {
      */
     animationLoop?: ((time: number) => void) | null;
     replaceWithScreenshotOnComplete?: boolean;
+    /**
+     * When to boot the WebGL engine and fetch the model (default `'eager'`).
+     * `'lazy'` defers everything until the viewer first approaches the
+     * viewport (like `<img loading="lazy">`) — on pages with many viewers
+     * only the visible ones pay for a GL context and a model download. Once
+     * booted a viewer stays booted; where IntersectionObserver is unavailable
+     * the option gracefully degrades to eager.
+     */
+    loading?: 'eager' | 'lazy';
     /**
      * Built-in loading overlay shown while a model loads. `true`/omitted shows the
      * default spinner; `false` hides it (render your own via the loading events);

package/dist/simple-viewer.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-QkQEREfW.cjs");exports.ControlType=e.ControlType;exports.ErrorCode=e.ErrorCode;exports.Hotspot=e.Hotspot;exports.SimpleViewer=e.SimpleViewerWrapper;exports.ThreeViewerError=e.ThreeViewerError;exports.TypedEventEmitter=e.TypedEventEmitter;exports.VIEWER_PRESETS=e.VIEWER_PRESETS;exports.defaultOptions=e.defaultOptions;exports.resolvePreset=e.resolvePreset;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-BiSXFVUP.cjs");exports.ControlType=e.ControlType;exports.ErrorCode=e.ErrorCode;exports.Hotspot=e.Hotspot;exports.SimpleViewer=e.SimpleViewerWrapper;exports.ThreeViewerError=e.ThreeViewerError;exports.TypedEventEmitter=e.TypedEventEmitter;exports.VIEWER_PRESETS=e.VIEWER_PRESETS;exports.defaultOptions=e.defaultOptions;exports.resolvePreset=e.resolvePreset;

package/dist/simple-viewer.es.js

@@ -1,4 +1,4 @@
-import { f as s, E as o, H as a, i as t, e as E, T as i, V as p, j as T, r as l } from "./index-BdrQXlCy.js";
+import { f as s, E as o, H as a, i as t, e as E, T as i, V as p, j as T, r as l } from "./index-uh2exMyt.js";
 export {
   s as ControlType,
   o as ErrorCode,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "softbox",
   "private": false,
-  "version": "4.3.2",
+  "version": "4.4.1",
   "homepage": "https://leming.github.io/softbox/",
   "type": "module",
   "description": "Batteries-included React 3D viewer — any GLB looks studio-shot in one line",