three-low-poly 0.9.22 → 0.9.24

package/dist/index.d.ts

@@ -2,13 +2,15 @@ import { BoxGeometry } from 'three';
 import { BufferGeometry } from 'three';
 import { Camera } from 'three';
 import { Color } from 'three';
+import { ColorRepresentation } from 'three';
 import { DataTexture } from 'three';
+import { DirectionalLight } from 'three';
 import { ExtrudeGeometry } from 'three';
 import { Group } from 'three';
 import { InstancedMesh } from 'three';
-import { Light } from 'three';
 import { Material } from 'three';
 import { Mesh } from 'three';
+import { MeshBasicMaterial } from 'three';
 import { MeshLambertMaterial } from 'three';
 import { MeshPhongMaterial } from 'three';
 import { MeshPhysicalMaterial } from 'three';
@@ -16,9 +18,13 @@ import { MeshStandardMaterial } from 'three';
 import { Object3D } from 'three';
 import { ParametricGeometry } from 'three-stdlib';
 import { PerspectiveCamera } from 'three';
+import { PlaneGeometry } from 'three';
+import { PointLight } from 'three';
+import { Points } from 'three';
 import { ShaderMaterial } from 'three';
 import { Shape } from 'three';
 import { SphereGeometry } from 'three';
+import * as THREE from 'three';
 import { Uniform } from 'three';
 import { Vector2 } from 'three';
 import { Vector3 } from 'three';
@@ -390,6 +396,31 @@ export declare class BifurcatedStaircaseGeometry extends BufferGeometry {
     constructor(stepWidth?: number, stepHeight?: number, stepDepth?: number, numStepsCentral?: number, numStepsBranch?: number, branchAngle?: number);
 }
 
+declare interface BloomTransitionOptions extends SceneTransitionFXOptions {
+    maxBloom?: number;
+}
+
+declare interface BlurTransitionOptions extends SceneTransitionFXOptions {
+    maxBlur?: number;
+    kernelSize?: number;
+}
+
+export declare const blurTransitionShader: {
+    uniforms: {
+        tDiffuse: {
+            value: null;
+        };
+        kernelSize: {
+            value: number;
+        };
+        resolution: {
+            value: null;
+        };
+    };
+    vertexShader: string;
+    fragmentShader: string;
+};
+
 export declare class Bone extends Mesh<BoneGeometry, MeshStandardMaterial> {
     constructor();
 }
@@ -472,31 +503,31 @@ export declare enum BoxSide {
     BACK = "back"
 }
 
