three-low-poly 0.9.23 → 0.9.25

package/dist/index.d.ts

@@ -1,21 +1,28 @@
 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';
 import { MeshStandardMaterial } from 'three';
 import { Object3D } from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
 import { ParametricGeometry } from 'three-stdlib';
 import { PerspectiveCamera } from 'three';
+import { Plane } from 'three';
+import { PlaneGeometry } from 'three';
+import { PointLight } from 'three';
+import { Points } from 'three';
+import { Quaternion } from 'three';
 import { ShaderMaterial } from 'three';
 import { Shape } from 'three';
 import { SphereGeometry } from 'three';
@@ -161,6 +168,8 @@ export declare function alignToRow<T extends Object3D>(objects: T[], direction?:
  */
 export declare function appendSphericalCurve(sphereRadiusX: number, sphereRadiusY: number, sphereStartY: number, holeTopRadius?: number, holeBottomRadius?: number, segments?: number): Vector2[];
 
+export declare function applySnapshot(camera: PerspectiveCamera, controls: OrbitControls | undefined, snapshot: CameraSnapshot): void;
+
 /**
  * Atmospheric scattering shader.
  *
@@ -387,10 +396,6 @@ export declare const Axis: {
     XYZ: Vector3;
 };
 
-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;
 }
@@ -400,6 +405,22 @@ declare interface BlurTransitionOptions extends SceneTransitionFXOptions {
     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();
 }
@@ -482,32 +503,20 @@ 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;
-}
+/**
+ * Build merged box geometries for the outer frame and diagonal lead cames.
+ * Diagonal bars are trimmed to the rectangular opening (segment clip, not stencil).
+ */
+export declare function buildDiamondLatticeParts({ width, height, centerY, grid, leadThickness: barT, leadDepth: barD, }: DiamondLatticePartOptions): BoxGeometry[];
 
-export declare interface BubblingEffectOptions {
-    geometry?: BufferGeometry;
-    material?: Material;
-    count?: number;
-    height?: number;
-    width?: number;
-    depth?: number;
-}
+/**
+ * Build merged box geometries for the outer frame and interior mullions.
+ * Orthogonal grid — no clipping required; counts guarantee full panes.
+ */
+export declare function buildGregorianLatticeParts({ width, height, centerY, cellsX, cellsY, mullionThickness: barT, mullionDepth: barD, }: GregorianLatticePartOptions): BoxGeometry[];
+
+/** Outer frame bars — shared topology across lattice window openings. */
+export declare function buildRingLatticeFrameParts({ width, height, centerY, frameThickness: barT, frameDepth: barD, }: RingLatticeFramePartOptions): BoxGeometry[];
 
 export declare class BunsenBurner extends Group {
     constructor();
@@ -585,74 +594,84 @@ export declare function calculateXFromSlopeIntercept(x1: number, y1: number, x2:
  */
 export declare function calculateYFromSlopeIntercept(x1: number, y1: number, x2: number, y2: number, x: number): number;
 
-/**
- * Dolly backward
- *
- * Example:
- * ```
- * cameraDollyAnimation(camera, 5, 3000, () => {
- *   console.log("Dolly animation complete");
- * });
- * ```
- */
-export declare function cameraDollyAnimation(camera: Camera, distance: number, duration: number, onComplete?: () => void): void;
+export declare interface CameraClip {
+    readonly label: string;
+    readonly duration: number;
+    start(runtime: ClipRuntime): void;
+    update(runtime: ClipRuntime, dt: number): ClipPhase;
+    /** Called when playback is cancelled mid-clip. */
+    cancel?(runtime: ClipRuntime): void;
+}
 
-/**
- * The camera flies through a sequence of points, ideal for showcasing specific elements in the scene.
- *
- * Example:
- * ```
- * cameraFlythroughAnimation(
- *   camera,
- *   [
- *     new THREE.Vector3(0, 5, 5),
- *     new THREE.Vector3(0, 5, -25.5),
- *     new THREE.Vector3(-20.5, 5, 0),
- *   ],
- *   6000,
- *   () => {
- *     console.log("Flythrough animation complete");
- *   }
- * );
- * ```
- */
-export declare function cameraFlythroughAnimation(camera: Camera, waypoints: Vector3[], duration: number, onComplete?: () => void): void;
+declare interface CameraClipTiming {
+    /** Duration in seconds. */
+    duration: number;
+    /** Progress easing for normalized time `t` in [0, 1]. Defaults to smoothstep. */
+    ease?: EasingFunction;
+}
 
 /**
- * Orbit around a target
+ * Single director for camera showcase clips — Unity demo-scene style playback.
  *
- * Example:
- * ```
- * cameraOrbitAnimation(camera, new THREE.Vector3(0, 0, 0), 10, 5000, () => {
- *   console.log("Orbit animation complete");
- * });
- * ```
- */
-export declare function cameraOrbitAnimation(camera: Camera, target: Vector3, radius: number, duration: number, onComplete?: () => void): void;
-
-/**
- * The camera swings back and forth like a pendulum.
+ * One active clip at a time, driven by {@link update} with elapsed seconds (`dt`),
+ * not nested `requestAnimationFrame` loops. Disables OrbitControls while playing;
+ * re-enables and syncs `controls.target` to the clip focus on complete.
  *
- * Example:
- * ```
- * cameraPendulumAnimation(camera, new THREE.Vector3(0, 5, 5), 0.5, 9000, 3, () => {
- *   console.log("Pendulum animation complete");
- * });
- * ```
- */
-export declare function cameraPendulumAnimation(camera: Camera, center: Vector3, radius: number, duration: number, oscillations: number, onComplete?: () => void): void;
-
-/**
- * The camera spirals upward, perfect for revealing a large scene or structure.
+ * @example
+ * ```ts
+ * const playback = new CameraPlayback(camera, controls);
+ * playback.setRest(); // snapshot current pose as Reset target
  *
- * Example:
- * ```
- * cameraSpiralAscensionAnimation(camera, new THREE.Vector3(0, 0, 0), 10, 300, 7, 12000, () => {
- *   console.log("Spiral ascension animation complete");
+ * onFrame((dt) => {
+ *   playback.update(dt);
+ *   controls.update();
+ *   renderer.render(scene, camera);
  * });
+ *
+ * playback.play(createOrbitClip({ target, radius: 10, duration: 8 }));
  * ```
  */
-export declare function cameraSpiralAscensionAnimation(camera: Camera, center: Vector3, radius: number, height: number, revolutions: number, duration: number, onComplete?: () => void): void;
+export declare class CameraPlayback {
+    private readonly camera;
+    private readonly controls?;
+    private active;
+    private elapsed;
+    private readonly focus;
+    private rest;
+    constructor(camera: PerspectiveCamera, controls?: OrbitControls | undefined);
+    /** Whether a clip is actively playing. */
+    get isPlaying(): boolean;
+    /** Snapshot the current camera + controls pose as the Reset/rest pose. */
+    setRest(): void;
+    /** Replace the rest pose without stopping playback. */
+    setRestSnapshot(snapshot: CameraSnapshot): void;
+    /**
+     * Begin a clip. Cancels any active clip first.
+     * OrbitControls are disabled until the clip completes or {@link stop} is called.
+     */
+    play(clip: CameraClip): void;
+    /** Cancel the active clip and restore the rest pose. */
+    stop(): void;
+    /** Alias for {@link stop} — return to the rest pose. */
+    reset(): void;
+    /**
+     * Advance the active clip. Call from the scene `onFrame` callback each frame.
+     * @param dt Elapsed seconds since last frame.
+     */
+    update(dt: number): void;
+    /** Release references; call from example dispose. */
+    dispose(): void;
+    private cancelActive;
+    private runtime;
+}
+
+/** Rest pose captured when playback is constructed or reset. */
+export declare interface CameraSnapshot {
+    position: Vector3;
+    quaternion: Quaternion;
+    fov: number;
+    target: Vector3;
+}
 
 /**
  * CameraTransition provides smooth animated transitions between perspective and orthographic cameras.
@@ -735,31 +754,6 @@ export declare interface CameraTransitionOptions {
     onComplete?: () => void;
 }
 
-/**
- * Add a slight random wobble for intensity or realism (e.g., during an explosion).
- *
- * Example:
- * ```
- * cameraWobbleAnimation(camera, 0.5, 1000, () => {
- *   console.log("Wobble animation complete");
- * });
- * ```
- */
-export declare function cameraWobbleAnimation(camera: Camera, intensity: number, duration: number, onComplete?: () => void): void;
-
-/**
- * The camera smoothly zooms in toward a target, focusing attention on a specific point,
- * and resets to its original FOV after completion.
- *
- * Example:
- * ```
- * cameraZoomInAnimation(camera, new THREE.Vector3(0, 0, 0), 120, 75, 2000, () => {
- *   console.log("Zoom in animation complete");
- * });
- * ```
- */
-export declare function cameraZoomInAnimation(camera: PerspectiveCamera, target: Vector3, startFov: number, endFov: number, duration: number, onComplete?: () => void): void;
-
 /**
  * Material indices
  * 0: Stick
@@ -800,6 +794,8 @@ export declare class CandleGeometry extends BufferGeometry {
  */
 export declare const capHeightFromRadius: (radius: number, thetaLength: number) => number;
 
+export declare function captureSnapshot(camera: PerspectiveCamera, controls?: OrbitControls): CameraSnapshot;
+
 /**
  * Calculate the width of a spherical cap.
  *   w = 2 * R * sin(thetaLength)
@@ -866,11 +862,22 @@ export declare function centerObjectGeometry<T extends Object3D>(object: T, targ
  */
 export declare const checkerboardTexture: (size: number) => DataTexture;
 
-export declare const circIn: (t: number) => number;
+export declare type ClipPhase = "running" | "complete";
 
-export declare const circInOut: (t: number) => number;
+/** Per-frame mutable state shared with the active clip. */
+export declare interface ClipRuntime {
+    camera: PerspectiveCamera;
+    controls: OrbitControls | null;
+    /** Seconds elapsed in the active clip. */
+    elapsed: number;
+    /** Clip duration in seconds. */
+    duration: number;
+    /** Look-at point the clip is focused on — synced to OrbitControls on complete. */
+    focus: Vector3;
+}
 
-export declare const circOut: (t: number) => number;
+/** Clip a segment to an axis-aligned rectangle; returns endpoints inside the opening. */
+export declare function clipSegmentToAabb(x1: number, y1: number, x2: number, y2: number, minX: number, minY: number, maxX: number, maxY: number): [number, number, number, number] | null;
 
 export declare const ColorPalette: {
     CADMIUM_RED: number;
@@ -944,10 +951,6 @@ export declare const ColorPalette: {
     TITANIUM_WHITE: number;
 };
 
-export declare const concave: (t: number) => number;
-
-export declare const convex: (t: number) => number;
-
 /**
  * Function to create cubic Bezier curve points
  *
@@ -983,6 +986,9 @@ export declare const createCubicCurvePoints: (start: Vector2, control1: Vector2,
  */
 export declare const createDampedCurvePoints: (start: Vector2, end: Vector2, damping: number, segments?: number) => Vector2[];
 
+/** Dolly in or out along the current view direction. */
+export declare function createDollyClip(options: DollyClipOptions): CameraClip;
+
 /**
  * Function to create exponential curve points
  *
@@ -1001,6 +1007,9 @@ export declare const createDampedCurvePoints: (start: Vector2, end: Vector2, dam
  */
 export declare const createExponentialCurvePoints: (start: Vector2, end: Vector2, base: number, factor: number, segments?: number) => Vector2[];
 
+/** Waypoint tour through a sequence of positions. */
+export declare function createFlythroughClip(options: FlythroughClipOptions): CameraClip;
+
 /**
  * Hexagonal tile pattern factory with density control.
  *
@@ -1057,6 +1066,15 @@ export declare function createHexagonalTilesByRadius(options: HexagonalTileRadiu
  */
 export declare const createLogarithmicCurvePoints: (start: Vector2, end: Vector2, base: number, factor: number, segments?: number) => Vector2[];
 
+/**
+ * Four clipping planes for a rectangular opening (shadow + mesh clip).
+ * Fragments are discarded when `dot(normal, position) > constant`.
+ */
+export declare function createOpeningClippingPlanes(width: number, height: number, centerY?: number): Plane[];
+
+/** Circle the scene — showcase reel orbit. */
+export declare function createOrbitClip(options: OrbitClipOptions): CameraClip;
+
 /**
  * Function to create parabolic curve points
  *
@@ -1076,6 +1094,12 @@ export declare const createLogarithmicCurvePoints: (start: Vector2, end: Vector2
  */
 export declare const createParabolicCurvePoints: (start: Vector2, end: Vector2, a: number, b: number, c: number, segments?: number) => Vector2[];
 
+/**
+ * Atmospheric focus drift — slow Ken Burns sway while locked on a subject.
+ * Not a full orbit; subtle back-and-forth for mood and screen capture.
+ */
+export declare function createPendulumClip(options: PendulumClipOptions): CameraClip;
+
 /**
  * Generates vertices for two triangles based upon a quad.
  *
@@ -1146,6 +1170,17 @@ p2: [number, number, number], p3: [number, number, number], p4: [number, number,
  */
 export declare const createQuadraticCurvePoints: (start: Vector2, control: Vector2, end: Vector2, segments?: number) => Vector2[];
 
+/**
+ * Create a random source.
+ *
+ * - **No seed** — wraps `Math.random()`. Unique every runtime; default for examples.
+ * - **With seed** — {@link mulberry32} stream. Same seed ⇒ same sequence.
+ */
+export declare function createRandom(seed?: number): RandomSource;
+
+/** Hollow square profile extruded for one lattice ring (local XY, facing +Z). */
+export declare function createRingLatticeGeometry(outer: number, wall: number, depth: number): ExtrudeGeometry;
+
 /**
  * Function to create sigmoid curve points
  *
@@ -1162,6 +1197,39 @@ export declare const createQuadraticCurvePoints: (start: Vector2, control: Vecto
  */
 export declare const createSigmoidCurvePoints: (start: Vector2, end: Vector2, a: number, segments?: number) => Vector2[];
 
+/**
+ * Scene-transition spiral — orbit upward while looking down at the scene.
+ * Camera rises and optionally widens its orbit; `lookAt` stays on the ground
+ * target so the view pitches into a bird's-eye survey (not a horizontal orbit).
+ */
+export declare function createSpiralClip(options: SpiralClipOptions): CameraClip;
+
+/**
+ * Impact wobble — short head-shake / recovery shake (gameplay feedback).
+ * Decaying sinusoidal offset, not random noise. For showcase orbit rigs use
+ * {@link createPendulumClip} instead.
+ */
+export declare function createWobbleClip(options: WobbleClipOptions): CameraClip;
+
+/** Focus punch — smooth FOV narrow toward a target. Restores FOV on cancel; keeps end FOV on complete. */
+export declare function createZoomClip(options: ZoomClipOptions): CameraClip;
+
+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);
 }
@@ -1176,14 +1244,6 @@ declare interface CrossHeadstoneOptions {
     depth?: number;
 }
 
-export declare const cubicCurve: (t: number, p0: number, p1: number, p2: number, p3: number) => number;
-
-export declare const cubicIn: (t: number) => number;
-
-export declare const cubicInOut: (t: number) => number;
-
-export declare const cubicOut: (t: number) => number;
-
 /**
  * Cubic UV Mapping
  * Applies a texture by projecting UVs along each face of a cube.
@@ -1223,8 +1283,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 & {
@@ -1264,6 +1322,22 @@ export declare interface DaySkyUniforms {
     bottomColor: Uniform<Color>;
 }
 
+/**
+ * Derive an independent sub-stream seed from a master seed and domain salt.
+ *
+ * XOR the salt before mixing so each subsystem gets its own mulberry32 stream
+ * without sequential `seed + 1` collision risk. Use stable hex constants per
+ * domain (`0x101` books, `0x202` fog, `0x303` windows, …).
+ *
+ * @example
+ * ```ts
+ * const master = 1337;
+ * const bookRng = createRandom(deriveSubSeed(master, 0x101));
+ * const fogRng = createRandom(deriveSubSeed(master, 0x202));
+ * ```
+ */
+export declare function deriveSubSeed(masterSeed: number, salt: number): number;
+
 /**
  * Material indices:
  * 0. Desk surface
@@ -1282,41 +1356,117 @@ export declare class DeskGeometry extends BufferGeometry {
     constructor();
 }
 
+/** Derive uniform cell size from center-to-corner periods. Legacy — prefer grid counts. */
+export declare function diamondLatticeCellFromCount(width: number, height: number, cellsAcross: number): number;
+
+/**
+ * Perpendicular distance from the window center to a corner along the diamond
+ * grid axis (45° families share this spacing when square).
+ */
+export declare function diamondLatticeCornerSpan(width: number, height: number): number;
+
+/**
+ * Axis-aligned diamond lattice — north/south vertices share a vertical axis,
+ * east/west share a horizontal axis (`<>` not `><`).
+ */
+export declare interface DiamondLatticeGrid {
+    /** Horizontal half-diagonal of each quarrel (east–west point spacing). */
+    a: number;
+    /** Vertical half-diagonal of each quarrel (north–south point spacing). */
+    b: number;
+    /**
+     * Came angle from +X; the two families run at `+angle` and `−angle`.
+     * Equals 45° only when `a === b`.
+     */
+    angle: number;
+    /** Shared perpendicular spacing for both came families. */
+    spacing: number;
+}
+
 /**
- * A diorama with a floor and walls.
+ * Build an axis-aligned diamond grid from cell counts.
  *
- * Material indices:
- * 0: Interior walls
- * 1: Floor
- * 2: Exterior walls
+ * `cellsX` quarrels span the width (east–west); `cellsY` span the height.
+ * Equal counts on a square opening yield square diamonds; `5×10` elongates them
+ * vertically while keeping north/south tips on the same vertical axis.
  */
-export declare class Diorama extends Mesh<DioramaGeometry, MeshStandardMaterial[]> {
-    constructor({ width, height, depth, wallThickness, interiorColor, floorColor, exteriorColor, }?: {
-        width?: number | undefined;
-        height?: number | undefined;
-        depth?: number | undefined;
-        wallThickness?: number | undefined;
-        interiorColor?: number | undefined;
-        floorColor?: number | undefined;
-        exteriorColor?: number | undefined;
-    });
+export declare function diamondLatticeGridFromCells(width: number, height: number, cellsX: number, cellsY: number): DiamondLatticeGrid;
+
+declare interface DiamondLatticePartOptions {
+    width: number;
+    height: number;
+    /** Center Y of the opening in local space. Defaults to `0`. */
+    centerY?: number;
+    grid: DiamondLatticeGrid;
+    leadThickness: number;
+    leadDepth: number;
 }
 
+/** @deprecated Use {@link diamondLatticeGridFromCells}. */
+export declare function diamondLatticeSpacingFromGrid(width: number, height: number, cellsX: number, cellsY: number): {
+    plus45: number;
+    minus45: number;
+};
+
 /**
- * Geometry for a diorama with a floor and walls.
+ * Diamond lattice window — diagonal lead cames with axis-aligned quarrels (`<>`).
  *
- * Group indices:
- * 0: Interior walls
- * 1: Floor
- * 2: Exterior walls
+ * Local frame: centered on the opening, XY plane facing +Z. Lead and optional
+ * glass share `z = 0`. Pair with a scene-owned backing plane behind the wall.
  */
-export declare class DioramaGeometry extends BufferGeometry {
-    constructor({ width, height, depth, wallThickness }?: {
-        width?: number | undefined;
-        height?: number | undefined;
-        depth?: number | undefined;
-        wallThickness?: number | undefined;
-    });
+export declare class DiamondLatticeWindow extends Group {
+    readonly lattice: Mesh<DiamondLatticeWindowGeometry, MeshStandardMaterial>;
+    readonly glass?: Mesh<PlaneGeometry, MeshPhysicalMaterial>;
+    readonly cellsX: number;
+    readonly cellsY: number;
+    readonly fittedGrid: DiamondLatticeGrid;
+    constructor({ leadColor, glass, glassColor, glassEmissive, glassEmissiveIntensity, ...geometryOptions }?: DiamondLatticeWindowOptions);
+}
+
+/**
+ * Diamond lattice window — outer frame plus diagonal cames.
+ * Quarrel tips align to the vertical and horizontal axes (`<>`).
+ * Built in the XY plane facing +Z.
+ *
+ * Glass is a separate pane on {@link DiamondLatticeWindow} — this geometry is
+ * lead and frame only (casts shadow; glass typically does not).
+ */
+export declare class DiamondLatticeWindowGeometry extends BufferGeometry {
+    readonly cellsX: number;
+    readonly cellsY: number;
+    readonly fittedGrid: DiamondLatticeGrid;
+    constructor({ width, height, leadThickness, leadDepth, cellsX, cellsY, centerY, }?: DiamondLatticeWindowGeometryOptions);
+}
+
+declare interface DiamondLatticeWindowGeometryOptions {
+    /** Opening width (world units). */
+    width?: number;
+    /** Opening height (world units). */
+    height?: number;
+    /** Lead came thickness (cross-section). Defaults to `0.055`. */
+    leadThickness?: number;
+    /** Lead depth (Z extent). Defaults to `0.11`. */
+    leadDepth?: number;
+    /** Quarrels spanning east–west across the opening. Defaults to `10`. */
+    cellsX?: number;
+    /** Quarrels spanning north–south across the opening. Defaults to `10`. */
+    cellsY?: number;
+    /** Vertical center of the opening in local geometry space. Defaults to `0`. */
+    centerY?: number;
+}
+
+declare interface DiamondLatticeWindowOptions extends DiamondLatticeWindowGeometryOptions {
+    /** Lead + outer frame tint. Defaults to `#0c0f14`. */
+    leadColor?: ColorRepresentation;
+    /**
+     * Optional glass pane coplanar with the lattice (same Z center).
+     * Mad-science uses an emissive sky mesh in the scene instead.
+     */
+    glass?: boolean;
+    glassColor?: ColorRepresentation;
+    /** Glass emissive for moonlit / storm backlight. Defaults to off. */
+    glassEmissive?: ColorRepresentation;
+    glassEmissiveIntensity?: number;
 }
 
 /**
@@ -1399,6 +1549,12 @@ export declare const Direction: {
  */
 export declare const displacementBrush: <T extends BufferGeometry>(geometry: T, position: Vector3, radius: number, strength: number, direction?: Vector3, falloffFn?: (distance: number, radius: number) => number) => void;
 
+export declare interface DollyClipOptions extends CameraClipTiming {
+    /** Distance along view axis — positive pulls back, negative pushes in. */
+    distance: number;
+    ease?: EasingFunction;
+}
+
 /**
  * Easing functions for interpolating values over time.
  *
@@ -1407,7 +1563,7 @@ export declare const displacementBrush: <T extends BufferGeometry>(geometry: T,
  *
  * @example
  * ```typescript
- * import { Easing, cubicInOut } from 'three-low-poly';
+ * import { Easing } from 'three-low-poly';
  *
  * // Using with transitions (namespace)
  * cameraTransition.transitionTo(camera, {
@@ -1415,12 +1571,6 @@ export declare const displacementBrush: <T extends BufferGeometry>(geometry: T,
  *   easing: Easing.cubicInOut  // Function reference
  * });
  *
- * // Or using direct import
- * cameraTransition.transitionTo(camera, {
- *   duration: 1000,
- *   easing: cubicInOut  // Direct function reference
- * });
- *
  * // Or using string reference
  * cameraTransition.transitionTo(camera, {
  *   duration: 1000,
@@ -1478,6 +1628,80 @@ export declare const Easing: {
  */
 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();
 }
@@ -1487,52 +1711,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, }?: {
@@ -1555,22 +1782,17 @@ export declare class ErlenmeyerFlaskGeometry extends BufferGeometry {
     });
 }
 
-export declare const expoIn: (t: number) => number;
-
-export declare const expoInOut: (t: number) => number;
-
-export declare const exponentialCurve: (t: number, base?: number, factor?: number) => number;
-
-export declare const expoOut: (t: number) => number;
-
 export declare const fadeShader: {
     uniforms: {
         tDiffuse: {
             value: null;
         };
-        opacity: {
+        fadeAmount: {
             value: number;
         };
+        fadeColor: {
+            value: null;
+        };
     };
     vertexShader: string;
     fragmentShader: string;
@@ -1584,19 +1806,40 @@ declare interface FadeTransitionOptions_2 extends SceneTransitionFXOptions {
     color?: THREE.ColorRepresentation;
 }
 
+export declare const fadeTransitionSceneShader: {
+    uniforms: {
+        tDiffuseA: {
+            value: null;
+        };
+        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;
@@ -1612,6 +1855,12 @@ export declare function findClosestColorChannelWise(inputColor: number, dataset:
  */
 export declare function findClosestPoint(point: Vector3, mesh: Mesh): Vector3;
 
+/**
+ * Snap cell size so diagonal cames align symmetrically at all four frame edges.
+ * Legacy single-spacing helper — prefer {@link diamondLatticeGridFromCells}.
+ */
+export declare function fitDiamondLatticeCell(width: number, height: number, preferredCell: number): number;
+
 export declare class Flame extends Mesh<FlameGeometry, MeshStandardMaterial> {
     constructor({ height, radius, segmentsU, segmentsV }?: {
         height?: number | undefined;
@@ -1621,14 +1870,61 @@ export declare class Flame extends Mesh<FlameGeometry, MeshStandardMaterial> {
     });
 }
 
-export declare class FlameGeometry extends ParametricGeometry {
-    constructor({ height, radius, segmentsU, segmentsV }?: {
-        height?: number | undefined;
-        radius?: number | undefined;
-        segmentsU?: number | undefined;
-        segmentsV?: number | undefined;
-    });
-}
+/**
+ * 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;
+        radius?: number | undefined;
+        segmentsU?: number | undefined;
+        segmentsV?: number | undefined;
+    });
+}
 
 /**
  * Flattens vertices to a given plane defined by a target height or normal direction.
@@ -1643,7 +1939,12 @@ export declare class FlorenceFlaskGeometry extends BufferGeometry {
     constructor();
 }
 
-export declare const gaussian: (t: number) => number;
+export declare interface FlythroughClipOptions extends CameraClipTiming {
+    waypoints: Vector3[];
+    /** Optional look-at points per waypoint; defaults to next waypoint. */
+    lookAt?: Vector3[];
+    ease?: EasingFunction;
+}
 
 export declare class Gear extends Mesh {
     constructor({ sides, innerRadius, outerRadius, holeSides, holeRadius, depth }?: {
@@ -1681,6 +1982,251 @@ 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;
+}
+
+/** Pane dimensions derived from opening size and cell counts. */
+export declare interface GregorianLatticeGrid {
+    /** Width of each rectangular pane. */
+    paneWidth: number;
+    /** Height of each rectangular pane. */
+    paneHeight: number;
+}
+
+/**
+ * Derive pane size from cell counts.
+ *
+ * `cellsX` panes span the opening width; `cellsY` span the height. Mullions
+ * divide the opening evenly so every segment is a full rectangle.
+ */
+export declare function gregorianLatticeGridFromCells(width: number, height: number, cellsX: number, cellsY: number): GregorianLatticeGrid;
+
+declare interface GregorianLatticePartOptions {
+    width: number;
+    height: number;
+    /** Center Y of the opening in local space. Defaults to `0`. */
+    centerY?: number;
+    cellsX: number;
+    cellsY: number;
+    mullionThickness: number;
+    mullionDepth: number;
+}
+
+/**
+ * Gregorian lattice window — rectangular pane grid with orthogonal mullions.
+ *
+ * Local frame: centered on the opening, XY plane facing +Z. Mullions and
+ * optional glass share `z = 0`.
+ */
+export declare class GregorianLatticeWindow extends Group {
+    readonly mullions: Mesh<GregorianLatticeWindowGeometry, MeshStandardMaterial>;
+    readonly glass?: Mesh<PlaneGeometry, MeshPhysicalMaterial>;
+    readonly cellsX: number;
+    readonly cellsY: number;
+    readonly fittedGrid: GregorianLatticeGrid;
+    constructor({ mullionColor, glass, glassColor, glassEmissive, glassEmissiveIntensity, ...geometryOptions }?: GregorianLatticeWindowOptions);
+}
+
+/**
+ * Gregorian lattice window — outer frame plus orthogonal mullions in a rectangular grid.
+ * Built in the XY plane facing +Z.
+ */
+export declare class GregorianLatticeWindowGeometry extends BufferGeometry {
+    readonly cellsX: number;
+    readonly cellsY: number;
+    readonly fittedGrid: GregorianLatticeGrid;
+    constructor({ width, height, mullionThickness, mullionDepth, cellsX, cellsY, centerY, }?: GregorianLatticeWindowGeometryOptions);
+}
+
+declare interface GregorianLatticeWindowGeometryOptions {
+    /** Opening width (world units). */
+    width?: number;
+    /** Opening height (world units). */
+    height?: number;
+    /** Mullion thickness (cross-section). Defaults to `0.055`. */
+    mullionThickness?: number;
+    /** Mullion depth (Z extent). Defaults to `0.11`. */
+    mullionDepth?: number;
+    /** Rectangular panes across the opening width. Defaults to `4`. */
+    cellsX?: number;
+    /** Rectangular panes up the opening height. Defaults to `6`. */
+    cellsY?: number;
+    /** Vertical center of the opening in local geometry space. Defaults to `0`. */
+    centerY?: number;
+}
+
+declare interface GregorianLatticeWindowOptions extends GregorianLatticeWindowGeometryOptions {
+    /** Frame + mullion tint. Defaults to `#5c4033` (wood). */
+    mullionColor?: ColorRepresentation;
+    /** Optional glass pane coplanar with the mullions (same Z center). */
+    glass?: boolean;
+    glassColor?: ColorRepresentation;
+    glassEmissive?: ColorRepresentation;
+    glassEmissiveIntensity?: 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, scene 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;
+}
+
+/**
+ * Hanging wrought-iron lantern — open cage struts around a solid emissive
+ * inner octahedron (glass-pane lamp). Mount, cage, and lamp use separate
+ * material groups. Pair {@link GlowHalo} and {@link FlameFlickerEffect} at
+ * `cageCenterY` for bloom and flicker.
+ *
+ * Local frame: origin at the chain top (hang point).
+ */
+export declare class HangingLantern extends Mesh<HangingLanternGeometry, MeshStandardMaterial[]> {
+    readonly drop: number;
+    readonly cageCenterY: number;
+    constructor({ color, mountColor, cageColor, lampColor, lampEmissiveIntensity, lampOpacity, inner, ...geometryOptions }?: HangingLanternOptions);
+}
+
+/**
+ * Wrought-iron hanging lantern frame — chain, cap, and open octahedron cage
+ * built from edge struts.
+ *
+ * Material groups: `0` mount (chain + cap), `1` cage struts, `2` inner lamp
+ * (solid octahedron).
+ *
+ * Local frame: origin at the chain top (hang point). The cage top vertex
+ * attaches at the cap center, optionally lowered by `cageGap`.
+ */
+export declare class HangingLanternGeometry extends BufferGeometry {
+    readonly drop: number;
+    readonly chainWidth: number;
+    readonly capWidth: number;
+    readonly capHeight: number;
+    readonly capDepth: number;
+    readonly capOffset: number;
+    readonly cageRadius: number;
+    readonly cageStretch: number;
+    readonly cageGap: number;
+    readonly cageBarWidth: number;
+    readonly innerScale: number;
+    readonly inner: boolean;
+    /** Y of the cage center in local space (negative, below the hang point). */
+    readonly cageCenterY: number;
+    constructor({ drop, chainWidth, capWidth, capHeight, capDepth, capOffset, cageRadius, cageStretch, cageGap, cageBarWidth, innerScale, inner, }?: HangingLanternGeometryOptions);
+}
+
+export declare interface HangingLanternGeometryOptions {
+    /** Chain length from the hang point. Defaults to `3`. */
+    drop?: number;
+    /** Chain link cross-section. Defaults to `0.05`. */
+    chainWidth?: number;
+    /** Cap width (X). Defaults to `0.18`. */
+    capWidth?: number;
+    /** Cap height (Y). Defaults to `0.16`. */
+    capHeight?: number;
+    /** Cap depth (Z). Defaults to `0.18`. */
+    capDepth?: number;
+    /** Cap center offset below the chain bottom. Defaults to `0.02`. */
+    capOffset?: number;
+    /** Cage vertex radius before stretch. Defaults to `0.42`. */
+    cageRadius?: number;
+    /** Vertical stretch on the cage. Defaults to `1.4`. */
+    cageStretch?: number;
+    /** Extra downward offset below the cap-center cage attach. Defaults to `0`. */
+    cageGap?: number;
+    /** Cage strut thickness. Defaults to `0.03`. */
+    cageBarWidth?: number;
+    /** Inner lamp scale relative to the cage (inset to sit inside struts). Defaults to `0.96`. */
+    innerScale?: number;
+    /** Include the solid inner octahedron lamp volume. Defaults to `true`. */
+    inner?: boolean;
+}
+
+export declare interface HangingLanternOptions extends HangingLanternGeometryOptions {
+    /** Wrought-iron tint for mount and cage. Defaults to `#171a1f`. */
+    color?: ColorRepresentation;
+    /** Mount iron tint (chain + cap). Defaults to `color`. */
+    mountColor?: ColorRepresentation;
+    /** Cage strut tint. Defaults to `color`. */
+    cageColor?: ColorRepresentation;
+    /** Inner lamp tint (emissive octahedron). Defaults to `#ffb45a`. */
+    lampColor?: ColorRepresentation;
+    /** Inner lamp emissive strength. Defaults to `1.4`. */
+    lampEmissiveIntensity?: number;
+    /** Inner lamp opacity for a glass-pane read. Defaults to `0.88`. */
+    lampOpacity?: number;
+}
+
 export declare class Heart extends Mesh {
     constructor({ size, width, height, tipDepth, depth }?: {
         size?: number | undefined;
@@ -1798,8 +2344,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
@@ -1818,140 +2362,178 @@ export declare class JarGeometry extends BufferGeometry {
     constructor();
 }
 
-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;
+/**
+ * Tabletop lantern — frame around an emissive glass body. Geometry only; add
+ * {@link GlowHalo} and {@link FlameFlickerEffect} at `lampCenterY` in the
+ * scene.
+ *
+ * Local frame: sits on the Y=0 plane.
+ */
+export declare class Lantern extends Mesh<LanternGeometry, MeshStandardMaterial[]> {
+    readonly lampCenterY: number;
+    constructor(heightOrOptions?: number | LanternOptions, baseWidth?: number);
 }
 
-export declare interface LeafEffectOptions {
-    geometry?: BufferGeometry;
-    material?: Material;
-    count?: number;
-    width?: number;
-    height?: number;
-    depth?: number;
+/**
+ * Tabletop lantern — wood/metal base, roof, and handle framing an emissive
+ * glass body.
+ *
+ * Material groups: `0` frame (base + roof + handle), `1` glass body.
+ *
+ * Local frame: sits on the Y=0 plane; lamp center at `lampCenterY`.
+ */
+export declare class LanternGeometry extends BufferGeometry {
+    readonly baseWidth: number;
+    readonly bodyHeight: number;
+    readonly baseHeight: number;
+    readonly innerScale: number;
+    readonly inner: boolean;
+    readonly lampCenterY: number;
+    constructor({ baseWidth, bodyHeight, baseHeight, roofHeight, roofRadius, glassRadiusScale, innerScale, handleRadius, handleTubeRadius, handleLift, segments, inner, }?: LanternGeometryOptions);
+}
+
+export declare interface LanternGeometryOptions {
+    /** Base / foot radius. Defaults to `0.5`. */
+    baseWidth?: number;
+    /** Glass body height. Defaults to `1.3`. */
+    bodyHeight?: number;
+    /** Base height. Defaults to `0.2`. */
+    baseHeight?: number;
+    /** Roof cone height. Defaults to `0.5`. */
+    roofHeight?: number;
+    /** Roof cone radius. Defaults to `baseWidth * 1.1`. */
+    roofRadius?: number;
+    /** Glass radius relative to `baseWidth`. Defaults to `0.9`. */
+    glassRadiusScale?: number;
+    /** Glass height inset relative to `bodyHeight`. Defaults to `0.96`. */
+    innerScale?: number;
+    /** Carry-handle major radius. Defaults to `baseWidth * 0.8`. */
+    handleRadius?: number;
+    /** Carry-handle tube radius. Defaults to `0.05`. */
+    handleTubeRadius?: number;
+    /** Gap above the roof to the handle center. Defaults to `0.35`. */
+    handleLift?: number;
+    /** Radial segments on round parts. Defaults to `8`. */
+    segments?: number;
+    /** Include the emissive glass body. Defaults to `true`. */
+    inner?: boolean;
+}
+
+export declare interface LanternOptions extends LanternGeometryOptions {
+    /** Frame tint (base, roof, handle). Defaults to `#8b4513`. */
+    color?: ColorRepresentation;
+    /** Glass lamp tint. Defaults to `#ffd700`. */
+    lampColor?: ColorRepresentation;
+    /** Glass emissive strength. Defaults to `1.2`. */
+    lampEmissiveIntensity?: number;
+    /** Glass opacity. Defaults to `0.75`. */
+    lampOpacity?: number;
 }
 
-export declare class LeverPanel extends Group {
-    constructor();
+/**
+ * Folded autumn leaf prefab — {@link LeafGeometry} with flat-shaded double-sided
+ * material matching the graveyard blowing-leaves look.
+ *
+ * Local frame: tip at +Y, base at −Y, fold rises along +Z.
+ */
+export declare class Leaf extends Mesh<LeafGeometry, MeshStandardMaterial> {
+    readonly size: number;
+    readonly lift: number;
+    constructor({ color, ...geometryOptions }?: LeafOptions);
 }
 
 /**
- * Create a light flicker animation that will randomly change the intensity and position of a light.
- * Effect resembles a flickering flame of candlelight.
+ * Low-poly folded leaf — a pointed ellipse with a gently raised midrib so it
+ * catches rim light instead of reading as a flat sliver. Spine vertices sit
+ * slightly above the mirrored rim outline, giving a soft V cross-section under
+ * flat shading.
  *
- * 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;
+ * Local frame: tip at +Y, base at −Y, fold rises along +Z.
+ */
+export declare class LeafGeometry extends BufferGeometry {
+    readonly size: number;
+    readonly lift: number;
+    constructor({ size, lift }?: LeafGeometryOptions);
 }
 
-export declare interface LightFlickerAnimationOptions {
-    light?: Light;
-    minIntensity: number;
-    maxIntensity: number;
-    x: number;
-    y: number;
-    z: number;
-    jitterX: number;
-    jitterY: number;
-    jitterZ: number;
+export declare interface LeafGeometryOptions {
+    /** Overall leaf scale. Defaults to `0.13`. */
+    size?: number;
+    /** Midrib rise above the rim as a fraction of size. Defaults to `0.22`. */
+    lift?: number;
+}
+
+export declare interface LeafOptions extends LeafGeometryOptions {
+    /** Leaf tint. Defaults to `#a8702c`. */
+    color?: ColorRepresentation;
+}
+
+export declare class LeverPanel extends Group {
+    constructor();
 }
 
 /**
- * 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.
+ *
+ * @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 lightningAnimation = new LightningAnimation();
+ * const storm = new LightningEffect({ light: bolt, peak: 12, minGap: 3, maxGap: 9 });
  *
- * setRandomInterval(() => {
- *   lightningEffect.triggerLightning();
- * }, 250, 1250);
+ * 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.
  *
@@ -1962,7 +2544,7 @@ export declare const logarithmicCurve: (t: number, base?: number, factor?: numbe
  * @param {number} [max=1] - Maximum value of the range.
  * @returns {number} A random number between `min` and `max`, skewed towards `max`.
  */
-export declare function logarithmicRandomMax(exponent?: number, min?: number, max?: number): number;
+export declare function logarithmicRandomMax(exponent?: number, min?: number, max?: number, source?: RandomSource): number;
 
 /**
  * Generates a random number skewed towards the minimum value.
@@ -1974,10 +2556,56 @@ export declare function logarithmicRandomMax(exponent?: number, min?: number, ma
  * @param {number} [max=1] - Maximum value of the range.
  * @returns {number} A random number between `min` and `max`, skewed towards `min`.
  */
-export declare function logarithmicRandomMin(exponent?: number, min?: number, max?: number): number;
+export declare function logarithmicRandomMin(exponent?: number, min?: number, max?: number, source?: RandomSource): number;
+
+/**
+ * L-shaped staircase prefab — two flights with a square width × width landing.
+ */
+export declare class LShapedStaircase extends Mesh<LShapedStaircaseGeometry, MeshStandardMaterial> {
+    readonly width: number;
+    readonly riserHeight: number;
+    readonly treadDepth: number;
+    readonly stepsPerFlight: number;
+    readonly landingSize: number;
+    readonly flightRun: number;
+    readonly totalHeight: number;
+    constructor({ color, ...geometryOptions }?: LShapedStaircaseOptions);
+}
 
+/**
+ * L-shaped staircase with a square landing (width × width) at the 90° turn.
+ *
+ * Local frame:
+ * - First flight climbs +Z, centered on X = 0.
+ * - Landing is a width² platform starting at the last tread (no cantilever over
+ *   the lower flight) and extending forward at the turn.
+ * - Second flight climbs −X from the left edge of the landing.
+ */
 export declare class LShapedStaircaseGeometry extends BufferGeometry {
-    constructor(stepWidth?: number, stepHeight?: number, stepDepth?: number, numStepsPerFlight?: number, landingDepth?: number);
+    readonly width: number;
+    readonly riserHeight: number;
+    readonly treadDepth: number;
+    readonly stepsPerFlight: number;
+    readonly landingSize: number;
+    readonly flightRun: number;
+    readonly totalHeight: number;
+    constructor({ width, riserHeight, treadDepth, stepsPerFlight, }?: LShapedStaircaseGeometryOptions);
+}
+
+export declare interface LShapedStaircaseGeometryOptions {
+    /** Stair width (tread left–right extent). Defaults to `2`. */
+    width?: number;
+    /** Vertical rise per step (riser). Defaults to `0.3`. */
+    riserHeight?: number;
+    /** Horizontal run per step (tread depth). Defaults to `0.5`. */
+    treadDepth?: number;
+    /** Steps in each flight (before and after the landing). Defaults to `5`. */
+    stepsPerFlight?: number;
+}
+
+export declare interface LShapedStaircaseOptions extends LShapedStaircaseGeometryOptions {
+    /** Tread and riser tint. Defaults to `#8b4513`. */
+    color?: ColorRepresentation;
 }
 
 /**
@@ -2008,24 +2636,6 @@ export declare class Microscope extends Group {
     constructor();
 }
 
-export declare class Moon extends Mesh<SphereGeometry, ShaderMaterial> {
-    constructor();
-}
-
-/**
- * Moon shader
- * Simple moon effect with noise
- */
-export declare const moonShader: {
-    uniforms: {
-        time: {
-            value: number;
-        };
-    };
-    vertexShader: string;
-    fragmentShader: string;
-};
-
 export declare class MortarAndPestle extends Group {
     constructor();
 }
@@ -2110,6 +2720,12 @@ export declare class MoundGeometry extends BufferGeometry {
     });
 }
 
+/**
+ * Fast seeded PRNG — portfolio Gotham/Water parity.
+ * Returns a closure yielding floats in [0, 1).
+ */
+export declare function mulberry32(seed: number): RandomStream;
+
 export declare class NightSkybox extends Mesh {
     geometry: SphereGeometry;
     material: ShaderMaterial & {
@@ -2209,6 +2825,16 @@ declare interface ObeliskHeadstoneOptions {
     totalHeight?: number;
 }
 
+export declare interface OrbitClipOptions extends CameraClipTiming {
+    target: Vector3;
+    /** Horizontal distance from target. Defaults to current camera distance. */
+    radius?: number;
+    /** Elevation above target Y in radians. Defaults to current camera elevation. */
+    elevation?: number;
+    /** Revolutions over the clip. Defaults to `1`. */
+    revolutions?: number;
+}
+
 /**
  * Prefab for a panel.
  * Designed to be used as a control panel for switches, lights, levels, dials, and gauges.
@@ -2243,8 +2869,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).
  */
@@ -2253,14 +2877,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: {
@@ -2278,6 +2902,97 @@ export declare const ParametricCurveUtils: {
  */
 export declare function parseHexCode(hex: string): [number, number, number];
 
+export declare interface PendulumClipOptions extends CameraClipTiming {
+    target: Vector3;
+    /** Distance from target. Defaults to current camera distance. */
+    distance?: number;
+    /** Peak azimuth swing in radians — keep small for Ken Burns mood (e.g. `0.12`). */
+    azimuthAmplitude?: number;
+    /** Slow back-and-forth cycles over the clip. Defaults to `2`. */
+    oscillations?: number;
+    ease?: EasingFunction;
+}
+
+/**
+ * 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).
@@ -2336,26 +3051,6 @@ export declare class PotionBottleGeometry extends BufferGeometry {
     constructor();
 }
 
-export declare const quadIn: (t: number) => number;
-
-export declare const quadInOut: (t: number) => number;
-
-export declare const quadOut: (t: number) => number;
-
-export declare const quadraticCurve: (t: number, p0: number, p1: number, p2: number) => number;
-
-export declare const quartIn: (t: number) => number;
-
-export declare const quartInOut: (t: number) => number;
-
-export declare const quartOut: (t: number) => number;
-
-export declare const quintIn: (t: number) => number;
-
-export declare const quintInOut: (t: number) => number;
-
-export declare const quintOut: (t: number) => number;
-
 /**
  * Calculate the radius to achieve a spherical cap height.
  *   R = r / (1 - cos(thetaLength))
@@ -2368,18 +3063,230 @@ 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;
+}
+
+/**
+ * Grouped exports — same function API, namespace import like {@link Easing}.
+ *
+ * @example
+ * ```ts
+ * import { Random } from "three-low-poly";
+ * const rng = Random.create(deriveSubSeed(1337, 0x101));
+ * ```
+ */
+export declare const Random: {
+    readonly create: typeof createRandom;
+    readonly mulberry32: typeof mulberry32;
+    readonly splitmix32: typeof splitmix32;
+    readonly deriveSubSeed: typeof deriveSubSeed;
+    readonly range: typeof randomRange;
+    readonly pick: typeof randomPick;
+};
+
 /**
  * Generates a random number between `min` and `max`.
  */
-export declare function randomFloat(min?: number, max?: number): number;
+export declare function randomFloat(min?: number, max?: number, source?: RandomSource): number;
 
 /**
  * Generates a random integer between `min` and `max`.
  */
-export declare function randomInteger(min?: number, max?: number): number;
+export declare function randomInteger(min?: number, max?: number, source?: RandomSource): number;
+
+/** Pick from a non-empty array using any stream — website `pick()` parity. */
+export declare function randomPick<T>(stream: RandomStream, arr: readonly T[]): T;
+
+/** Float in [min, max) from any stream — website `range()` parity. */
+export declare function randomRange(stream: RandomStream, min: number, max: number): number;
+
+/**
+ * Random source — a stream plus distribution helpers.
+ * Returned by {@link createRandom}; also accepted by {@link RandomNumberUtils}.
+ */
+export declare interface RandomSource {
+    /** `true` when backed by {@link mulberry32}; `false` when using `Math.random()`. */
+    readonly seeded: boolean;
+    /** Next float in [0, 1). */
+    next(): number;
+    /** Float in [min, max). */
+    float(min?: number, max?: number): number;
+    /** Integer in [min, max] (inclusive). */
+    int(min?: number, max?: number): number;
+    /** Uniform element from a non-empty array. */
+    pick<T>(arr: readonly T[]): T;
+    /** `true` with given probability (default 0.5). */
+    boolean(probability?: number): boolean;
+    /**
+     * Skew toward `max`. Lower `exponent` = stronger bias.
+     * Mirrors {@link logarithmicRandomMax}.
+     */
+    skewMax(exponent?: number, min?: number, max?: number): number;
+    /**
+     * Skew toward `min`. Lower `exponent` = stronger bias.
+     * Mirrors {@link logarithmicRandomMin}.
+     */
+    skewMin(exponent?: number, min?: number, max?: number): number;
+}
+
+/**
+ * Randomness for procedural generation — unseeded by default, reproducible on demand.
+ *
+ * ---
+ *
+ * ### Layer 1 — stream primitive (portfolio parity)
+ *
+ * - {@link mulberry32} — fast seeded PRNG; returns a `() => number` closure yielding
+ *   floats in `[0, 1)`. Same algorithm as Gotham/Water on the portfolio site.
+ *
+ * ### Seed mixing
+ *
+ * - {@link splitmix32} — mixer only, **not** a stream. Maps one 32-bit value to another.
+ * - {@link deriveSubSeed} — `splitmix32(masterSeed ^ salt)`. Fan one user-facing master
+ *   seed into independent sub-streams per subsystem. Use stable hex salts per domain
+ *   (`0x101` books, `0x202` fog, `0x303` windows, …) instead of `seed + n` offsets.
+ *
+ * ### Layer 2 — library ergonomics
+ *
+ * - {@link createRandom} — **no seed** → wraps `Math.random()`, unique every runtime
+ *   (showcase default). **With seed** → {@link mulberry32} stream, same seed ⇒ same sequence.
+ * - Returns a {@link RandomSource}: `next`, `float`, `int`, `pick`, `boolean`, `skewMax`, `skewMin`.
+ * - {@link Random} namespace — grouped exports, same API as standalone functions (like {@link Easing}).
+ *
+ * ### Layer 3 — {@link RandomNumberUtils}
+ *
+ * Existing helpers (`randomFloat`, `logarithmicRandomMax`, …) accept an optional
+ * {@link RandomSource} as their last argument. Omit it for unseeded default behavior.
+ *
+ * ---
+ *
+ * @example Unique runtime (default)
+ * ```ts
+ * const rng = createRandom();
+ * rng.float(0, 10); // different every page load
+ * ```
+ *
+ * @example Reproducible layout with sub-seeds
+ * ```ts
+ * const master = 1337;
+ * const books = createRandom(deriveSubSeed(master, 0x101));
+ * const fog = createRandom(deriveSubSeed(master, 0x202));
+ * ```
+ *
+ * @example Namespace import
+ * ```ts
+ * const rng = Random.create(deriveSubSeed(1337, 0x101));
+ * ```
+ */
+/** Callable stream returning floats in [0, 1). */
+export declare type RandomStream = () => number;
 
 export declare function randomTransformVertices<T extends BufferGeometry>(geometry: T, axis?: Vector3, minScale?: number, maxScale?: number): T;
 
+/** Resolve uniform ring spacing — `cell` wins over the `cellsX` density hint. */
+export declare function resolveRingLatticeCell(width: number, _height: number, cell?: number, cellsX?: number): number;
+
 export declare function rgbToHex(r: number, g: number, b: number): number;
 
 /**
@@ -2394,6 +3301,84 @@ export declare function rgbToHex(r: number, g: number, b: number): number;
  */
 export declare function rgbToHsl(r: number, g: number, b: number): [number, number, number];
 
+/** Ring-spacing factor — overlap tightens as this approaches 1. */
+export declare const RING_LATTICE_SPACING_FACTOR = 0.96;
+
+declare interface RingLatticeFramePartOptions {
+    width: number;
+    height: number;
+    centerY?: number;
+    frameThickness: number;
+    frameDepth: number;
+}
+
+export declare interface RingLatticeGrid {
+    /** Requested ring-center spacing before the overlap factor. */
+    cell: number;
+    /** Effective center spacing (`cell × 0.96`). */
+    latticeCell: number;
+    /** Outer half-extent of each square ring profile. */
+    ringOuter: number;
+    /** Ring instance count. */
+    count: number;
+}
+
+declare interface RingLatticeSpotOptions {
+    width: number;
+    height: number;
+    centerY?: number;
+    cell: number;
+}
+
+/** Ring-center positions overscanning the opening (stencil trims the excess). */
+export declare function ringLatticeSpots({ width, height, centerY, cell, }: RingLatticeSpotOptions): {
+    spots: [number, number][];
+    grid: RingLatticeGrid;
+};
+
+/**
+ * Ring lattice window — overlapping square rings on a uniform grid (diaper /
+ * trellis fretwork), stencil-clipped to a rectangular opening.
+ */
+export declare class RingLatticeWindow extends Group {
+    readonly lattice: InstancedMesh;
+    readonly frame: Mesh;
+    readonly glass?: Mesh<PlaneGeometry, MeshPhysicalMaterial>;
+    readonly cell: number;
+    readonly fittedGrid: RingLatticeGrid;
+    private readonly clipPlanesLocal;
+    private readonly clipPlanesWorld;
+    constructor({ width, height, cell: cellOption, cellsX, centerY, ringThickness, ringDepth, frameThickness, frameDepth, latticeColor, glass, glassColor, glassEmissive, glassEmissiveIntensity, }?: RingLatticeWindowOptions);
+}
+
+declare interface RingLatticeWindowOptions {
+    /** Opening width (world units). */
+    width?: number;
+    /** Opening height (world units). */
+    height?: number;
+    /** Uniform ring-center spacing. Overrides `cellsX` when set. Defaults to `0.55`. */
+    cell?: number;
+    /** Density hint — `cell = width / cellsX` when `cell` is omitted. */
+    cellsX?: number;
+    /** Wall thickness of each square ring profile. Defaults to `0.05`. */
+    ringThickness?: number;
+    /** Extrusion depth of each ring. Defaults to `0.06`. */
+    ringDepth?: number;
+    /** Outer frame bar thickness. Defaults to `0.055`. */
+    frameThickness?: number;
+    /** Outer frame depth (Z). Defaults to `0.11`. */
+    frameDepth?: number;
+    /** Vertical center of the opening in local space. Defaults to `0`. */
+    centerY?: number;
+    /** Lattice + frame tint. Defaults to `#0c0f14`. */
+    latticeColor?: ColorRepresentation;
+    /** Optional glass pane recessed slightly on −Z. */
+    glass?: boolean;
+    glassColor?: ColorRepresentation;
+    glassEmissive?: ColorRepresentation;
+    glassEmissiveIntensity?: number;
+}
+
 export declare class Rock extends Mesh<RockGeometry, MeshStandardMaterial> {
     constructor(radius?: number, widthSegments?: number, heightSegments?: number);
 }
@@ -2421,22 +3406,24 @@ export declare class RoundedHeadstoneGeometry extends BufferGeometry {
 /**
  * Creates a row of books with a given count.
  */
-export declare function rowOfBooksByCount<T extends Material>({ coverMaterial, pagesMaterial, count, scaleXMin, scaleXMax, scaleYMin, scaleYMax, scaleZMin, scaleZMax, }: RowOfBooksOptions<T>): InstancedMesh;
+export declare function rowOfBooksByCount<T extends Material>({ coverMaterial, pagesMaterial, count, scaleXMin, scaleXMax, scaleYMin, scaleYMax, scaleZMin, scaleZMax, seed, }: RowOfBooksOptions<T>): InstancedMesh;
 
 /**
  * Creates a row of books with a total length.
  */
-export declare function rowOfBooksByLength<T extends Material>({ coverMaterial, pagesMaterial, length, scaleXMin, scaleXMax, scaleYMin, scaleYMax, scaleZMin, scaleZMax, }: RowOfBooksOptions<T>): InstancedMesh;
+export declare function rowOfBooksByLength<T extends Material>({ coverMaterial, pagesMaterial, length, scaleXMin, scaleXMax, scaleYMin, scaleYMax, scaleZMin, scaleZMax, seed, }: RowOfBooksOptions<T>): InstancedMesh;
 
 /**
  * Creates a row of books from the scales array of Vector3.
  */
-export declare function rowOfBooksByScales<T extends Material>({ coverMaterial, pagesMaterial, scales, }: RowOfBooksByScalesOptions<T>): InstancedMesh;
+export declare function rowOfBooksByScales<T extends Material>({ coverMaterial, pagesMaterial, scales, source, }: RowOfBooksByScalesOptions<T>): InstancedMesh;
 
 declare interface RowOfBooksByScalesOptions<T extends Material = Material> {
     coverMaterial: T;
     pagesMaterial: T;
     scales: Vector3[];
+    /** Shared stream for shelf jitter — must be the same source that built `scales`. */
+    source: RandomSource;
 }
 
 declare interface RowOfBooksOptions<T extends Material = Material> {
@@ -2450,6 +3437,8 @@ declare interface RowOfBooksOptions<T extends Material = Material> {
     scaleYMax?: number;
     scaleZMin?: number;
     scaleZMax?: number;
+    /** Optional seed for reproducible layout. Omit for unique runtime. */
+    seed?: number;
 }
 
 /**
@@ -2559,6 +3548,9 @@ export declare class SceneTransition {
  * - 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
@@ -2569,12 +3561,22 @@ export declare class SceneTransition {
  * import { ShaderPass } from 'three/addons/postprocessing/ShaderPass.js';
  *
  * const composer = new EffectComposer(renderer);
- * const sceneTransitionFX = new SceneTransitionFX(renderer, composer);
+ * const renderPass = new RenderPass(sceneA, camera);
+ * composer.addPass(renderPass);
  *
- * sceneTransitionFX.bloom(sceneA, sceneB, camera, {
- *   duration: 2000,
- *   maxBloom: 15.0
- * });
+ * // 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 {
@@ -2600,7 +3602,11 @@ export declare class SceneTransitionFX {
     private fadeColor;
     private onUpdateCallback?;
     private onCompleteCallback?;
-    constructor(renderer: THREE.WebGLRenderer, composer: any);
+    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
      */
@@ -2709,21 +3715,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 sineIn: (t: number) => number;
-
-export declare const sineInOut: (t: number) => number;
-
-export declare const sineOut: (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.
@@ -2759,14 +3755,89 @@ export declare function sphericalUVMapping(vertices: [number, number, number][])
  */
 export declare const spikeBrush: <T extends BufferGeometry>(geometry: T, position: Vector3, radius: number, strength: number, inward?: boolean, falloffFn?: (distance: number, radius: number) => number) => void;
 
+export declare interface SpiralClipOptions extends CameraClipTiming {
+    /** Ground point to look down at (typically scene center, `y = 0`). */
+    target: Vector3;
+    /** Orbit radius at the start of the clip. */
+    radius: number;
+    /** Optional wider radius at the end — pulls back as you rise. Defaults to `radius`. */
+    endRadius?: number;
+    /** Total vertical rise over the clip. */
+    height: number;
+    revolutions: number;
+    ease?: EasingFunction;
+}
+
+/**
+ * Turret-style spiral staircase prefab — wraps {@link SpiralStaircaseGeometry}.
+ */
+export declare class SpiralStaircase extends Mesh<SpiralStaircaseGeometry, MeshStandardMaterial> {
+    readonly innerRadius: number;
+    readonly width: number;
+    readonly outerRadius: number;
+    readonly treadDepth: number;
+    readonly riserHeight: number;
+    readonly stepCount: number;
+    readonly stepAngle: number;
+    readonly totalHeight: number;
+    readonly totalTurn: number;
+    constructor({ color, ...geometryOptions }?: SpiralStaircaseOptions);
+}
+
+/**
+ * Turret-style spiral staircase — trapezoidal treads between an inner newel radius
+ * and an outer wall radius, ascending counter-clockwise when viewed from above.
+ *
+ * Each step is a four-sided tread (no pinched center point). Step angle is
+ * derived from tread depth at the mid-radius so treads meet without overlapping.
+ */
 export declare class SpiralStaircaseGeometry extends BufferGeometry {
-    constructor(stepWidth?: number, stepDepth?: number, stepHeight?: number, numSteps?: number, radius?: number, angleIncrement?: number);
+    readonly innerRadius: number;
+    readonly width: number;
+    readonly outerRadius: number;
+    readonly treadDepth: number;
+    readonly riserHeight: number;
+    readonly stepCount: number;
+    readonly startAngle: number;
+    readonly stepAngle: number;
+    readonly totalHeight: number;
+    readonly totalTurn: number;
+    constructor({ innerRadius, width, treadDepth, riserHeight, stepCount, startAngle, stepAngle: stepAngleOption, }?: SpiralStaircaseGeometryOptions);
+}
+
+export declare interface SpiralStaircaseGeometryOptions {
+    /** Newel / center-hole radius (inner edge of every tread). Defaults to `0.45`. */
+    innerRadius?: number;
+    /** Radial tread width (outer − inner radius). Defaults to `1.95`. */
+    width?: number;
+    /** Arc run per step at the walking line (mid-radius). Defaults to `0.45`. */
+    treadDepth?: number;
+    /** Vertical rise per step (riser). Defaults to `0.2`. */
+    riserHeight?: number;
+    /** Number of steps. Defaults to `20`. */
+    stepCount?: number;
+    /** Spiral start angle in radians (+X = 0, CCW). Defaults to `0`. */
+    startAngle?: number;
+    /** Override step angle (radians). When omitted, derived from `treadDepth`. */
+    stepAngle?: number;
+}
+
+export declare interface SpiralStaircaseOptions extends SpiralStaircaseGeometryOptions {
+    /** Tread and riser tint. Defaults to `#8b4513`. */
+    color?: ColorRepresentation;
 }
 
 export declare class SpiralTube extends Group {
     constructor();
 }
 
+/**
+ * Seed mixer — maps one 32-bit value to another well-distributed value.
+ * Use with {@link deriveSubSeed}, not as a drop-in stream replacement for
+ * {@link mulberry32}.
+ */
+export declare function splitmix32(seed: number): number;
+
 export declare class SquareHeadstone extends Mesh<SquareHeadstoneGeometry, MeshStandardMaterial> {
     constructor(width?: number, height?: number, depth?: number);
 }
@@ -2775,10 +3846,53 @@ export declare class SquareHeadstoneGeometry extends BufferGeometry {
     constructor(width?: number, height?: number, depth?: number);
 }
 
-export declare const squareRoot: (t: number) => number;
+/**
+ * Straight run staircase prefab — {@link StaircaseGeometry} with a wood-tone
+ * default material.
+ *
+ * Local frame: centered on width, rises along +Y, runs along +Z.
+ */
+export declare class Staircase extends Mesh<StaircaseGeometry, MeshStandardMaterial> {
+    readonly width: number;
+    readonly riserHeight: number;
+    readonly treadDepth: number;
+    readonly stepCount: number;
+    readonly totalHeight: number;
+    readonly totalDepth: number;
+    constructor({ color, ...geometryOptions }?: StaircaseOptions);
+}
 
+/**
+ * Straight run staircase — open risers and treads (no side stringers yet).
+ *
+ * Local frame: centered on width, rises along +Y, runs along +Z. Each step
+ * emits a front riser (+Z) and a top tread (+Y). UVs are normalized per face
+ * (0–1) so materials can tile per step.
+ */
 export declare class StaircaseGeometry extends BufferGeometry {
-    constructor(width?: number, stepHeight?: number, stepDepth?: number, numSteps?: number);
+    readonly width: number;
+    readonly riserHeight: number;
+    readonly treadDepth: number;
+    readonly stepCount: number;
+    readonly totalHeight: number;
+    readonly totalDepth: number;
+    constructor({ width, riserHeight, treadDepth, stepCount, }?: StaircaseGeometryOptions);
+}
+
+export declare interface StaircaseGeometryOptions {
+    /** Stair width (tread left–right extent). Defaults to `2`. */
+    width?: number;
+    /** Vertical rise per step (riser). Defaults to `0.3`. */
+    riserHeight?: number;
+    /** Horizontal run per step (tread depth). Defaults to `0.5`. */
+    treadDepth?: number;
+    /** Number of steps. Defaults to `10`. */
+    stepCount?: number;
+}
+
+export declare interface StaircaseOptions extends StaircaseGeometryOptions {
+    /** Tread and riser tint. Defaults to `#8b4513`. */
+    color?: ColorRepresentation;
 }
 
 export declare class Stand extends Mesh<StandGeometry, MeshStandardMaterial> {
@@ -2812,6 +3926,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.
  */
@@ -2864,8 +4093,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[];
 }
 
 /**
@@ -2958,6 +4201,107 @@ export declare function updateNoiseDisplacementTime<T extends Material>(material
  */
 export declare function updateWaterDisplacementTime<T extends Material>(material: T, deltaTime: number): void;
 
+/**
+ * Wall-mounted oil-lamp sconce — iron mount and cap/bowl frame around an
+ * emissive glass chimney. Pair {@link GlowHalo} and {@link FlameFlickerEffect}
+ * at `(lightCenterX, lightCenterY, lightCenterZ)` for bloom and flicker.
+ *
+ * Local frame: faces +X from a −X wall.
+ */
+export declare class WallSconce extends Mesh<WallSconceGeometry, MeshStandardMaterial[]> {
+    readonly lightCenterX: number;
+    readonly lightCenterY: number;
+    readonly lightCenterZ: number;
+    constructor({ color, mountColor, frameColor, lampColor, lampEmissiveIntensity, lampOpacity, inner, ...geometryOptions }?: WallSconceOptions);
+}
+
+/**
+ * Wall-mounted oil-lamp sconce — iron mount, cap, and bowl framing an emissive
+ * glass chimney.
+ *
+ * Material groups: `0` mount (plate + bracket), `1` iron frame (cap + bowl),
+ * `2` glass chimney.
+ *
+ * Local frame: faces +X from a −X wall; lamp center at
+ * `(bodyOffsetX, chimneyCenterY, 0)`.
+ */
+export declare class WallSconceGeometry extends BufferGeometry {
+    readonly bodyOffsetX: number;
+    readonly chimneyCenterY: number;
+    readonly innerScale: number;
+    readonly inner: boolean;
+    readonly lightCenterX: number;
+    readonly lightCenterY: number;
+    readonly lightCenterZ: number;
+    constructor({ plateThickness, plateHeight, plateDepth, plateOffsetX, bracketLength, bracketHeight, bracketDepth, bracketOffsetX, bracketOffsetY, bodyOffsetX, chimneyHeight, chimneyTopRadius, chimneyBottomRadius, chimneyCenterY, capRadius, capHeight, capCenterY, bowlTopRadius, bowlBottomRadius, bowlHeight, bowlCenterY, radialSegments, innerScale, inner, }?: WallSconceGeometryOptions);
+}
+
+export declare interface WallSconceGeometryOptions {
+    /** Wall-plate thickness (X). Defaults to `0.05`. */
+    plateThickness?: number;
+    /** Wall-plate height (Y). Defaults to `0.22`. */
+    plateHeight?: number;
+    /** Wall-plate depth (Z). Defaults to `0.28`. */
+    plateDepth?: number;
+    /** Wall-plate center X (negative = into the wall). Defaults to `-0.055`. */
+    plateOffsetX?: number;
+    /** Bracket length into the room (X). Defaults to `0.1`. */
+    bracketLength?: number;
+    /** Bracket height (Y). Defaults to `0.05`. */
+    bracketHeight?: number;
+    /** Bracket depth (Z). Defaults to `0.07`. */
+    bracketDepth?: number;
+    /** Bracket center X. Defaults to `-0.005`. */
+    bracketOffsetX?: number;
+    /** Bracket center Y. Defaults to `0.1`. */
+    bracketOffsetY?: number;
+    /** Chimney / lamp body center X. Defaults to `0.06`. */
+    bodyOffsetX?: number;
+    /** Chimney height. Defaults to `0.3`. */
+    chimneyHeight?: number;
+    /** Chimney top radius. Defaults to `0.1`. */
+    chimneyTopRadius?: number;
+    /** Chimney bottom radius. Defaults to `0.105`. */
+    chimneyBottomRadius?: number;
+    /** Chimney center Y. Defaults to `-0.05`. */
+    chimneyCenterY?: number;
+    /** Cap radius. Defaults to `0.115`. */
+    capRadius?: number;
+    /** Cap height. Defaults to `0.05`. */
+    capHeight?: number;
+    /** Cap center Y. Defaults to `0.12`. */
+    capCenterY?: number;
+    /** Bowl top radius. Defaults to `0.09`. */
+    bowlTopRadius?: number;
+    /** Bowl bottom radius. Defaults to `0.11`. */
+    bowlBottomRadius?: number;
+    /** Bowl height. Defaults to `0.05`. */
+    bowlHeight?: number;
+    /** Bowl center Y. Defaults to `-0.22`. */
+    bowlCenterY?: number;
+    /** Radial segments on cylinders. Defaults to `8`. */
+    radialSegments?: number;
+    /** Glass chimney scale relative to the frame opening. Defaults to `0.96`. */
+    innerScale?: number;
+    /** Include the emissive glass chimney. Defaults to `true`. */
+    inner?: boolean;
+}
+
+export declare interface WallSconceOptions extends WallSconceGeometryOptions {
+    /** Wrought-iron tint for mount and frame. Defaults to `#1c1e24`. */
+    color?: ColorRepresentation;
+    /** Mount iron tint (plate + bracket). Defaults to `color`. */
+    mountColor?: ColorRepresentation;
+    /** Frame iron tint (cap + bowl). Defaults to `color`. */
+    frameColor?: ColorRepresentation;
+    /** Glass chimney tint. Defaults to `#e8a058`. */
+    lampColor?: ColorRepresentation;
+    /** Glass emissive strength. Defaults to `1.4`. */
+    lampEmissiveIntensity?: number;
+    /** Glass opacity. Defaults to `0.88`. */
+    lampOpacity?: number;
+}
+
 export declare class WineBottle extends Mesh<WineBottleGeometry, MeshPhysicalMaterial> {
     constructor();
 }
@@ -2972,6 +4316,94 @@ 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 interface WobbleClipOptions extends CameraClipTiming {
+    /** Peak positional shake in world units. */
+    intensity: number;
+    ease?: EasingFunction;
+}
+
 export declare class WroughtIronBar extends Mesh<WroughtIronBarGeometry, MeshStandardMaterial> {
     constructor({ barHeight, //
         barRadius, spikeHeight, spikeRadius, spikeScaleZ, radialSegments, }?: {
@@ -3033,4 +4465,11 @@ export declare class WroughtIronFenceGeometry extends BufferGeometry {
     });
 }
 
+export declare interface ZoomClipOptions extends CameraClipTiming {
+    target: Vector3;
+    /** Narrower FOV at the end of the clip (e.g. `35` from `75`). */
+    endFov: number;
+    ease?: EasingFunction;
+}
+
 export { }