softbox 4.0.0

package/dist/index.d.cts

@@ -0,0 +1,621 @@
+import { default as default_2 } from 'react';
+import * as React_2 from 'react';
+import * as THREE from 'three';
+
+export declare interface AmbientLightOptions {
+    color?: string | number;
+    intensity?: number;
+}
+
+export declare interface AnimationOptions {
+    /**
+     * Start playback when a model with clips loads: `true` plays ALL clips
+     * (looped), a string plays the clip with that name.
+     */
+    autoplay?: boolean | string;
+    /** Playback rate multiplier (1 = authored speed). Applied live. */
+    speed?: number;
+}
+
+export declare interface AxesHelperOptions {
+    size?: number;
+}
+
+export declare interface CameraOptions {
+    position?: [number, number, number];
+    target?: [number, number, number];
+    fov?: number;
+    near?: number;
+    far?: number;
+    autoFitToObject?: boolean;
+}
+
+/**
+ * Output size for `captureStill`, in pixels. When only one dimension is given
+ * the other follows the canvas aspect ratio; when both are omitted the still
+ * matches the canvas drawing buffer.
+ */
+export declare interface CaptureStillOptions {
+    width?: number;
+    height?: number;
+}
+
+export declare interface CaptureVideoOptions {
+    /** Capture length in seconds. Default 3. */
+    duration?: number;
+    /** Frame rate handed to `canvas.captureStream()`. Default 30. */
+    fps?: number;
+    /**
+     * Preferred container/codec (e.g. `'video/webm;codecs=vp9'`). When omitted
+     * or unsupported the best supported WebM flavor is picked, falling back to
+     * MP4 (Safari) and finally the browser default.
+     */
+    mimeType?: string;
+    /** Encoder bitrate hint in bits per second. */
+    videoBitsPerSecond?: number;
+}
+
+export declare type ControlsInstance = {
+    enabled: boolean;
+    update(): void;
+    dispose(): void;
+    target: THREE.Vector3;
+    getThreeControls?(): unknown;
+};
+
+export declare interface ControlsOptions {
+    type?: ControlType;
+    enabled?: boolean;
+    enableDamping?: boolean;
+    dampingFactor?: number;
+    enableZoom?: boolean;
+    enableRotate?: boolean;
+    enablePan?: boolean;
+    autoRotate?: boolean;
+    autoRotateSpeed?: number;
+    minDistance?: number;
+    maxDistance?: number;
+    minPolarAngle?: number;
+    maxPolarAngle?: number;
+}
+
+export declare enum ControlType {
+    MapControls = "MapControls",
+    OrbitControls = "OrbitControls"
+}
+
+/**
+ * Default options using the new format structure
+ */
+export declare const defaultOptions: SimpleViewerOptions;
+
+export declare interface DirectionalLightOptions {
+    color?: string | number;
+    intensity?: number;
+    position?: Vec3Like | [number, number, number];
+    castShadow?: boolean;
+    shadow?: {
+        mapSize?: {
+            width: number;
+            height: number;
+        };
+        camera?: {
+            near?: number;
+            far?: number;
+            left?: number;
+            right?: number;
+            top?: number;
+            bottom?: number;
+        };
+        bias?: number;
+        radius?: number;
+    };
+}
+
+export declare interface EnvironmentOptions {
+    url?: string;
+    backgroundBlurriness?: number;
+    backgroundIntensity?: number;
+    environmentIntensity?: number;
+}
+
+export declare enum ErrorCode {
+    SCENE_INIT_FAILED = "SCENE_INIT_FAILED",
+    RENDERER_INIT_FAILED = "RENDERER_INIT_FAILED",
+    RENDERER_NOT_INITIALIZED = "RENDERER_NOT_INITIALIZED",
+    CAMERA_INIT_FAILED = "CAMERA_INIT_FAILED",
+    WEBGL_NOT_SUPPORTED = "WEBGL_NOT_SUPPORTED",
+    INITIALIZATION_FAILED = "INITIALIZATION_FAILED",
+    PATH_TRACING_INIT_FAILED = "PATH_TRACING_INIT_FAILED",
+    MODEL_LOAD_FAILED = "MODEL_LOAD_FAILED",
+    TEXTURE_LOAD_FAILED = "TEXTURE_LOAD_FAILED",
+    RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND",
+    UNSUPPORTED_FORMAT = "UNSUPPORTED_FORMAT",
+    INVALID_CONFIGURATION = "INVALID_CONFIGURATION",
+    RENDER_ERROR = "RENDER_ERROR",
+    RENDER_FAILED = "RENDER_FAILED",
+    SCENE_OPERATION_FAILED = "SCENE_OPERATION_FAILED",
+    COMPONENT_NOT_MOUNTED = "COMPONENT_NOT_MOUNTED",
+    INVALID_STATE = "INVALID_STATE",
+    INVALID_PARAMETER = "INVALID_PARAMETER",
+    OPERATION_FAILED = "OPERATION_FAILED",
+    UNKNOWN = "UNKNOWN"
+}
+
+export declare interface ErrorContext {
+    [key: string]: unknown;
+}
+
+export declare interface GizmoOptions {
+    placement?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    size?: number;
+}
+
+export declare interface GridHelperOptions {
+    size?: number;
+    divisions?: number;
+    colorCenterLine?: string | number;
+    colorGrid?: string | number;
+    type?: 'square_wire' | 'hexagonal_wire' | 'hexagonal_glass' | 'stone_tiles';
+    opacity?: number;
+    styleOptions?: {
+        hexRadius?: number;
+        tileSize?: number;
+        texture?: string;
+        normalMap?: string;
+        roughnessMap?: string;
+        metalness?: number;
+        roughness?: number;
+        transmission?: number;
+        thickness?: number;
+        ior?: number;
+        height?: number;
+        bevelSize?: number;
+        randomHeight?: boolean;
+        randomRotation?: boolean;
+    };
+}
+
+export declare interface HelperOptions {
+    grid?: boolean | GridHelperOptions;
+    axes?: boolean | AxesHelperOptions;
+    stats?: boolean;
+    gizmo?: boolean | GizmoOptions;
+    studioEnvironment?: boolean;
+    darkStudioMode?: boolean;
+}
+
+export declare interface HemisphereLightOptions {
+    skyColor?: string | number;
+    groundColor?: string | number;
+    intensity?: number;
+}
+
+/**
+ * A DOM annotation anchored to a world-space point of the scene. Render it as
+ * a child of `SimpleViewer`; the anchor is projected through the camera after
+ * every rendered frame, so it tracks orbiting, zooming and resizes. Points
+ * behind the camera are hidden; `occlude` also hides it when the model covers
+ * the anchor. The projection math lives behind the viewer's anchor-projection
+ * port — this component only wires events to DOM styles.
+ */
+export declare function Hotspot({ position, occlude, children }: HotspotProps): default_2.JSX.Element;
+
+export declare interface HotspotProps {
+    /** World-space anchor point, e.g. a `point` from the `object:selected` event. */
+    position: [number, number, number];
+    /**
+     * Hide the hotspot when the model occludes its anchor point (a raycast per
+     * rendered frame). Off by default.
+     */
+    occlude?: boolean;
+    /** Pin content; without children a default dot pin is rendered. */
+    children?: default_2.ReactNode;
+}
+
+export declare interface LightingOptions {
+    ambientLight?: AmbientLightOptions;
+    hemisphereLight?: HemisphereLightOptions;
+    directionalLight?: DirectionalLightOptions;
+}
+
+/**
+ * Compression-decoder configuration for the built-in glTF/GLB loader.
+ *
+ * DRACO (geometry), KTX2/Basis (textures) and Meshopt (geometry) are all wired
+ * into the loader by default, so compressed assets exported by Blender,
+ * `gltfpack`, `gltf-transform`, etc. load without any extra setup.
+ *
+ * Meshopt is bundled and needs no external file. DRACO and KTX2 require a small
+ * WebAssembly decoder that is fetched **on demand** — only the first time an
+ * asset actually uses that compression — from a version-pinned CDN by default.
+ * Point `dracoDecoderPath` / `ktx2TranscoderPath` at a self-hosted copy (e.g.
+ * `three/examples/jsm/libs/draco/` and `.../basis/` copied into your public dir)
+ * for a fully offline, no-CDN setup.
+ */
+export declare interface LoaderOptions {
+    /** Decode DRACO-compressed geometry. Default: `true`. */
+    draco?: boolean;
+    /** Decode KTX2 / Basis-compressed textures. Default: `true`. */
+    ktx2?: boolean;
+    /** Decode Meshopt-compressed geometry. Default: `true`. */
+    meshopt?: boolean;
+    /**
+     * Directory holding the DRACO decoder (`draco_wasm_wrapper.js` +
+     * `draco_decoder.wasm`). Must end with a trailing slash. Defaults to a
+     * version-pinned jsDelivr URL matching the installed Three.js revision.
+     */
+    dracoDecoderPath?: string;
+    /**
+     * Directory holding the KTX2 Basis transcoder (`basis_transcoder.js` +
+     * `basis_transcoder.wasm`). Must end with a trailing slash. Defaults to a
+     * version-pinned jsDelivr URL matching the installed Three.js revision.
+     */
+    ktx2TranscoderPath?: string;
+}
+
+/**
+ * Configuration for the built-in loading overlay shown while a model loads.
+ *
+ * Pass a boolean on `SimpleViewerOptions.loadingIndicator` to toggle the
+ * default overlay, or this object to customize it. Set `loadingIndicator: false`
+ * to render your own using the `model:loading` / `model:loaded` / `model:error`
+ * events on the viewer handle.
+ */
+export declare interface LoadingIndicatorOptions {
+    /** Show the built-in overlay. Default: `true`. */
+    enabled?: boolean;
+    /** Text under the spinner while loading. Default: `'Loading…'`. */
+    label?: string;
+    /** Message shown if the model fails to load. Default: the error message. */
+    errorLabel?: string;
+    /** Spinner and text color. Default: `'#ffffff'`. */
+    color?: string;
+    /** Backdrop scrim behind the spinner. Default: a subtle dark scrim. */
+    backdrop?: string;
+}
+
+export declare interface PathTracingOptions {
+    enabled?: boolean;
+    maxSamples?: number;
+    bounces?: number;
+    transmissiveBounces?: number;
+    renderScale?: number;
+    lowResScale?: number;
+    dynamicLowRes?: boolean;
+}
+
+export declare interface RendererOptions {
+    antialias?: boolean;
+    alpha?: boolean;
+    shadowMapEnabled?: boolean;
+    pixelRatio?: number;
+    /** A `THREE.ShadowMapType` constant (e.g. `THREE.PCFShadowMap` === 1). */
+    shadowMapType?: number;
+    /** A `THREE.ToneMapping` constant (e.g. `THREE.ACESFilmicToneMapping` === 6). */
+    toneMapping?: number;
+    toneMappingExposure?: number;
+    /** A `THREE.ColorSpace` value (e.g. `'srgb'`, `'srgb-linear'`). */
+    outputColorSpace?: string;
+}
+
+/**
+ * Rendering behavior options
+ */
+export declare interface RenderingOptions {
+    /**
+     * Enable idle detection to stop rendering when inactive
+     * @default true for static scenes, false for non-static scenes
+     */
+    enableIdleDetection?: boolean;
+    /**
+     * Time in milliseconds before entering idle state
+     * @default 1000
+     */
+    idleDelay?: number;
+    /**
+     * Target frames per second
+     * @default 60
+     */
+    targetFPS?: number;
+    /**
+     * Enable frame rate limiting
+     * @default true
+     */
+    enableFrameRateLimiting?: boolean;
+}
+
+/** The partial options for a preset, or an empty object when none is set. */
+export declare function resolvePreset(preset?: ViewerPreset): Partial<SimpleViewerOptions>;
+
+/**
+ * Click-picking and hotspot-occlusion raycast options.
+ */
+export declare interface SelectionOptions {
+    /**
+     * Build a BVH (bounding volume hierarchy) for each loaded model, making
+     * raycasts logarithmic instead of linear — noticeable on high-poly models.
+     * Costs one synchronous build pass at load time (or on the first click for
+     * models passed as raw objects) and ~25% extra geometry memory. The build
+     * sorts each geometry's index in place (triangle order changes; rendering
+     * is unaffected) and adds an index to non-indexed geometry. Disable on
+     * memory-constrained targets or when the index order matters. Default on.
+     */
+    bvh?: boolean;
+}
+
+/**
+ * Public entry component for the viewer. Thin forwardRef pass-through to the
+ * clean-architecture SimpleViewer implementation.
+ */
+export declare const SimpleViewer: default_2.ForwardRefExoticComponent<SimpleViewerProps & default_2.RefAttributes<SimpleViewerHandle>>;
+
+/**
+ * Imperative handle exposed via `ref` on the `SimpleViewer` component. Lives in a
+ * dedicated type module (not the component file) so cross-cutting modules such as
+ * `events/ViewerEvents` can reference it without depending on a React component.
+ */
+export declare interface SimpleViewerHandle {
+    scene: THREE.Scene | null;
+    camera: THREE.Camera | null;
+    renderer: THREE.WebGLRenderer | null;
+    controls: ControlsInstance | null;
+    events: TypedEventEmitter<ViewerEventMap>;
+    loadModel: (source: string | THREE.Object3D) => Promise<void>;
+    /**
+     * Capture a PNG still of the current scene (data URL). Pass `width`/`height`
+     * for a high-resolution raster capture; in path-traced mode omit them — the
+     * still is taken at canvas resolution once the accumulation completes.
+     */
+    captureStill: (options?: CaptureStillOptions) => Promise<string>;
+    /**
+     * Record the live canvas for a few seconds (default 3) and resolve with the
+     * encoded clip — WebM in Chromium/Firefox, MP4 in Safari. Motion (turntable,
+     * animations, user orbiting) is captured as it happens.
+     */
+    captureVideo: (options?: CaptureVideoOptions) => Promise<Blob>;
+    /** Clip names of the loaded model, in file order (empty when none). */
+    getAnimationNames: () => string[];
+    /** Plays one clip by name, or ALL clips when no name is given (looped). */
+    playAnimations: (clipName?: string) => void;
+    /** Freezes playback on the current pose; playAnimations() resumes. */
+    pauseAnimations: () => void;
+    dispose: () => void;
+}
+
+export declare interface SimpleViewerOptions {
+    /**
+     * A one-word visual preset (`studio`, `product`, `neutral`, `dark`, `outdoor`)
+     * that sets a cohesive lighting/environment/tone look. Any other option you
+     * pass overrides the preset's values.
+     */
+    preset?: ViewerPreset;
+    backgroundColor?: string | number;
+    staticScene?: boolean;
+    /** GLTF animation playback (autoplay, speed). */
+    animations?: AnimationOptions;
+    camera?: CameraOptions;
+    controls?: ControlsOptions;
+    environment?: EnvironmentOptions;
+    helpers?: HelperOptions;
+    lighting?: LightingOptions;
+    pathTracing?: PathTracingOptions;
+    renderer?: RendererOptions;
+    rendering?: RenderingOptions;
+    onLoad?: () => void;
+    onProgress?: (progress: number) => void;
+    onError?: (error: Error) => void;
+    animationLoop?: ((time: number) => void) | null;
+    replaceWithScreenshotOnComplete?: boolean;
+    /**
+     * 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);
+     * an object customizes it. UI-only — changing it never rebuilds the viewer.
+     */
+    loadingIndicator?: boolean | LoadingIndicatorOptions;
+    /**
+     * Compression decoders for the glTF/GLB loader (DRACO, KTX2/Basis, Meshopt).
+     * All enabled by default so compressed assets load with no setup; pass this to
+     * disable a decoder or self-host the DRACO/KTX2 WebAssembly files offline.
+     */
+    loaders?: LoaderOptions;
+    /**
+     * Built-in UI chrome over the canvas (e.g. `ui: { presets: true }` for the
+     * live preset picker). All opt-in; UI-only — never rebuilds the viewer.
+     */
+    ui?: UIOptions;
+    /**
+     * Click-picking / hotspot-occlusion raycast tuning (e.g. `selection: { bvh:
+     * false }` to skip the load-time BVH build on memory-constrained targets).
+     */
+    selection?: SelectionOptions;
+}
+
+export declare interface SimpleViewerProps {
+    /**
+     * A URL to a glb/gltf file, or a Three.js object. The viewer takes
+     * OWNERSHIP of objects you pass: their geometries, materials and textures
+     * are disposed when the object is replaced or the viewer unmounts. Pass a
+     * `.clone()` if you need to keep using the original elsewhere.
+     */
+    object: THREE.Object3D | null | string;
+    options?: SimpleViewerOptions;
+    /**
+     * Shorthand for `options.preset` — a one-word look
+     * (`studio` / `product` / `neutral` / `dark` / `outdoor`).
+     * `options.preset` takes precedence if both are set.
+     */
+    preset?: ViewerPreset;
+    /**
+     * Shorthand for `options.pathTracing.enabled = true` — photoreal progressive
+     * path tracing (a construction-time render mode). Composes with a partial
+     * `options.pathTracing` (tuning fields are kept); an explicit
+     * `options.pathTracing.enabled` wins. Pair with `handle.captureStill()` for
+     * a photoreal still once the accumulation completes.
+     */
+    pathTraced?: boolean;
+    /**
+     * Shorthand for `options.controls.autoRotate = true` — a showcase turntable
+     * that slowly orbits the camera around the model. Toggling it never rebuilds
+     * the viewer (applied live), and rotation pauses automatically while the
+     * user is dragging. Speed is tuned via `options.controls.autoRotateSpeed`
+     * (2 ≈ one orbit per 30s). An explicit `options.controls.autoRotate` wins.
+     */
+    turntable?: boolean;
+    /**
+     * Shorthand for `options.animations.autoplay = true` — plays ALL of the
+     * model's animation clips, looped, as soon as it loads. Toggling is live
+     * (pause/resume without a rebuild). Pick a single clip or tune the speed
+     * via `options.animations`; an explicit `options.animations.autoplay` wins.
+     */
+    animations?: boolean;
+    /**
+     * Overlay children rendered inside the viewer container (over the canvas),
+     * e.g. `<Hotspot>` annotations.
+     */
+    children?: React_2.ReactNode;
+}
+
+export declare class ThreeViewerError extends Error {
+    readonly code: ErrorCode;
+    readonly context?: ErrorContext | undefined;
+    readonly timestamp: Date;
+    constructor(message: string, code: ErrorCode, context?: ErrorContext | undefined);
+    static fromError(error: unknown, code: ErrorCode, context?: ErrorContext): ThreeViewerError;
+}
+
+export declare class TypedEventEmitter<T> {
+    private listeners;
+    on<K extends keyof T>(event: K, listener: (data: T[K]) => void): () => void;
+    emit<K extends keyof T>(event: K, data: T[K]): void;
+    once<K extends keyof T>(event: K, listener: (data: T[K]) => void): () => void;
+    removeAllListeners(event?: keyof T): void;
+    listenerCount(event: keyof T): number;
+    /**
+     * Alias for removing a listener (compatible with Node.js EventEmitter)
+     */
+    off<K extends keyof T>(event: K, listener: (data: T[K]) => void): void;
+    /**
+     * Alias for on (compatible with Node.js EventEmitter)
+     */
+    removeListener<K extends keyof T>(event: K, listener: (data: T[K]) => void): void;
+}
+
+/**
+ * Built-in UI chrome rendered over the canvas. Everything here is opt-in and
+ * UI-only — toggling it never rebuilds the viewer or reloads the model.
+ */
+export declare interface UIOptions {
+    /**
+     * Show the built-in preset picker: a row of chips over the canvas that
+     * switches the visual preset live. Off by default. Turning the picker off
+     * also clears any preset picked through it — your own `preset` takes over.
+     */
+    presets?: boolean;
+    /**
+     * Called when the user picks a preset via the built-in picker, e.g. to
+     * persist the choice. A later change to your own `preset` prop/option
+     * overrides the picked one; echoing a reported pick back into `preset`
+     * (even asynchronously) is safe and never reverts a newer pick.
+     */
+    onPresetChange?: (preset: ViewerPreset) => void;
+}
+
+/** A plain, engine-agnostic 3D point. */
+declare interface Vec3Like {
+    x: number;
+    y: number;
+    z: number;
+}
+
+/**
+ * Visual presets: cohesive deltas layered over the defaults (deep-merged) so a
+ * model looks intentional on first paint. Each preset only sets **runtime** look
+ * fields — background color, tone-mapping exposure and environment intensity —
+ * so switching presets is applied live (no viewer rebuild, no model reload) and
+ * everything else (camera auto-framing, lighting rig, controls, grid) is
+ * inherited from the defaults. Explicit user options always win.
+ */
+export declare const VIEWER_PRESETS: Record<ViewerPreset, 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
+ * source of truth with the core map via the generic {@link GenericViewerEventMap}.
+ */
+export declare type ViewerEventMap = ViewerEventMap_2<THREE.Object3D, THREE.Camera, ControlsInstance, SimpleViewerHandle>;
+
+/**
+ * The viewer's event contract, generic over the layer-specific representations
+ * of a 3D object, camera, controls, and viewer handle. The engine-agnostic core
+ * instantiates it with its interfaces (`IObject3D`/`ICamera`/…); the public
+ * surface instantiates it with the concrete Three.js types. Keeping a single
+ * generic definition is what stops the two instantiations from drifting apart.
+ */
+declare interface ViewerEventMap_2<TObject, TCamera, TControls, THandle> {
+    'initialized': {
+        viewer: THandle;
+    };
+    'disposed': {
+        viewer: THandle;
+    };
+    'model:loading': {
+        url: string;
+    };
+    'model:loaded': {
+        model: TObject;
+        loadTime: number;
+    };
+    'model:error': {
+        error: ThreeViewerError;
+        url?: string;
+    };
+    'render:start': {
+        frame: number;
+    };
+    'render:complete': {
+        frame: number;
+        renderTime: number;
+        samples?: number;
+    };
+    'pathtracing:complete': {
+        samples: number;
+        totalTime: number;
+    };
+    'screenshot:captured': {
+        dataUrl: string;
+    };
+    'controls:change': {
+        type?: string;
+        camera?: TCamera;
+        controls?: TControls;
+    };
+    /** A click (not a drag) hit the loaded model; `point` is the world-space hit. */
+    'object:selected': {
+        object: TObject;
+        point: Vec3Like;
+    };
+    'error': {
+        error: ThreeViewerError;
+    };
+}
+
+/**
+ * A one-word visual preset that sets the background, tone-mapping exposure and
+ * environment intensity as a cohesive "look", so a model looks intentional on
+ * first paint with zero manual tuning. Set it on `SimpleViewerOptions.preset`
+ * (or the `preset` prop). Presets apply live, so switching one never rebuilds
+ * the viewer or reloads the model. Any explicit option you pass overrides it.
+ *
+ * - `studio`  — clean, neutral light-grey backdrop; the balanced default look.
+ * - `product` — bright, high-key white backdrop for e-commerce hero shots.
+ * - `neutral` — flat, even, low-drama lighting for accurate inspection.
+ * - `dark`    — dramatic dark backdrop for portfolios and glossy materials.
+ * - `outdoor` — brighter, daylight-leaning sky tint.
+ *
+ * Path-traced output is a construction-time render mode (`pathTracing.enabled`),
+ * not a live-switchable preset.
+ */
+export declare type ViewerPreset = 'studio' | 'product' | 'neutral' | 'dark' | 'outdoor';
+
+export { }