-export declare class BubblingEffect extends InstancedMesh {
-    private bubblePositions;
-    private velocities;
-    private width;
-    private height;
-    private depth;
-    constructor(options?: BubblingEffectOptions);
-    /**
-     * Updates the position of a specific bubble instance in the InstancedMesh.
-     */
-    private updateInstanceMatrix;
-    /**
-     * Updates bubble positions, moving them upward and resetting them
-     * to the bottom if they reach the top.
-     */
-    update(): void;
+/**
+ * Single brick geometry for low-poly aesthetic.
+ * Default dimensions approximate standard brick proportions (in feet scale).
+ */
+export declare class BrickGeometry extends BufferGeometry {
+    constructor({ width, height, depth, }?: {
+        width?: number | undefined;
+        height?: number | undefined;
+        depth?: number | undefined;
+    });
 }
 
-export declare interface BubblingEffectOptions {
-    geometry?: BufferGeometry;
+export declare interface BrickWallOptions {
+    wallWidth?: number;
+    wallHeight?: number;
+    brickWidth?: number;
+    brickHeight?: number;
+    brickDepth?: number;
+    mortarGap?: number;
+    offsetPattern?: boolean;
+    brickColors?: number[];
+    colorVariation?: boolean;
+    positionVariation?: number;
+    rotationVariation?: number;
     material?: Material;
-    count?: number;
-    height?: number;
-    width?: number;
-    depth?: number;
 }
 
 export declare class BunsenBurner extends Group {
@@ -644,6 +675,87 @@ export declare function cameraPendulumAnimation(camera: Camera, center: Vector3,
  */
 export declare function cameraSpiralAscensionAnimation(camera: Camera, center: Vector3, radius: number, height: number, revolutions: number, duration: number, onComplete?: () => void): void;
 
+/**
+ * CameraTransition provides smooth animated transitions between perspective and orthographic cameras.
+ *
+ * The transition works by rendering both camera views to separate render targets and blending between them.
+ * This provides a true, accurate transition between the two camera types.
+ *
+ * @example
+ * ```typescript
+ * const transition = new CameraTransition(
+ *   perspectiveCamera,
+ *   orthographicCamera,
+ *   renderer
+ * );
+ *
+ * transition.transitionTo(orthographicCamera, {
+ *   duration: 1000,
+ *   easing: 'easeInOutCubic'
+ * });
+ * ```
+ */
+export declare class CameraTransition {
+    private perspectiveCamera;
+    private orthographicCamera;
+    private renderer;
+    private scene;
+    private currentCamera;
+    private targetCamera;
+    private transitionProgress;
+    private transitionDuration;
+    private transitionStartTime;
+    private isTransitioning;
+    private easingFunction;
+    private renderTargetA;
+    private renderTargetB;
+    private blendScene;
+    private blendCamera;
+    private blendMaterial;
+    private onUpdateCallback?;
+    private onCompleteCallback?;
+    constructor(perspectiveCamera: THREE.PerspectiveCamera, orthographicCamera: THREE.OrthographicCamera, renderer: THREE.WebGLRenderer);
+    /**
+     * Start a transition to the target camera
+     */
+    transitionTo(targetCamera: THREE.PerspectiveCamera | THREE.OrthographicCamera, options?: CameraTransitionOptions): void;
+    /**
+     * Update the transition. Call this in your render loop.
+     */
+    update(scene: THREE.Scene): THREE.Camera;
+    /**
+     * Render the scene with camera transition blending
+     */
+    render(scene: THREE.Scene): void;
+    /**
+     * Get the current active camera
+     */
+    getCurrentCamera(): THREE.Camera;
+    /**
+     * Check if a transition is currently in progress
+     */
+    getIsTransitioning(): boolean;
+    /**
+     * Get the current transition progress (0-1)
+     */
+    getProgress(): number;
+    /**
+     * Resize the render targets when the renderer size changes
+     */
+    setSize(width: number, height: number): void;
+    /**
+     * Dispose of resources
+     */
+    dispose(): void;
+}
+
+export declare interface CameraTransitionOptions {
+    duration?: number;
+    easing?: EasingFunction | keyof typeof Easing;
+    onUpdate?: (progress: number) => void;
+    onComplete?: () => void;
+}
+
 /**
  * Add a slight random wobble for intensity or realism (e.g., during an explosion).
  *
@@ -775,12 +887,6 @@ export declare function centerObjectGeometry<T extends Object3D>(object: T, targ
  */
 export declare const checkerboardTexture: (size: number) => DataTexture;
 
-export declare const circularEaseIn: (t: number) => number;
-
-export declare const circularEaseInOut: (t: number) => number;
-
-export declare const circularEaseOut: (t: number) => number;
-
 export declare const ColorPalette: {
     CADMIUM_RED: number;
     CARDINAL_RED: number;
@@ -853,9 +959,21 @@ export declare const ColorPalette: {
     TITANIUM_WHITE: number;
 };
 
-export declare const concave: (t: number) => number;
-
-export declare const convex: (t: number) => number;
+/**
+ * Creates an instanced mesh brick wall with running bond pattern.
+ *
+ * @example
+ * ```ts
+ * const wall = createBrickWall({
+ *   wallWidth: 10,
+ *   wallHeight: 8,
+ *   brickColors: [0x8b4513, 0xa0522d, 0x6b3410],
+ *   colorVariation: true
+ * });
+ * scene.add(wall);
+ * ```
+ */
+export declare function createBrickWall({ wallWidth, wallHeight, brickWidth, brickHeight, brickDepth, mortarGap, offsetPattern, brickColors, colorVariation, positionVariation, rotationVariation, material, }?: BrickWallOptions): InstancedMesh;
 
 /**
  * Function to create cubic Bezier curve points
@@ -1071,6 +1189,22 @@ export declare const createQuadraticCurvePoints: (start: Vector2, control: Vecto
  */
 export declare const createSigmoidCurvePoints: (start: Vector2, end: Vector2, a: number, segments?: number) => Vector2[];
 
+export declare const crossfadeShader: {
+    uniforms: {
+        tDiffuseA: {
+            value: null;
+        };
+        tDiffuseB: {
+            value: null;
+        };
+        mixRatio: {
+            value: number;
+        };
+    };
+    vertexShader: string;
+    fragmentShader: string;
+};
+
 export declare class CrossHeadstone extends Mesh<CrossHeadstoneGeometry, MeshStandardMaterial> {
     constructor({ width, height, depth, }?: CrossHeadstoneOptions);
 }
@@ -1085,14 +1219,6 @@ declare interface CrossHeadstoneOptions {
     depth?: number;
 }
 
-export declare const cubicCurve: (t: number, p0: number, p1: number, p2: number, p3: number) => number;
-
-export declare const cubicEaseIn: (t: number) => number;
-
-export declare const cubicEaseInOut: (t: number) => number;
-
-export declare const cubicEaseOut: (t: number) => number;
-
 /**
  * Cubic UV Mapping
  * Applies a texture by projecting UVs along each face of a cube.
@@ -1132,8 +1258,6 @@ export declare function cubicUVMappingBatch(vertices: [number, number, number][]
  */
 export declare function cylindricalUVMapping(vertices: [number, number, number][]): [number, number][];
 
-export declare const dampedCurve: (t: number, damping?: number) => number;
-
 export declare class DaySkybox extends Mesh {
     geometry: BoxGeometry;
     material: ShaderMaterial & {
@@ -1310,39 +1434,151 @@ export declare const displacementBrush: <T extends BufferGeometry>(geometry: T,
 
 /**
  * Easing functions for interpolating values over time.
+ *
+ * Use these functions to create smooth animations and transitions.
+ * All easing functions take a value t between 0 and 1 and return an eased value between 0 and 1.
+ *
+ * @example
+ * ```typescript
+ * import { Easing } from 'three-low-poly';
+ *
+ * // Using with transitions (namespace)
+ * cameraTransition.transitionTo(camera, {
+ *   duration: 1000,
+ *   easing: Easing.cubicInOut  // Function reference
+ * });
+ *
+ * // Or using string reference
+ * cameraTransition.transitionTo(camera, {
+ *   duration: 1000,
+ *   easing: 'cubicInOut'  // String reference
+ * });
+ *
+ * // Using the function directly in custom animation
+ * const progress = 0.5;
+ * const easedValue = Easing.cubicInOut(progress);
+ *
+ * // Custom animation loop
+ * const startValue = 0;
+ * const endValue = 100;
+ * const t = elapsedTime / duration;
+ * const easedT = Easing.sineInOut(t);
+ * const currentValue = startValue + (endValue - startValue) * easedT;
+ * ```
  */
 export declare const Easing: {
-    SINE_EASE_IN: (t: number) => number;
-    SINE_EASE_OUT: (t: number) => number;
-    SINE_EASE_IN_OUT: (t: number) => number;
-    QUADRATIC_EASE_IN: (t: number) => number;
-    QUADRATIC_EASE_OUT: (t: number) => number;
-    QUADRATIC_EASE_IN_OUT: (t: number) => number;
-    CUBIC_EASE_IN: (t: number) => number;
-    CUBIC_EASE_OUT: (t: number) => number;
-    CUBIC_EASE_IN_OUT: (t: number) => number;
-    QUARTIC_EASE_IN: (t: number) => number;
-    QUARTIC_EASE_OUT: (t: number) => number;
-    QUARTIC_EASE_IN_OUT: (t: number) => number;
-    QUINTIC_EASE_IN: (t: number) => number;
-    QUINTIC_EASE_OUT: (t: number) => number;
-    QUINTIC_EASE_IN_OUT: (t: number) => number;
-    EXPONENTIAL_EASE_IN: (t: number) => number;
-    EXPONENTIAL_EASE_OUT: (t: number) => number;
-    EXPONENTIAL_EASE_IN_OUT: (t: number) => number;
-    CIRCULAR_EASE_IN: (t: number) => number;
-    CIRCULAR_EASE_OUT: (t: number) => number;
-    CIRCULAR_EASE_IN_OUT: (t: number) => number;
-    LINEAR: (t: number) => number;
-    SMOOTHSTEP: (t: number) => number;
-    CONCAVE: (t: number) => number;
-    CONVEX: (t: number) => number;
-    LOGARITHMIC: (t: number) => number;
-    SQUARE_ROOT: (t: number) => number;
-    INVERSE: (t: number) => number;
-    GAUSSIAN: (t: number) => number;
+    sineIn: (t: number) => number;
+    sineOut: (t: number) => number;
+    sineInOut: (t: number) => number;
+    quadIn: (t: number) => number;
+    quadOut: (t: number) => number;
+    quadInOut: (t: number) => number;
+    cubicIn: (t: number) => number;
+    cubicOut: (t: number) => number;
+    cubicInOut: (t: number) => number;
+    quartIn: (t: number) => number;
+    quartOut: (t: number) => number;
+    quartInOut: (t: number) => number;
+    quintIn: (t: number) => number;
+    quintOut: (t: number) => number;
+    quintInOut: (t: number) => number;
+    expoIn: (t: number) => number;
+    expoOut: (t: number) => number;
+    expoInOut: (t: number) => number;
+    circIn: (t: number) => number;
+    circOut: (t: number) => number;
+    circInOut: (t: number) => number;
+    linear: (t: number) => number;
+    smoothstep: (t: number) => number;
+    concave: (t: number) => number;
+    convex: (t: number) => number;
+    logarithmic: (t: number) => number;
+    squareRoot: (t: number) => number;
+    inverse: (t: number) => number;
+    gaussian: (t: number) => number;
 };
 
+/**
+ * Easing function type for interpolating values over time.
+ * @param t - Progress value between 0 and 1
+ * @returns Eased value between 0 and 1
+ */
+export declare type EasingFunction = (t: number) => number;
+
+/**
+ * Carbonation bubbles rising through a bounded volume — seltzer, soda, or
+ * brewing liquid. Each instance drifts upward at its own speed and respawns
+ * near {@link EffervescenceEffectOptions.baseY} after reaching the top.
+ *
+ * Spawn positions use a square footprint (`width` × `depth`). {@link EffervescenceEffectOptions.spread}
+ * pulls that box inward so round jars do not get occasional corner outliers.
+ * Position and scale the effect to sit inside a jar, flask, or panel viewport.
+ * Call {@link EffervescenceEffect.update} each frame with elapsed time in seconds.
+ *
+ * @example
+ * ```typescript
+ * const fizz = new EffervescenceEffect({ width: 1.2, height: 2.5, count: 30 });
+ * fizz.position.set(0, 1.2, 0);
+ * scene.add(fizz);
+ *
+ * onFrame((dt) => fizz.update(dt));
+ * ```
+ */
+export declare class EffervescenceEffect extends InstancedMesh {
+    private readonly width;
+    private readonly height;
+    private readonly depth;
+    private readonly baseY;
+    private readonly spread;
+    private readonly px;
+    private readonly py;
+    private readonly pz;
+    private readonly speed;
+    private readonly dummy;
+    constructor(options?: EffervescenceEffectOptions);
+    /**
+     * Advance bubble positions. Pass elapsed frame time in seconds (e.g. from
+     * `createScene`'s `onFrame` callback).
+     */
+    update(dt: number): void;
+    /** Release geometry and materials held by the field. */
+    dispose(): this;
+    private respawn;
+    private writeMatrices;
+}
+
+export declare interface EffervescenceEffectOptions {
+    /** Override bubble geometry. Defaults to a small `SphereGeometry`. */
+    geometry?: BufferGeometry;
+    /** Override the default bubble material. */
+    material?: Material;
+    /** Number of bubble instances. Defaults to `24`. */
+    count?: number;
+    /** Horizontal spread (world units). Defaults to `1.5`. */
+    width?: number;
+    /** Vertical column height (world units). Defaults to `3`. */
+    height?: number;
+    /** Depth spread (world units). Defaults to `1.5`. */
+    depth?: number;
+    /**
+     * Horizontal spawn inset (0–1). Scales width/depth spawn area inward so a
+     * square volume fits round vessels. `1` = full box; `0.88` (default) trims corners.
+     */
+    spread?: number;
+    /** World Y where bubbles spawn when they recycle. Defaults to `0`. */
+    baseY?: number;
+    /** Minimum rise speed (units/s). Defaults to `0.35`. */
+    speedMin?: number;
+    /** Maximum rise speed (units/s). Defaults to `0.85`. */
+    speedMax?: number;
+    /** Bubble tint when using the default material. Defaults to `0xffffff`. */
+    color?: ColorRepresentation;
+    /** Default material opacity. Defaults to `0.6`. */
+    opacity?: number;
+    /** Default material emissive intensity. Defaults to `0`. */
+    emissiveIntensity?: number;
+}
+
 export declare class ElectricPanel extends Group {
     constructor();
 }
@@ -1352,52 +1588,55 @@ export declare class EllipticLeafGeometry extends BufferGeometry {
 }
 
 /**
- * Emissive pulse animation, producing a flickering light effect for materials that have emissive properties.
- * The emissive intensity of the material will oscillate between `minIntensity` and `maxIntensity`.
+ * Smooth emissive pulse for fake LEDs — animates `emissiveIntensity` on an existing
+ * mesh material without adding geometry or scene lights.
  *
- * Oscillation time = 2π / speed
- *  - Low speed values (e.g., 0.5) will result in a slow pulse
- *  - High speed values (e.g., 10) will result in a rapid flicker
+ * Pair with a prefab such as {@link PanelLight}: place the mesh, pass its material
+ * here, call `update(dt)` each frame. For a bank of same-color LEDs, give each
+ * instance a different `speed` so they breathe out of sync.
  *
- *  Requires `update()` frame handler with `clock.getElapsedTime()` for animation.
- *
- *  Example usage:
- *  ```
- *  const pulseAnimation = new EmissivePulseAnimation();
- *  const clock = new THREE.Clock();
+ * @example
+ * ```ts
+ * const led = new PanelLight({ emissive: 0xff0000 });
+ * scene.add(led);
+ *
+ * const pulse = new EmissivePulseEffect({
+ *   material: led.material,
+ *   speed: 1.4,
+ *   minIntensity: 0.05,
+ *   maxIntensity: 2,
+ * });
  *
- *  function animate() {
- *    pulseAnimation.update(clock.getElapsedTime());
- *  }
- *  ```
+ * onFrame((dt) => pulse.update(dt));
+ * ```
  */
-export declare class EmissivePulseAnimation {
+export declare class EmissivePulseEffect {
     speed: number;
-    maxIntensity: number;
     minIntensity: number;
-    material: MeshStandardMaterial | MeshPhysicalMaterial | MeshLambertMaterial | MeshPhongMaterial;
-    constructor(options: EmissivePulseEffectOptions);
-    /**
-     * Update the emissive intensity of the material.
-     *
-     * Use Three.Clock getElapsedTime()
-     *
-     * Example:
-     * ```
-     * const clock = new THREE.Clock();
-     * effect.update(clock.getElapsedTime());
-     * ```
-     */
-    update(elapsedTime?: number): void;
+    maxIntensity: number;
+    readonly material: EmissivePulseMaterial;
+    private elapsed;
+    constructor({ material, speed, maxIntensity, minIntensity, }: EmissivePulseEffectOptions);
+    /** Advance the pulse by `dt` seconds (elapsed time, not frame index). */
+    update(dt: number): void;
 }
 
 export declare interface EmissivePulseEffectOptions {
+    /** Material whose `emissiveIntensity` will oscillate. Must have emissive set. */
+    material: EmissivePulseMaterial;
+    /**
+     * Pulse frequency in radians per second (`abs(sin(elapsed * speed))`).
+     * Defaults to `2`. Primary differentiator when many LEDs share one color.
+     */
     speed?: number;
-    maxIntensity?: number;
+    /** Lower bound of the pulse. Defaults to `0.2`. */
     minIntensity?: number;
-    material: MeshStandardMaterial | MeshPhysicalMaterial | MeshLambertMaterial | MeshPhongMaterial;
+    /** Upper bound of the pulse. Defaults to `0.8`. */
+    maxIntensity?: number;
 }
 
+export declare type EmissivePulseMaterial = MeshStandardMaterial | MeshPhysicalMaterial | MeshLambertMaterial | MeshPhongMaterial;
+
 export declare class ErlenmeyerFlask extends Mesh<ErlenmeyerFlaskGeometry, MeshPhysicalMaterial> {
     constructor({ flaskRadius, //
         neckRadius, height, neckHeight, radialSegments, }?: {
@@ -1420,40 +1659,64 @@ export declare class ErlenmeyerFlaskGeometry extends BufferGeometry {
     });
 }
 
-export declare const exponentialCurve: (t: number, base?: number, factor?: number) => number;
-
-export declare const exponentialEaseIn: (t: number) => number;
+export declare const fadeShader: {
+    uniforms: {
+        tDiffuse: {
+            value: null;
+        };
+        fadeAmount: {
+            value: number;
+        };
+        fadeColor: {
+            value: null;
+        };
+    };
+    vertexShader: string;
+    fragmentShader: string;
+};
 
-export declare const exponentialEaseInOut: (t: number) => number;
+declare interface FadeTransitionOptions extends SceneTransitionOptions {
+    color?: THREE.ColorRepresentation;
+}
 
-export declare const exponentialEaseOut: (t: number) => number;
+declare interface FadeTransitionOptions_2 extends SceneTransitionFXOptions {
+    color?: THREE.ColorRepresentation;
+}
 
-export declare const fadeShader: {
+export declare const fadeTransitionSceneShader: {
     uniforms: {
-        tDiffuse: {
+        tDiffuseA: {
             value: null;
         };
-        opacity: {
+        tDiffuseB: {
+            value: null;
+        };
+        mixRatio: {
             value: number;
         };
+        fadeColor: {
+            value: null;
+        };
     };
     vertexShader: string;
     fragmentShader: string;
 };
 
 export declare const Falloff: {
-    LINEAR: (distance: number, radius: number) => number;
-    QUADRATIC: (distance: number, radius: number) => number;
-    SQUARE_ROOT: (distance: number, radius: number) => number;
-    LOGARITHMIC: (distance: number, radius: number) => number;
-    SINE: (distance: number, radius: number) => number;
-    EXPONENTIAL: (distance: number, radius: number) => number;
-    CUBIC: (distance: number, radius: number) => number;
-    GAUSSIAN: (distance: number, radius: number) => number;
-    INVERSE: (distance: number, radius: number) => number;
-    SMOOTHSTEP: (distance: number, radius: number) => number;
+    linear: (distance: number, radius: number) => number;
+    quadratic: (distance: number, radius: number) => number;
+    squareRoot: (distance: number, radius: number) => number;
+    logarithmic: (distance: number, radius: number) => number;
+    sine: (distance: number, radius: number) => number;
+    exponential: (distance: number, radius: number) => number;
+    cubic: (distance: number, radius: number) => number;
+    gaussian: (distance: number, radius: number) => number;
+    inverse: (distance: number, radius: number) => number;
+    smoothstep: (distance: number, radius: number) => number;
 };
 
+export declare type FalloffFunction = (distance: number, radius: number) => number;
+
 export declare function findClosestColor(inputColor: number, dataset: number[]): number | null;
 
 export declare function findClosestColorChannelWise(inputColor: number, dataset: number[]): number | null;
@@ -1478,6 +1741,53 @@ export declare class Flame extends Mesh<FlameGeometry, MeshStandardMaterial> {
     });
 }
 
+/**
+ * Calm flame flicker from detuned sines — drives optional real lights, flame
+ * materials, and {@link GlowHalo} opacity in sync. Time-based (`update(dt)`).
+ *
+ * Use without a `light` for mass candlefields (halo + bloom only). Add a
+ * `light` for hero sconces that must cast on walls and props.
+ */
+export declare class FlameFlickerEffect {
+    readonly seed: number;
+    light?: PointLight;
+    lightIntensity: number;
+    flame?: MeshBasicMaterial;
+    halo?: GlowHalo;
+    haloOpacity: number;
+    private readonly flameColor;
+    private elapsed;
+    constructor({ seed, light, lightIntensity, flame, flameColor, halo, haloOpacity, }?: FlameFlickerEffectOptions);
+    /**
+     * Flicker factor at elapsed time — lazy sum of detuned sines (~0.5–1.1).
+     */
+    static factor(elapsed: number, seed: number): number;
+    /** Current flicker factor after the last `update`. */
+    get level(): number;
+    update(dt: number): void;
+    /** Billboard linked halo toward the eye, if present. */
+    faceCamera(eye: Vector3): void;
+}
+
+export declare interface FlameFlickerEffectOptions {
+    /**
+     * Desyncs multiple instances. Defaults to `Math.random() * 100`.
+     */
+    seed?: number;
+    /** Optional real light — use sparingly; casts on geometry but counts against light limits. */
+    light?: PointLight;
+    /** Base intensity when `light` is set. Defaults to `4`. */
+    lightIntensity?: number;
+    /** Optional flame core material (e.g. `MeshBasicMaterial` on a small sphere). */
+    flame?: MeshBasicMaterial;
+    /** Flame tint when `flame` is set. Defaults to `0xffaa44`. */
+    flameColor?: ColorRepresentation;
+    /** Optional {@link GlowHalo}; opacity scales with the flicker factor. */
+    halo?: GlowHalo;
+    /** Halo opacity multiplier at flicker peak. Defaults to `0.75`. */
+    haloOpacity?: number;
+}
+
 export declare class FlameGeometry extends ParametricGeometry {
     constructor({ height, radius, segmentsU, segmentsV }?: {
         height?: number | undefined;
@@ -1500,8 +1810,6 @@ export declare class FlorenceFlaskGeometry extends BufferGeometry {
     constructor();
 }
 
-export declare const gaussian: (t: number) => number;
-
 export declare class Gear extends Mesh {
     constructor({ sides, innerRadius, outerRadius, holeSides, holeRadius, depth }?: {
         sides?: number | undefined;
@@ -1534,6 +1842,91 @@ export declare class GearShape extends Shape {
  */
 export declare function getAnalogousColors(baseHue: number): [number, number, number];
 
+declare interface GlitchTransitionOptions extends SceneTransitionFXOptions {
+    maxIntensity?: number;
+}
+
+/**
+ * Soft additive glow billboard — reads as light without a {@link PointLight}.
+ * Pair with {@link FlameFlickerEffect} for organic pulse, or use alone for
+ * cheap mass lighting (many halos + bloom, no light-count limit).
+ *
+ * Call `faceCamera(camera.position)` each frame so the card faces the eye.
+ */
+export declare class GlowHalo extends Object3D {
+    readonly mesh: Mesh<PlaneGeometry, MeshBasicMaterial>;
+    private texture;
+    private readonly baseColor;
+    constructor({ color, size, opacity, }?: GlowHaloOptions);
+    /** Billboard toward the camera (or any eye position). */
+    faceCamera(eye: Vector3): void;
+    /** Set halo opacity (e.g. scaled each frame by {@link FlameFlickerEffect}). */
+    setOpacity(opacity: number): void;
+    get opacity(): number;
+    setColor(color: ColorRepresentation): void;
+    dispose(): void;
+}
+
+export declare interface GlowHaloOptions {
+    /** Warm glow tint. Defaults to `0xffaa44`. */
+    color?: ColorRepresentation;
+    /** Billboard plane edge length in world units. Defaults to `1.2`. */
+    size?: number;
+    /** Base opacity before flicker scaling. Defaults to `0.75`. */
+    opacity?: number;
+}
+
+/**
+ * Creeping ground mist — soft horizontal cards drifting above the floor.
+ * Interior patches wrap toroidally within `area`; optional perimeter patches
+ * sit on/outside the fence on edges opposite the camera. One texture, one
+ * `update(dt)` — perimeter is placement logic, not a separate effect.
+ */
+export declare class GroundFogEffect extends Object3D {
+    private readonly patches;
+    private readonly area;
+    private readonly heightAt;
+    private readonly texture;
+    private elapsed;
+    constructor({ count, area, perimeterCount, plotHalf, terrainHalf, cameraFacing, color, heightAt, }?: GroundFogEffectOptions);
+    update(dt: number): void;
+    dispose(): void;
+    private makeInteriorPatch;
+    private makePerimeterPatch;
+    private makeMesh;
+}
+
+export declare interface GroundFogEffectOptions {
+    /** Interior mist cards scattered across the plot. Defaults to `14`. */
+    count?: number;
+    /** Half-extent of the interior scatter (world units). Defaults to `16`. */
+    area?: number;
+    /**
+     * Large cards hugging the plot perimeter — softens terrain cutoffs on the
+     * horizons opposite the camera. Defaults to `0` (interior only).
+     */
+    perimeterCount?: number;
+    /** Half-extent of the inner bounded plot (fence, wall, diorama edge, etc.). Defaults to `12`. */
+    plotHalf?: number;
+    /** Terrain half-extent; perimeter cards spill outward toward this edge. Defaults to `16`. */
+    terrainHalf?: number;
+    /**
+     * Horizontal direction from plot center toward the camera. Perimeter patches
+     * concentrate on the opposite edges. Defaults to `{ x: 1, z: 1 }`.
+     */
+    cameraFacing?: {
+        x: number;
+        z: number;
+    };
+    /** Mist tint. Defaults to `#9fb0c8`. */
+    color?: ColorRepresentation;
+    /**
+     * Sample ground height at world (x, z). Defaults to flat `y = 0`.
+     * Portfolio graveyard uses undulating terrain via the same callback.
+     */
+    heightAt?: (x: number, z: number) => number;
+}
+
 export declare class Heart extends Mesh {
     constructor({ size, width, height, tipDepth, depth }?: {
         size?: number | undefined;
@@ -1651,8 +2044,6 @@ export declare function hslToRgb(h: number, s: number, l: number): [number, numb
  */
 export declare function interpolateCurve(curveFunction: (t: number) => number, startRadius: number, endRadius: number, startHeight: number, endHeight: number, segments?: number, min?: number, max?: number): Vector2[];
 
-export declare const inverse: (t: number) => number;
-
 /**
  * Material indices
  * 0. Jar
@@ -1675,136 +2066,72 @@ export declare class Lantern extends Group {
     constructor(height?: number, baseWidth?: number);
 }
 
-export declare class LeafEffect extends InstancedMesh {
-    private dummyMatrix;
-    private velocities;
-    private width;
-    private height;
-    private depth;
-    constructor(options?: LeafEffectOptions);
-    update(): void;
-}
-
-export declare interface LeafEffectOptions {
-    geometry?: BufferGeometry;
-    material?: Material;
-    count?: number;
-    width?: number;
-    height?: number;
-    depth?: number;
-}
-
 export declare class LeverPanel extends Group {
     constructor();
 }
 
 /**
- * Create a light flicker animation that will randomly change the intensity and position of a light.
- * Effect resembles a flickering flame of candlelight.
- *
- * Example usage:
- * ```
- *    // Create a candle
- *    const candle = new Candle({
- *      height: 1,
- *      flameHeight: 0.25,
- *    });
- *    scene.add(candle);
- *
- *    // Create a point light
- *    const candleLight = new THREE.PointLight(0xffa500, 1, 5);
- *    scene.add(candleLight);
- *
- *    // Apply the animator to the light
- *    const lightAnimation = new LightFlickerAnimation({
- *      light: candleLight,
- *      maxIntensity: 2.2,
- *      x: candle.position.x,
- *      y: candle.position.y + 1 + 0.125, // height + half flame height
- *      z: candle.position.z,
- *    });
- *    animations.push(lightAnimation);
- *
- *    // Update the light animation in the render loop
- *    renderer.setAnimationLoop(() => {
- *      lightAnimation.update();
- *    });
- * ```
- */
-export declare class LightFlickerAnimation {
-    private light?;
-    minIntensity: number;
-    maxIntensity: number;
-    x: number;
-    y: number;
-    z: number;
-    jitterX: number;
-    jitterY: number;
-    jitterZ: number;
-    constructor({ light, minIntensity, maxIntensity, x, y, z, jitterX, jitterY, jitterZ, }?: Partial<LightFlickerAnimationOptions>);
-    update(): void;
-}
-
-export declare interface LightFlickerAnimationOptions {
-    light?: Light;
-    minIntensity: number;
-    maxIntensity: number;
-    x: number;
-    y: number;
-    z: number;
-    jitterX: number;
-    jitterY: number;
-    jitterZ: number;
-}
-
-/**
- * A lightning animation that can be used to simulate a lightning storm.
- * This effect is applied to a light source.
+ * Thunderstorm lightning that drives a {@link DirectionalLight} each frame.
  *
- * Example usage:
- * ```
- * const lightning = new THREE.DirectionalLight(0xffffff, 0);
- * scene.add(lightning);
- * lightning.position.set(5, 10, -5);
+ * Rather than scheduling timeouts (which need careful teardown), each strike
+ * enqueues two or three decaying intensity spikes a few frames apart — the
+ * characteristic stutter of real lightning. Read {@link LightningEffect.level}
+ * after {@link LightningEffect.update} to sync fog, sky, rain, or emissive
+ * surfaces with the flash.
  *
- * const lightningAnimation = new LightningAnimation();
- *
- * setRandomInterval(() => {
- *   lightningEffect.triggerLightning();
- * }, 250, 1250);
+ * @example
+ * ```typescript
+ * const bolt = new DirectionalLight(0xcdd8ff, 0);
+ * bolt.position.set(5, 12, -8);
+ * bolt.target.position.set(0, 0, 0);
+ * scene.add(bolt, bolt.target);
+ *
+ * const storm = new LightningEffect({ light: bolt, peak: 12, minGap: 3, maxGap: 9 });
+ *
+ * function animate(delta: number) {
+ *   storm.update(delta);
+ *   const flash = storm.level; // 0..~1.2
+ *   renderer.render(scene, camera);
+ * }
  * ```
  */
-export declare class LightningAnimation {
-    private light?;
-    minIntensity: number;
-    maxIntensity: number;
-    minDuration: number;
-    maxDuration: number;
-    constructor({ light, //
-        minIntensity, maxIntensity, minDuration, maxDuration, }?: LightningEffectOptions);
-    triggerLightning(): void;
-    update(): void;
+export declare class LightningEffect {
+    /** Current flash level, 0 = dark. Read after each {@link LightningEffect.update}. */
+    level: number;
+    private readonly light;
+    private readonly peak;
+    private readonly minGap;
+    private readonly maxGap;
+    private readonly spikes;
+    private clock;
+    private nextStrike;
+    constructor({ light, peak, minGap, maxGap }: LightningEffectOptions);
+    /**
+     * Advance the strike schedule and update the driven light intensity. Pass
+     * elapsed frame time in seconds.
+     */
+    update(dt: number): void;
+    /** Force the driven light dark, e.g. when lightning is toggled off. */
+    quiet(): void;
+    private strike;
 }
 
-declare interface LightningEffectOptions {
-    light?: Light;
-    minIntensity?: number;
-    maxIntensity?: number;
-    minDuration?: number;
-    maxDuration?: number;
+export declare interface LightningEffectOptions {
+    /** Directional light driven by lightning flashes. Start at intensity `0`. */
+    light: DirectionalLight;
+    /** Peak light intensity at full flash. Defaults to `12`. */
+    peak?: number;
+    /** Minimum seconds between strikes. Defaults to `3`. */
+    minGap?: number;
+    /** Maximum seconds between strikes. Defaults to `9`. */
+    maxGap?: number;
 }
 
-export declare const linear: (t: number) => number;
-
 export declare const LineEquations: {
     calculateXFromSlopeIntercept: typeof calculateXFromSlopeIntercept;
     calculateYFromSlopeIntercept: typeof calculateYFromSlopeIntercept;
 };
 
-export declare const logarithmic: (t: number) => number;
-
-export declare const logarithmicCurve: (t: number, base?: number, factor?: number) => number;
-
 /**
  * Generates a random number skewed towards the maximum value.
  *
@@ -2096,8 +2423,6 @@ export declare interface PanelOptions {
     depth?: number;
 }
 
-export declare const parabolicCurve: (t: number, a?: number, b?: number, c?: number) => number;
-
 /**
  * Prismatic parallelogram, with horizontal skew (offset in X for the slant).
  */
@@ -2106,14 +2431,14 @@ export declare class ParallelogramBoxGeometry extends BufferGeometry {
 }
 
 export declare const ParametricCurve: {
-    CUBIC: (t: number, p0: number, p1: number, p2: number, p3: number) => number;
-    DAMPED: (t: number, damping?: number) => number;
-    EXPONENTIAL: (t: number, base?: number, factor?: number) => number;
-    LOGARITHMIC: (t: number, base?: number, factor?: number) => number;
-    PARABOLIC: (t: number, a?: number, b?: number, c?: number) => number;
-    QUADRATIC: (t: number, p0: number, p1: number, p2: number) => number;
-    SIGMOID: (t: number, a?: number) => number;
-    SINUSOIDAL: (t: number) => number;
+    cubic: (t: number, p0: number, p1: number, p2: number, p3: number) => number;
+    damped: (t: number, damping?: number) => number;
+    exponential: (t: number, base?: number, factor?: number) => number;
+    logarithmic: (t: number, base?: number, factor?: number) => number;
+    parabolic: (t: number, a?: number, b?: number, c?: number) => number;
+    quadratic: (t: number, p0: number, p1: number, p2: number) => number;
+    sigmoid: (t: number, a?: number) => number;
+    sinusoidal: (t: number) => number;
 };
 
 export declare const ParametricCurveUtils: {
@@ -2131,6 +2456,86 @@ export declare const ParametricCurveUtils: {
  */
 export declare function parseHexCode(hex: string): [number, number, number];
 
+/**
+ * Soft, slow-drifting petals (or leaves) falling through a bounded volume —
+ * cherry-blossom float rather than stiff tumble. Each instance drifts downward
+ * with gentle horizontal wander and a light sinusoidal flutter.
+ *
+ * Call {@link PetalDriftEffect.update} each frame with elapsed time in seconds.
+ *
+ * @example
+ * ```typescript
+ * const petals = new PetalDriftEffect({
+ *   count: 80,
+ *   color: [0xffd6f0, 0xfff0f8, 0xf8c8e0],
+ *   flutter: 0.3,
+ * });
+ * scene.add(petals);
+ *
+ * onFrame((dt) => petals.update(dt));
+ * ```
+ */
+export declare class PetalDriftEffect extends InstancedMesh {
+    private readonly width;
+    private readonly height;
+    private readonly depth;
+    private readonly floorY;
+    private readonly flutter;
+    private readonly px;
+    private readonly py;
+    private readonly pz;
+    private readonly fallSpeed;
+    private readonly driftX;
+    private readonly driftZ;
+    private readonly rotX;
+    private readonly rotY;
+    private readonly rotZ;
+    private readonly phase;
+    private readonly dummy;
+    private clock;
+    constructor(options?: PetalDriftEffectOptions);
+    /**
+     * Advance petal positions and flutter. Pass elapsed frame time in seconds.
+     */
+    update(dt: number): void;
+    /** Release geometry and materials held by the field. */
+    dispose(): this;
+    private respawn;
+    private writeMatrices;
+}
+
+export declare interface PetalDriftEffectOptions {
+    /** Override petal geometry. Defaults to {@link EllipticLeafGeometry}. */
+    geometry?: BufferGeometry;
+    /** Override the default petal material. */
+    material?: Material;
+    /** Number of petal instances. Defaults to `120`. */
+    count?: number;
+    /** Horizontal spread (world units). Defaults to `16`. */
+    width?: number;
+    /** Vertical spawn span (world units). Defaults to `8`. */
+    height?: number;
+    /** Depth spread (world units). Defaults to `16`. */
+    depth?: number;
+    /** World Y where petals respawn after drifting below the floor. Defaults to `0`. */
+    floorY?: number;
+    /** Minimum fall speed (units/s). Defaults to `0.12`. */
+    fallSpeedMin?: number;
+    /** Maximum fall speed (units/s). Defaults to `0.28`. */
+    fallSpeedMax?: number;
+    /** Minimum horizontal drift speed (units/s). Defaults to `0.04`. */
+    driftMin?: number;
+    /** Maximum horizontal drift speed (units/s). Defaults to `0.14`. */
+    driftMax?: number;
+    /**
+     * Flutter strength (radians). Subtle rotation sway as each petal falls.
+     * Defaults to `0.35`.
+     */
+    flutter?: number;
+    /** Single petal color or palette; multiple entries pick a random color per petal. */
+    color?: ColorRepresentation | ColorRepresentation[];
+}
+
 /**
  * Planar UV Mapping
  * Projects UVs onto the geometry from a single direction (like shining a projector onto a surface).
@@ -2189,26 +2594,6 @@ export declare class PotionBottleGeometry extends BufferGeometry {
     constructor();
 }
 
-export declare const quadraticCurve: (t: number, p0: number, p1: number, p2: number) => number;
-
-export declare const quadraticEaseIn: (t: number) => number;
-
-export declare const quadraticEaseInOut: (t: number) => number;
-
-export declare const quadraticEaseOut: (t: number) => number;
-
-export declare const quarticEaseIn: (t: number) => number;
-
-export declare const quarticEaseInOut: (t: number) => number;
-
-export declare const quarticEaseOut: (t: number) => number;
-
-export declare const quinticEaseIn: (t: number) => number;
-
-export declare const quinticEaseInOut: (t: number) => number;
-
-export declare const quinticEaseOut: (t: number) => number;
-
 /**
  * Calculate the radius to achieve a spherical cap height.
  *   R = r / (1 - cos(thetaLength))
@@ -2221,6 +2606,110 @@ export declare const radiusFromCapHeight: (height: number, thetaLength: number)
  */
 export declare const radiusFromCapWidth: (width: number, thetaLength: number) => number;
 
+/**
+ * Misty rainfall as instanced vertical streaks.
+ *
+ * Each streak is a thin, gradient-textured quad animated through a bounded
+ * volume. By default streaks fall straight down with no rotation. Optional
+ * {@link RainEffectOptions.windDirection} / {@link RainEffectOptions.windStrength}
+ * tilt streaks **and** drift them horizontally together, so motion matches the
+ * visual angle. Streak materials use `DoubleSide` so thin quads stay visible
+ * from any camera angle. Scene fog dissolves distant streaks when the material's
+ * `fog` flag is enabled.
+ *
+ * **`intensity`** (0–1) scales how many instances draw, how fast they fall, and
+ * their opacity — useful for storm ramps or lightning flashes.
+ *
+ * @example
+ * ```typescript
+ * const rain = new RainEffect({ area: 12, height: 16, intensity: 0.4 });
+ * scene.add(rain);
+ * scene.fog = new Fog(0x0a0a12, 4, 28);
+ *
+ * function animate(delta: number) {
+ *   rain.update(delta);
+ *   renderer.render(scene, camera);
+ * }
+ * ```
+ */
+export declare class RainEffect extends InstancedMesh {
+    /** Rainfall strength (0–1). Adjust at runtime for storm variation. */
+    intensity: number;
+    private readonly maxCount;
+    private readonly area;
+    private readonly height;
+    private readonly groundY;
+    private readonly baseOpacity;
+    private readonly windDirection;
+    private readonly windStrength;
+    private readonly fallDirection;
+    private readonly streakOrientation;
+    private readonly sx;
+    private readonly sz;
+    private readonly topY;
+    private readonly len;
+    private readonly speed;
+    private readonly streakTexture?;
+    private readonly dummy;
+    private clock;
+    constructor(options?: RainEffectOptions);
+    /**
+     * Advance streak positions and refresh instance transforms. Pass elapsed frame
+     * time in seconds (e.g. from `createScene`'s `onFrame` callback).
+     */
+    update(dt: number): void;
+    /** Release geometry, materials, and the procedural streak texture. */
+    dispose(): this;
+    private applyIntensity;
+    private updateFallDirection;
+    private writeMatrices;
+}
+
+export declare interface RainEffectOptions {
+    /** Override the streak quad geometry. Defaults to a thin `PlaneGeometry`. */
+    geometry?: BufferGeometry;
+    /** Override the default streak material. */
+    material?: Material;
+    /** Maximum number of streak instances. Defaults to `1400`. */
+    count?: number;
+    /** Horizontal half-extent of the rainfall area (square centered on the origin). Defaults to `26`. */
+    area?: number;
+    /** Vertical span above `groundY`. Defaults to `22`. */
+    height?: number;
+    /** World Y where streaks recycle. Defaults to `0`. */
+    groundY?: number;
+    /** Streak quad width. Defaults to `0.009`. */
+    width?: number;
+    /** Streak color. Defaults to `#aebfd6`. */
+    color?: ColorRepresentation;
+    /** Base material opacity at full intensity. Defaults to `0.16`. */
+    opacity?: number;
+    /** Minimum streak length. Defaults to `0.18`. */
+    lengthMin?: number;
+    /** Maximum streak length. Defaults to `0.42`. */
+    lengthMax?: number;
+    /** Minimum fall speed (units/s). Defaults to `11`. */
+    speedMin?: number;
+    /** Maximum fall speed (units/s). Defaults to `19`. */
+    speedMax?: number;
+    /**
+     * Horizontal compass direction the wind blows (radians, 0 = +X, π/2 = +Z).
+     * Only used when {@link RainEffectOptions.windStrength} is greater than zero.
+     * Defaults to `0`.
+     */
+    windDirection?: number;
+    /**
+     * How much rain tilts and drifts from vertical, as `tan(angleFromVertical)`.
+     * `0` = straight down (default). `0.15` ≈ 8.5° lean with matching horizontal drift.
+     */
+    windStrength?: number;
+    /**
+     * Rainfall strength (0–1). Scales visible instance count, fall speed, and opacity.
+     * Defaults to `0.5`.
+     */
+    intensity?: number;
+}
+
 /**
  * Generates a random number between `min` and `max`.
  */
@@ -2305,6 +2794,256 @@ declare interface RowOfBooksOptions<T extends Material = Material> {
     scaleZMax?: number;
 }
 
+/**
+ * SceneTransition provides smooth animated transitions between Three.js scenes.
+ *
+ * Supports multiple transition types:
+ * - Fade: Fade to a color (black, white, etc.) and back
+ * - Crossfade: Directly blend from one scene to another
+ * - Blur: Blur out the first scene and blur in the second
+ *
+ * @example
+ * ```typescript
+ * const sceneTransition = new SceneTransition(renderer);
+ *
+ * // Fade to black transition
+ * sceneTransition.fade(sceneA, sceneB, camera, {
+ *   duration: 1000,
+ *   color: 0x000000,
+ *   easing: 'easeInOutCubic'
+ * });
+ *
+ * // Direct crossfade
+ * sceneTransition.crossfade(sceneA, sceneB, camera, {
+ *   duration: 1500
+ * });
+ * ```
+ */
+export declare class SceneTransition {
+    private renderer;
+    private currentScene;
+    private targetScene;
+    private camera;
+    private transitionProgress;
+    private transitionDuration;
+    private transitionStartTime;
+    private isTransitioning;
+    private transitionType;
+    private easingFunction;
+    private renderTargetA;
+    private renderTargetB;
+    private blendScene;
+    private blendCamera;
+    private fadeMaterial;
+    private crossfadeMaterial;
+    private fadeColor;
+    private onUpdateCallback?;
+    private onCompleteCallback?;
+    constructor(renderer: THREE.WebGLRenderer);
+    /**
+     * Fade transition: Fades to a color and then fades in the new scene
+     */
+    fade(fromScene: THREE.Scene, toScene: THREE.Scene, camera: THREE.Camera, options?: FadeTransitionOptions): void;
+    /**
+     * Crossfade transition: Directly blends from one scene to another
+     */
+    crossfade(fromScene: THREE.Scene, toScene: THREE.Scene, camera: THREE.Camera, options?: SceneTransitionOptions): void;
+    /**
+     * Blur transition: Blurs out first scene, then blurs in second scene
+     * Note: This uses the fade material with a neutral gray for a blur-like effect
+     * For true blur, you'd need post-processing passes
+     */
+    blur(fromScene: THREE.Scene, toScene: THREE.Scene, camera: THREE.Camera, options?: SceneTransitionOptions): void;
+    /**
+     * Internal method to start a transition
+     */
+    private startTransition;
+    /**
+     * Update the transition. Call this in your render loop.
+     */
+    update(): void;
+    /**
+     * Render the scene with transition blending
+     */
+    render(): void;
+    /**
+     * Get the current active scene
+     */
+    getCurrentScene(): THREE.Scene | null;
+    /**
+     * Check if a transition is currently in progress
+     */
+    getIsTransitioning(): boolean;
+    /**
+     * Get the current transition progress (0-1)
+     */
+    getProgress(): number;
+    /**
+     * Set the current scene (useful for initialization)
+     */
+    setCurrentScene(scene: THREE.Scene): void;
+    /**
+     * Resize the render targets when the renderer size changes
+     */
+    setSize(width: number, height: number): void;
+    /**
+     * Dispose of resources
+     */
+    dispose(): void;
+}
+
+/**
+ * SceneTransitionFX provides advanced post-processing transitions between Three.js scenes.
+ *
+ * Uses EffectComposer for sophisticated visual effects:
+ * - Bloom: Bright bloom effect that peaks at transition midpoint, washing out to white
+ * - Blur: Progressive blur effect that peaks at midpoint, blurring scenes to oblivion
+ * - Fade: Classic fade through a color (black, white, or custom)
+ * - Glitch: Digital distortion/glitch effect with heavy artifacts
+ *
+ * Built-in shader passes for blur and fade are automatically created. For bloom and glitch
+ * effects, you'll need to provide those passes manually.
+ *
+ * Note: Requires post-processing imports from three/addons
+ *
+ * @example
+ * ```typescript
+ * import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
+ * import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
+ * import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js';
+ * import { ShaderPass } from 'three/addons/postprocessing/ShaderPass.js';
+ *
+ * const composer = new EffectComposer(renderer);
+ * const renderPass = new RenderPass(sceneA, camera);
+ * composer.addPass(renderPass);
+ *
+ * // Pass ShaderPass to enable built-in blur and fade effects
+ * const sceneTransitionFX = new SceneTransitionFX(renderer, composer, ShaderPass);
+ *
+ * // Blur and fade transitions work out of the box
+ * sceneTransitionFX.blur(sceneA, sceneB, camera, { duration: 2000 });
+ * sceneTransitionFX.fade(sceneA, sceneB, camera, { duration: 2000, color: 0x000000 });
+ *
+ * // For bloom, provide the pass manually
+ * const bloomPass = new UnrealBloomPass(new THREE.Vector2(width, height), 0, 0.4, 0.85);
+ * bloomPass.enabled = false;
+ * composer.addPass(bloomPass);
+ * sceneTransitionFX.setBloomPass(bloomPass);
+ * sceneTransitionFX.bloom(sceneA, sceneB, camera, { duration: 2000, maxBloom: 15.0 });
+ * ```
+ */
+export declare class SceneTransitionFX {
+    private renderer;
+    private composer;
+    private currentScene;
+    private targetScene;
+    private camera;
+    private transitionProgress;
+    private transitionDuration;
+    private transitionStartTime;
+    private isTransitioning;
+    private transitionType;
+    private easingFunction;
+    private renderPass;
+    private bloomPass;
+    private glitchPass;
+    private blurPass;
+    private fadePass;
+    private maxBloomStrength;
+    private maxBlurAmount;
+    private maxGlitchIntensity;
+    private fadeColor;
+    private onUpdateCallback?;
+    private onCompleteCallback?;
+    constructor(renderer: THREE.WebGLRenderer, composer: any, ShaderPass?: any);
+    /**
+     * Create default shader passes for blur and fade effects
+     */
+    private createDefaultPasses;
+    /**
+     * Set the bloom pass for bloom transitions
+     */
+    setBloomPass(bloomPass: any): void;
+    /**
+     * Set the glitch pass for glitch transitions
+     */
+    setGlitchPass(glitchPass: any): void;
+    /**
+     * Set the blur pass for blur transitions
+     */
+    setBlurPass(blurPass: any): void;
+    /**
+     * Set the fade pass for fade transitions
+     */
+    setFadePass(fadePass: any): void;
+    /**
+     * Bloom transition: Bright bloom effect that peaks at transition midpoint
+     */
+    bloom(fromScene: THREE.Scene, toScene: THREE.Scene, camera: THREE.Camera, options?: BloomTransitionOptions): void;
+    /**
+     * Blur transition: Progressively blur scenes to oblivion and back
+     */
+    blur(fromScene: THREE.Scene, toScene: THREE.Scene, camera: THREE.Camera, options?: BlurTransitionOptions): void;
+    /**
+     * Fade transition: Classic fade through a color (black, white, or custom)
+     */
+    fade(fromScene: THREE.Scene, toScene: THREE.Scene, camera: THREE.Camera, options?: FadeTransitionOptions_2): void;
+    /**
+     * Glitch transition: Digital distortion effect
+     */
+    glitch(fromScene: THREE.Scene, toScene: THREE.Scene, camera: THREE.Camera, options?: GlitchTransitionOptions): void;
+    /**
+     * Internal method to start a transition
+     */
+    private startTransition;
+    /**
+     * Update the transition. Call this in your render loop.
+     */
+    update(): void;
+    /**
+     * Render using the effect composer
+     */
+    render(): void;
+    /**
+     * Get the current active scene
+     */
+    getCurrentScene(): THREE.Scene | null;
+    /**
+     * Check if a transition is currently in progress
+     */
+    getIsTransitioning(): boolean;
+    /**
+     * Get the current transition progress (0-1)
+     */
+    getProgress(): number;
+    /**
+     * Set the current scene (useful for initialization)
+     */
+    setCurrentScene(scene: THREE.Scene): void;
+    /**
+     * Resize the composer when the renderer size changes
+     */
+    setSize(width: number, height: number): void;
+    /**
+     * Dispose of resources
+     */
+    dispose(): void;
+}
+
+export declare interface SceneTransitionFXOptions {
+    duration?: number;
+    easing?: EasingFunction | keyof typeof Easing;
+    onUpdate?: (progress: number) => void;
+    onComplete?: () => void;
+}
+
+export declare interface SceneTransitionOptions {
+    duration?: number;
+    easing?: EasingFunction | keyof typeof Easing;
+    onUpdate?: (progress: number) => void;
+    onComplete?: () => void;
+}
+
 /**
  * Set a random interval that will call the callback function with a random delay between minDelay and maxDelay.
  *
@@ -2329,21 +3068,11 @@ export declare function setRandomInterval(callback: () => void, minDelay: number
  */
 export declare function setRandomTimeout(callback: () => void, minDelay: number, maxDelay: number): NodeJS.Timeout;
 
-export declare const sigmoidCurve: (t: number, a?: number) => number;
-
-export declare const sineEaseIn: (t: number) => number;
-
-export declare const sineEaseInOut: (t: number) => number;
-
-export declare const sineEaseOut: (t: number) => number;
-
 /**
  * Smooths out the vertices by averaging their positions with neighboring vertices within a given radius.
  */
 export declare const smoothBrush: <T extends BufferGeometry>(geometry: T, position: Vector3, radius: number, strength: number) => void;
 
-export declare const smoothstep: (t: number) => number;
-
 /**
  * Convert spherical coordinates to Cartesian coordinates.
  * @param {number} radius - The radius of the sphere.
@@ -2395,8 +3124,6 @@ export declare class SquareHeadstoneGeometry extends BufferGeometry {
     constructor(width?: number, height?: number, depth?: number);
 }
 
-export declare const squareRoot: (t: number) => number;
-
 export declare class StaircaseGeometry extends BufferGeometry {
     constructor(width?: number, stepHeight?: number, stepDepth?: number, numSteps?: number);
 }
@@ -2432,6 +3159,121 @@ export declare class Star extends Mesh {
     });
 }
 
+export declare interface StarBurstShapeOptions {
+    /** Burst ray count. Defaults to `4`. */
+    sides?: number;
+    innerRadius?: number;
+    outerRadius?: number;
+    /** Extrusion depth; keep small for flat starbursts. Defaults to `0.05`. */
+    depth?: number;
+}
+
+/**
+ * Procedural star field distributed on a spherical shell — intended as an infinite sky dome.
+ *
+ * Stars are placed in world space around the origin. To keep the shell centered on the
+ * viewer, add this object to the **scene** (not the camera) and copy the camera position
+ * every frame. Parenting to the camera is not supported: Three.js does not render
+ * objects attached to the active camera.
+ *
+ * **Styles**
+ *
+ * - `points` — lightweight `Points` sprites using a canvas starburst texture.
+ * - `burst` — instanced 3D starbursts ({@link BurstGeometry}) that face the shell center.
+ *   Uses `DoubleSide` so stars remain visible when the camera sits inside the shell.
+ *
+ * **Sizing** — `sizeMin` / `sizeMax` are angular extents (radians at unit distance),
+ * multiplied by each star's distance from the origin so stars look similar regardless
+ * of shell depth (`minRadius`–`maxRadius`).
+ *
+ * **Rendering** — `frustumCulled` is disabled and materials use `depthWrite: false` so
+ * the field draws reliably as a background layer. For per-star color variation in burst
+ * mode, colors are written via `InstancedMesh.setColorAt`, not `vertexColors` on the
+ * base material.
+ *
+ * @example
+ * ```typescript
+ * const stars = new StarFieldEffect({
+ *   style: "burst",
+ *   count: 2500,
+ *   radius: 480,
+ *   twinkle: true,
+ * });
+ *
+ * scene.add(stars);
+ *
+ * function animate() {
+ *   stars.position.copy(camera.position); // sky dome follows the viewer
+ *   stars.update(); // no-op when twinkle is false
+ *   renderer.render(scene, camera);
+ * }
+ * ```
+ *
+ * Call {@link dispose} when removing the effect to free geometry, materials, and the
+ * points sprite texture.
+ */
+export declare class StarFieldEffect extends Object3D {
+    readonly style: "points" | "burst";
+    private readonly field;
+    private readonly twinkle;
+    private readonly baseSize;
+    private readonly baseScales?;
+    private readonly twinklePhases?;
+    private spriteTexture?;
+    private readonly dummy;
+    constructor(options?: StarFieldEffectOptions);
+    get drawable(): Points | InstancedMesh;
+    get geometry(): BufferGeometry;
+    get material(): Material | Material[];
+    /** Release GPU resources held by the field (and sprite texture, if any). */
+    dispose(): void;
+    /**
+     * Animate twinkling. No-op when `twinkle` is `false`.
+     *
+     * Points style modulates sprite size; burst style pulses each instance scale with
+     * a per-star phase offset. Pass elapsed time in seconds (defaults to `performance.now()`).
+     */
+    update(elapsed?: number): void;
+    private createPointsField;
+    private createBurstField;
+}
+
+export declare interface StarFieldEffectOptions {
+    /**
+     * Rendering style.
+     *
+     * - `points` (default) — billboard sprites with a procedural starburst texture
+     *   (not the default square `Points` marker).
+     * - `burst` — instanced {@link BurstGeometry} meshes oriented toward the shell center.
+     */
+    style?: "points" | "burst";
+    /** Shape parameters for both styles; `burst` uses them for geometry, `points` for the sprite. */
+    burst?: StarBurstShapeOptions;
+    /** Override the burst mesh geometry (`style: "burst"` only). */
+    geometry?: BufferGeometry;
+    /** Override the default field material. */
+    material?: Material;
+    /** Number of stars. Defaults to `1500`. */
+    count?: number;
+    /** Shell radius when `minRadius` / `maxRadius` are omitted. Defaults to `500`. */
+    radius?: number;
+    /** Inner shell radius. Defaults to `radius`. */
+    minRadius?: number;
+    /** Outer shell radius. Defaults to `radius`. */
+    maxRadius?: number;
+    /**
+     * Minimum angular size (radians at 1 unit distance). Scaled by each star's shell distance
+     * so apparent size stays consistent. Defaults to `0.008`.
+     */
+    sizeMin?: number;
+    /** Maximum angular size. Defaults to `0.025`. */
+    sizeMax?: number;
+    /** Single color or palette; multiple entries pick a random color per star. */
+    color?: ColorRepresentation | ColorRepresentation[];
+    /** Enable pulsing brightness; call {@link StarFieldEffect.update} each frame when `true`. */
+    twinkle?: boolean;
+}
+
 /**
  * Extrude geometry of Star Shape.
  */
@@ -2484,8 +3326,22 @@ export declare class TestTubeGeometry extends BufferGeometry {
     constructor(radiusTop?: number, radiusBottom?: number, height?: number, segments?: number, openEnded?: boolean);
 }
 
+/**
+ * Wooden rack with instanced test tubes and emissive liquid fills.
+ *
+ * Glass shells use `DoubleSide` and `depthWrite: false`; liquid draws first
+ * (`renderOrder` 1), glass second (`renderOrder` 2) so fills stay visible at
+ * most camera angles.
+ */
 export declare class TestTubeRack extends Group {
-    constructor(count?: number, colors?: number[]);
+    constructor(count?: number, colors?: ColorRepresentation[]);
+}
+
+export declare interface TestTubeRackOptions {
+    /** Number of tubes. Defaults to `3`. */
+    count?: number;
+    /** Liquid color per tube; cycles when fewer entries than tubes. */
+    colors?: ColorRepresentation[];
 }
 
 /**
@@ -2592,6 +3448,88 @@ export declare class WineBottleGeometry extends BufferGeometry {
     });
 }
 
+/**
+ * Will-o'-the-wisps drifting through a bounded volume — eerie green orbs that
+ * bob around spawn points with a pulsing point light. Ported from the portfolio
+ * graveyard scene.
+ *
+ * @example
+ * ```ts
+ * const wisps = new WispEffect({ count: 3 });
+ * scene.add(wisps);
+ * onFrame((dt) => wisps.update(dt));
+ * ```
+ */
+export declare class WispEffect extends Object3D {
+    private readonly wisps;
+    private readonly orbGeometry;
+    private readonly orbMaterial;
+    private readonly halfWidth;
+    private readonly depth;
+    private readonly heightMin;
+    private readonly heightMax;
+    private readonly driftX;
+    private readonly driftY;
+    private readonly driftZ;
+    private readonly speedMin;
+    private readonly speedMax;
+    private readonly castLight;
+    private readonly lightDistance;
+    private readonly lightDecay;
+    private readonly lightIntensity;
+    private readonly lightPulseAmplitude;
+    private readonly lightPulseSpeed;
+    private elapsed;
+    constructor({ count, width, depth, heightMin, heightMax, color, orbRadius, driftX, driftY, driftZ, speedMin, speedMax, castLight, lightDistance, lightDecay, lightIntensity, lightPulseAmplitude, lightPulseSpeed, }?: WispEffectOptions);
+    update(dt: number): void;
+    dispose(): void;
+}
+
+export declare interface WispEffectOptions {
+    /** Number of drifting wisps. Defaults to `3`. */
+    count?: number;
+    /** Horizontal spawn extent (world units, centered on the effect). Defaults to `16`. */
+    width?: number;
+    /** Depth spawn maximum (world units, from z = 0). Defaults to `8`. */
+    depth?: number;
+    /** Minimum spawn height. Defaults to `1`. */
+    heightMin?: number;
+    /** Maximum spawn height. Defaults to `2`. */
+    heightMax?: number;
+    /** Wisp tint. Defaults to `0x6dffb0` (portfolio graveyard). */
+    color?: ColorRepresentation;
+    /** Orb radius. Defaults to `0.08`. */
+    orbRadius?: number;
+    /** Horizontal drift radius (X). Defaults to `1.6`. */
+    driftX?: number;
+    /** Vertical drift radius (Y). Defaults to `0.3`. */
+    driftY?: number;
+    /** Depth drift radius (Z). Defaults to `1.6`. */
+    driftZ?: number;
+    /** Minimum motion speed multiplier. Defaults to `0.3`. */
+    speedMin?: number;
+    /** Maximum motion speed multiplier. Defaults to `0.7`. */
+    speedMax?: number;
+    /**
+     * Attach a {@link PointLight} per wisp (keep `count` low).
+     * Defaults to `true` to match the portfolio graveyard.
+     */
+    castLight?: boolean;
+    /** Point light distance when `castLight`. Defaults to `6`. */
+    lightDistance?: number;
+    /** Point light decay when `castLight`. Defaults to `2`. */
+    lightDecay?: number;
+    /**
+     * Light intensity = `lightIntensity + sin(t * lightPulseSpeed) * lightPulseAmplitude`.
+     * Defaults to `2.5`.
+     */
+    lightIntensity?: number;
+    /** Defaults to `1.2`. */
+    lightPulseAmplitude?: number;
+    /** Defaults to `3`. */
+    lightPulseSpeed?: number;
+}
+
 export declare class WroughtIronBar extends Mesh<WroughtIronBarGeometry, MeshStandardMaterial> {
     constructor({ barHeight, //
         barRadius, spikeHeight, spikeRadius, spikeScaleZ, radialSegments, }?: {