three-low-poly 0.9.24 → 0.9.25

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 import { BoxGeometry } from 'three';
 import { BufferGeometry } from 'three';
-import { Camera } from 'three';
 import { Color } from 'three';
 import { ColorRepresentation } from 'three';
 import { DataTexture } from 'three';
@@ -16,11 +15,14 @@ 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';
@@ -166,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.
  *
@@ -392,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;
 }
@@ -504,31 +504,19 @@ export declare enum BoxSide {
 }
 
 /**
- * Single brick geometry for low-poly aesthetic.
- * Default dimensions approximate standard brick proportions (in feet scale).
+ * 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 class BrickGeometry extends BufferGeometry {
-    constructor({ width, height, depth, }?: {
-        width?: number | undefined;
-        height?: number | undefined;
-        depth?: number | undefined;
-    });
-}
+export declare function buildDiamondLatticeParts({ width, height, centerY, grid, leadThickness: barT, leadDepth: barD, }: DiamondLatticePartOptions): BoxGeometry[];
 
-export declare interface BrickWallOptions {
-    wallWidth?: number;
-    wallHeight?: number;
-    brickWidth?: number;
-    brickHeight?: number;
-    brickDepth?: number;
-    mortarGap?: number;
-    offsetPattern?: boolean;
-    brickColors?: number[];
-    colorVariation?: boolean;
-    positionVariation?: number;
-    rotationVariation?: number;
-    material?: Material;
-}
+/**
+ * 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();
@@ -606,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.
@@ -756,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
@@ -821,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)
@@ -887,6 +862,23 @@ export declare function centerObjectGeometry<T extends Object3D>(object: T, targ
  */
 export declare const checkerboardTexture: (size: number) => DataTexture;
 
+export declare type ClipPhase = "running" | "complete";
+
+/** 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;
+}
+
+/** 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;
     CARDINAL_RED: number;
@@ -959,22 +951,6 @@ export declare const ColorPalette: {
     TITANIUM_WHITE: number;
 };
 
-/**
- * Creates an instanced mesh brick wall with running bond pattern.
- *
- * @example
- * ```ts
- * const wall = createBrickWall({
- *   wallWidth: 10,
- *   wallHeight: 8,
- *   brickColors: [0x8b4513, 0xa0522d, 0x6b3410],
- *   colorVariation: true
- * });
- * scene.add(wall);
- * ```
- */
-export declare function createBrickWall({ wallWidth, wallHeight, brickWidth, brickHeight, brickDepth, mortarGap, offsetPattern, brickColors, colorVariation, positionVariation, rotationVariation, material, }?: BrickWallOptions): InstancedMesh;
-
 /**
  * Function to create cubic Bezier curve points
  *
@@ -1010,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
  *
@@ -1028,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.
  *
@@ -1084,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
  *
@@ -1103,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.
  *
@@ -1173,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
  *
@@ -1189,6 +1197,23 @@ 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: {
@@ -1297,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
@@ -1315,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;
 }
 
 /**
@@ -1432,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.
  *
@@ -1732,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;
@@ -1810,6 +1939,13 @@ export declare class FlorenceFlaskGeometry extends BufferGeometry {
     constructor();
 }
 
+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 }?: {
         sides?: number | undefined;
@@ -1876,6 +2012,86 @@ export declare interface GlowHaloOptions {
     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
@@ -1906,7 +2122,7 @@ export declare interface GroundFogEffectOptions {
      * horizons opposite the camera. Defaults to `0` (interior only).
      */
     perimeterCount?: number;
-    /** Half-extent of the inner bounded plot (fence, wall, diorama edge, etc.). Defaults to `12`. */
+    /** 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;
@@ -1927,6 +2143,90 @@ export declare interface GroundFogEffectOptions {
     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;
@@ -2062,8 +2362,110 @@ export declare class JarGeometry extends BufferGeometry {
     constructor();
 }
 
-export declare class Lantern extends Group {
-    constructor(height?: number, baseWidth?: number);
+/**
+ * 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);
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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);
+}
+
+/**
+ * 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.
+ *
+ * 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 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 {
@@ -2142,7 +2544,7 @@ export declare const LineEquations: {
  * @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.
@@ -2154,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;
 }
 
 /**
@@ -2188,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();
 }
@@ -2290,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 & {
@@ -2389,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.
@@ -2456,6 +2902,17 @@ 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
@@ -2710,18 +3167,126 @@ export declare interface RainEffectOptions {
     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;
 
 /**
@@ -2736,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);
 }
@@ -2763,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> {
@@ -2792,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;
 }
 
 /**
@@ -3108,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);
 }
@@ -3124,8 +3846,53 @@ export declare class SquareHeadstoneGeometry extends BufferGeometry {
     constructor(width?: number, height?: number, depth?: 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> {
@@ -3434,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();
 }
@@ -3530,6 +4398,12 @@ export declare interface WispEffectOptions {
     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, }?: {
@@ -3591,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 { }