@hello-terrain/three 0.0.0-alpha.1 → 0.0.0-alpha.11

package/dist/index.d.cts

@@ -1,13 +1,26 @@
-import { BufferGeometry } from 'three';
+import { BufferGeometry, Ray, Vector3 as Vector3$1, Raycaster, Intersection } from 'three';
+import * as three_webgpu from 'three/webgpu';
+import { StorageArrayTexture, StorageTexture, Node, WebGPURenderer, StorageBufferAttribute, StorageBufferNode, UniformNode, Vector3, Vector3Like, InstancedMesh, NodeMaterial, ConstNode } from 'three/webgpu';
+import Node$1 from 'three/src/nodes/core/Node.js';
 import * as three_src_nodes_TSL_js from 'three/src/nodes/TSL.js';
-import { Node } from 'three/webgpu';
+import { ShaderCallNodeInternal } from 'three/src/nodes/TSL.js';
+import * as _hello_terrain_work from '@hello-terrain/work';
+import { TaskRef, Graph } from '@hello-terrain/work';
+import * as three_tsl from 'three/tsl';
 
 /**
  * Custom geometry for terrain tiles with properly handled skirts.
  * This geometry ensures that corner triangles are subdivided correctly.
  */
 declare class TerrainGeometry extends BufferGeometry {
-    constructor(innerSegments?: number, extendUV?: boolean);
+    /**
+     * @param flipWinding Reverse triangle winding so front faces point the
+     *   opposite way. The default winding makes flat tiles front-face `+Y`; the
+     *   cube-sphere maps `(u→right, v→up)`, which would otherwise leave the
+     *   planet's outer shell back-facing, so it passes `flipWinding` to render
+     *   the outer surface with `FrontSide`.
+     */
+    constructor(innerSegments?: number, extendUV?: boolean, flipWinding?: boolean);
     /**
      * Generate indices for terrain geometry with proper skirt corner handling.
      * The key improvement is in how corner triangles are subdivided.
@@ -28,17 +41,19 @@ declare class TerrainGeometry extends BufferGeometry {
      *  | / | \ | / | \ |
      *  o---o---o---o---o
      *
-     * INNER GRID (consistent diagonal, no rotational symmetry):
-     *        o---o---o
-     *        | \ | \ |
-     *        o---o---o
-     *        | \ | \ |
-     *        o---o---o
+     * INNER GRID (alternating diagonals — checkerboard pattern):
+     *        o---o---o---o---o
+     *        | \ | / | \ | / |
+     *        o---o---o---o---o
+     *        | / | \ | / | \ |
+     *        o---o---o---o---o
+     *        | \ | / | \ | / |
+     *        o---o---o---o---o
      *
      * Where o = vertex
      * Each square cell is split into 2 triangles.
      * - Skirt cells (outer ring): diagonal flip based on quadrant for corner correctness
-     * - Inner cells: consistent diagonal direction (all triangles "point" the same way)
+     * - Inner cells: alternating diagonal via (x+y)%2 to reduce interpolation artifacts
      *
      * Vertex layout (for innerSegments = 2):
      *
@@ -88,6 +103,1027 @@ declare class TerrainGeometry extends BufferGeometry {
     private generateNormals;
 }
 
+declare const Dir: {
+    readonly LEFT: 0;
+    readonly RIGHT: 1;
+    readonly TOP: 2;
+    readonly BOTTOM: 3;
+};
+type Dir = (typeof Dir)[keyof typeof Dir];
+declare const U32_EMPTY = 4294967295;
+type TileId = {
+    /** 0 for flat terrain; 0..5 for cube-sphere faces */
+    space: number;
+    level: number;
+    /** tile coordinate at this level (signed to support infinite surfaces) */
+    x: number;
+    /** tile coordinate at this level (signed to support infinite surfaces) */
+    y: number;
+};
+type TileBounds = {
+    /** camera-relative center */
+    cx: number;
+    cy: number;
+    cz: number;
+    /** conservative radius */
+    r: number;
+};
+type TopologyProjection = "flat" | "cubeSphere";
+type Topology = {
+    spaceCount: number;
+    /** maximum number of roots returned by `rootTiles` */
+    maxRootCount: number;
+    /**
+     * GPU position/normal assembly projection. Defaults to `flat` when absent.
+     * `cubeSphere` selects radial sphere mapping from cube faces.
+     */
+    projection?: TopologyProjection;
+    /** Sphere radius in world units (cube-sphere projection only). */
+    radius?: number;
+    /**
+     * Planet center in world space (cube-sphere projection only). Used to apply
+     * the camera elevation offset along the radial up-direction during LOD.
+     */
+    center?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /**
+     * Compute the same-level neighbor TileId in the requested direction.
+     * Returns false if the neighbor is outside the valid topology.
+     *
+     * IMPORTANT: This must handle cross-space edges in the future (cube-sphere).
+     */
+    neighborSameLevel(tile: TileId, dir: Dir, out: TileId): boolean;
+    /**
+     * Conservative camera-relative bounds for LOD decisions.
+     * Avoids absolute world coordinates so Earth-scale worlds remain stable.
+     */
+    tileBounds(tile: TileId, cameraOrigin: {
+        x: number;
+        y: number;
+        z: number;
+    }, out: TileBounds): void;
+    /**
+     * Fill root tiles for the current frame and return the count.
+     * Implementations should write level-0 tiles into `out[0..count)`.
+     */
+    rootTiles(cameraOrigin: {
+        x: number;
+        y: number;
+        z: number;
+    }, out: TileId[]): number;
+};
+type LeafSet = {
+    /** maximum number of leaves that fit in the buffers */
+    capacity: number;
+    /** number of valid leaf entries in this frame */
+    count: number;
+    space: Uint8Array;
+    level: Uint8Array;
+    x: Int32Array;
+    y: Int32Array;
+};
+declare function allocLeafSet(capacity: number): LeafSet;
+declare function resetLeafSet(leaves: LeafSet): void;
+type SeamTable = {
+    /** maximum number of leaves the table can describe */
+    capacity: number;
+    /** number of leaves described (typically equals leaves.count) */
+    count: number;
+    /** fixed stride per leaf, in u32 entries */
+    stride: 8;
+    /**
+     * neighbors in leaf-list index space
+     * layout: neighbors[leafIndex * 8 + edge*2 + slot]
+     * edge order: LEFT, RIGHT, TOP, BOTTOM
+     * slot: 0..1 (at most 2 neighbors per edge under 2:1 balance)
+     */
+    neighbors: Uint32Array;
+};
+declare function allocSeamTable(capacity: number): SeamTable;
+declare function resetSeamTable(seams: SeamTable): void;
+type LodMode = "distance" | "screen";
+type UpdateParams = {
+    cameraOrigin: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /**
+     * Terrain elevation beneath the camera (from the previous frame). During
+     * refinement it offsets the camera toward the terrain surface so LOD distance
+     * is measured relative to the surface rather than the datum:
+     * - flat: subtracted from `cameraOrigin.y`.
+     * - cube-sphere: subtracted along the radial up-direction from the planet center.
+     */
+    elevationAtCameraXZ?: number;
+    /**
+     * Controls how subdivision decisions are made.
+     * `distance` is the initial focus; `screen` is supported for future parity.
+     */
+    mode?: LodMode;
+    /**
+     * Distance-based refinement threshold.
+     * Interpretation is criteria-dependent; keep it stable across surfaces by using bounds.
+     */
+    distanceFactor?: number;
+    /** Screen-space projection factor = screenHeight / (2*tan(fovY/2)) */
+    projectionFactor?: number;
+    /** Target pixel radius/size threshold for screen-space refinement */
+    targetPixels?: number;
+    /** Prevent flicker by separating split/merge thresholds (0..1 typical) */
+    hysteresis?: number;
+};
+type QuadtreeConfig = {
+    maxNodes: number;
+    maxLevel: number;
+};
+
+type NodeStore = {
+    maxNodes: number;
+    nodesUsed: number;
+    /** generation stamping to avoid clearing buffers */
+    currentGen: number;
+    gen: Uint16Array;
+    space: Uint8Array;
+    level: Uint8Array;
+    x: Int32Array;
+    y: Int32Array;
+    /** sentinel U32_EMPTY means no children; otherwise children are [firstChild..firstChild+3] */
+    firstChild: Uint32Array;
+    flags: Uint8Array;
+    /** root node id per space */
+    roots: Uint32Array;
+};
+
+type SpatialIndex = {
+    size: number;
+    mask: number;
+    stampGen: number;
+    stamp: Uint16Array;
+    keysSpace: Uint8Array;
+    keysLevel: Uint8Array;
+    keysX: Uint32Array;
+    keysY: Uint32Array;
+    values: Uint32Array;
+};
+declare function createSpatialIndex(maxEntries: number): SpatialIndex;
+
+/**
+ * Build a spatial index for the current LeafSet.
+ * Maps (space, level, x, y) -> leafIndex.
+ *
+ * Allocation-free if `out` is provided.
+ */
+declare function buildLeafIndex(leaves: LeafSet, out?: SpatialIndex): SpatialIndex;
+
+type QuadtreeState = {
+    cfg: QuadtreeConfig;
+    store: NodeStore;
+    /** default reusable leaf buffers (capacity = cfg.maxNodes) */
+    leaves: LeafSet;
+    /** internal: node id per leaf entry (parallel to leaves.* arrays) */
+    leafNodeIds: Uint32Array;
+    /** reusable leaf spatial index (capacity = cfg.maxNodes) */
+    leafIndex: SpatialIndex;
+    /** traversal scratch */
+    stack: Uint32Array;
+    /** root nodes for this frame */
+    rootNodeIds: Uint32Array;
+    rootCount: number;
+    /** split scheduling scratch (dedupe without allocations) */
+    splitQueue: Uint32Array;
+    splitStamp: Uint16Array;
+    splitGen: number;
+    /** scratch objects to avoid allocations */
+    scratchTile: TileId;
+    scratchNeighbor: TileId;
+    scratchBounds: TileBounds;
+    scratchRootTiles: TileId[];
+    /** topology space count is fixed for a given state */
+    spaceCount: number;
+};
+declare function createState(cfg: QuadtreeConfig, topology: Topology): QuadtreeState;
+declare function beginUpdate(state: QuadtreeState, topology: Topology, params: UpdateParams): void;
+
+/**
+ * Update the quadtree for the given topology + camera parameters.
+ *
+ * Produces a LeafSet of TileIds (SoA typed arrays).
+ */
+declare function update(state: QuadtreeState, topology: Topology, params: UpdateParams, outLeaves?: LeafSet): LeafSet;
+
+/**
+ * Build a fixed-width seam/neighbor table for balanced leaves (2:1).
+ *
+ * Output neighbors are leaf-list indices, with U32_EMPTY for missing entries.
+ * Layout: neighbors[leafIndex * 8 + edge*2 + slot].
+ */
+declare function buildSeams2to1(topology: Topology, leaves: LeafSet, outSeams: SeamTable, outIndex?: SpatialIndex): SeamTable;
+
+type FlatTopologyConfig = {
+    /**
+     * World-space size of the root tile edge.
+     * The root tile covers [-rootSize/2, +rootSize/2] around origin in X/Z.
+     */
+    rootSize: number;
+    origin: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** optional conservative vertical extent, included in bounds radius */
+    maxHeight?: number;
+};
+declare function createFlatTopology(cfg: FlatTopologyConfig): Topology;
+
+type InfiniteFlatTopologyConfig = {
+    rootSize: number;
+    origin: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** optional conservative vertical extent, included in bounds radius */
+    maxHeight?: number;
+    /** half-width of root grid in root tiles (1 => 3x3 roots) */
+    rootGridRadius?: number;
+};
+declare function createInfiniteFlatTopology(cfg: InfiniteFlatTopologyConfig): Topology;
+
+type CubeSphereTopologyConfig = {
+    /** Sphere radius in world units. */
+    radius: number;
+    /** Planet center in world space (defaults to origin). */
+    center?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Optional conservative vertical extent, included in bounds radius. */
+    maxHeight?: number;
+};
+/**
+ * Cube-sphere topology: six quadtree faces wrapped onto a sphere.
+ *
+ * Topology (`neighborSameLevel`) is derived numerically from the shared
+ * `CUBE_FACES` basis so cross-face edges (including rotated pole edges)
+ * resolve to the correct neighbor tile without hand-coded transforms.
+ */
+declare function createCubeSphereTopology(cfg: CubeSphereTopologyConfig): Topology;
+
+/**
+ * Canonical cube-sphere face basis.
+ *
+ * Shared single source of truth between the CPU surface topology
+ * (`cubeSphere.ts`) and the GPU position/normal assembly (`tsl/cubeSphere.ts`)
+ * so both agree on geometry and faces seam correctly.
+ *
+ * Each face maps a face-local coordinate (u, v) in [0, 1] to a point on the
+ * cube `[-1, 1]^3` via:
+ *
+ *   s = 2u - 1, t = 2v - 1
+ *   cube = forward + s * right + t * up
+ *
+ * Normalizing `cube` yields the unit-sphere direction for that vertex.
+ *
+ * Bases are right-handed (`forward = right x up`) and outward-facing.
+ * Space indices: 0:+X 1:-X 2:+Y 3:-Y 4:+Z 5:-Z.
+ */
+type Vec3 = readonly [number, number, number];
+type CubeFace = {
+    forward: Vec3;
+    right: Vec3;
+    up: Vec3;
+};
+declare const CUBE_FACE_COUNT = 6;
+declare const CUBE_FACES: readonly CubeFace[];
+
+type Vec3Mutable = [number, number, number];
+/**
+ * Cube-space point for a face-local coordinate (u, v) in [0, 1]:
+ *   cube = forward + (2u-1) * right + (2v-1) * up
+ * The result is unnormalized; normalize it to obtain the sphere direction.
+ */
+declare function faceUVToCube(face: number, u: number, v: number, out: Vec3Mutable): void;
+/** Pick the cube face whose normal axis dominates the direction. */
+declare function directionToFace(d: Vec3): number;
+/** Face-local (u, v) in [0, 1] for a direction known to fall on `face`. */
+declare function directionToFaceUV(face: number, d: Vec3, out: [number, number]): void;
+/**
+ * Convert latitude/longitude (degrees) to a unit sphere direction.
+ *
+ * Convention matches `CUBE_FACES` (+Y is the north pole):
+ * - latitude is the angle above the equator, in `[-90, 90]`
+ * - longitude is the angle around the +Y axis, in `[-180, 180]`,
+ *   measured from +Z toward +X (lon = 0 points along +Z).
+ */
+declare function latLongToDirection(latDeg: number, lonDeg: number, out: Vec3Mutable): void;
+/** Inverse of {@link latLongToDirection}; returns degrees. */
+declare function directionToLatLong(d: Vec3): {
+    latitude: number;
+    longitude: number;
+};
+
+type TerrainFieldStorageBackendType = "array-texture" | "atlas" | "texture-3d";
+type TerrainFieldStorageFormat = "rgba16float" | "rgba32float";
+type TerrainFieldStorageOptions = {
+    backend?: TerrainFieldStorageBackendType;
+    filter?: "nearest" | "linear";
+    format?: TerrainFieldStorageFormat;
+};
+interface TerrainFieldStorage {
+    readonly backendType: TerrainFieldStorageBackendType;
+    readonly edgeVertexCount: number;
+    readonly tileCount: number;
+    readonly texture: StorageArrayTexture | StorageTexture;
+    uv(ix: Node, iy: Node, tileIndex: Node): Node;
+    texel(ix: Node, iy: Node, tileIndex: Node): Node;
+    /** UV-based filtered sample. `u, v` in [0, 1] tile-local space. */
+    sample(u: Node, v: Node, tileIndex: Node): Node;
+    resize(width: number, height: number, tileCount: number): void;
+}
+declare function ArrayTextureBackend(edgeVertexCount: number, tileCount: number, options: Required<Pick<TerrainFieldStorageOptions, "format" | "filter">>): TerrainFieldStorage;
+declare function AtlasBackend(edgeVertexCount: number, tileCount: number, options: Required<Pick<TerrainFieldStorageOptions, "format" | "filter">>): TerrainFieldStorage;
+declare function createTerrainFieldStorage(edgeVertexCount: number, tileCount: number, renderer?: WebGPURenderer, options?: TerrainFieldStorageOptions): TerrainFieldStorage;
+declare function storeTerrainField(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node, value: Node): Node;
+declare function loadTerrainField(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
+declare function loadTerrainFieldElevation(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
+declare function loadTerrainFieldNormal(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
+/**
+ * UV-based filtered sample. `u, v` are in [0, 1] tile-local space.
+ * Respects the filter mode (nearest / linear) set on the storage.
+ */
+declare function sampleTerrainField(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
+declare function sampleTerrainFieldElevation(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
+declare function packTerrainFieldSample(height: Node, normalXZ: Node, extra?: Node): Node;
+
+interface ElevationParams {
+    worldPosition: Node$1;
+    rootSize: Node$1;
+    rootUV: Node$1;
+    tileUV: Node$1;
+    tileLevel: Node$1;
+    tileSize: Node$1;
+    tileOriginVec2: Node$1;
+    nodeIndex: Node$1;
+}
+type ElevationCallback = (params: ElevationParams) => Node$1;
+
+interface TerrainUniformsParams {
+    rootSize: number;
+    rootOrigin: Vector3Like;
+    innerTileSegments: number;
+    skirtScale: number;
+    elevationScale: number;
+    radius: number;
+    instanceId: string;
+}
+interface TerrainUniformsContext {
+    uRootOrigin: UniformNode<Vector3>;
+    uRootSize: UniformNode<number>;
+    uInnerTileSegments: UniformNode<number>;
+    uSkirtScale: UniformNode<number>;
+    uElevationScale: UniformNode<number>;
+    uRadius: UniformNode<number>;
+}
+interface LeafStorageState {
+    data: Int32Array<ArrayBuffer>;
+    attribute: StorageBufferAttribute;
+    node: StorageBufferNode;
+}
+
+interface GpuSpatialIndexContext {
+    data: Uint32Array<ArrayBuffer>;
+    size: number;
+    mask: number;
+    stampGen: UniformNode<number>;
+    attribute: StorageBufferAttribute;
+    node: StorageBufferNode;
+}
+interface TerrainSampler {
+    sampleElevation: (worldX: Node, worldZ: Node) => Node;
+    sampleNormal: (worldX: Node, worldZ: Node) => Node;
+    sampleTerrain: (worldX: Node, worldZ: Node) => Node;
+    sampleValidity: (worldX: Node, worldZ: Node) => Node;
+    evaluateElevation: (worldX: Node, worldZ: Node) => Node;
+    evaluateNormal: (worldX: Node, worldZ: Node, epsilon?: Node) => Node;
+    /** Packed `vec4(elevation, nx, ny, nz)` where the normal is tangent-space. */
+    sampleTerrainByDirection?: (direction: Node) => Node;
+    sampleElevationByDirection?: (direction: Node) => Node;
+    /** World-space surface normal reconstructed in the sphere tangent frame. */
+    sampleNormalByDirection?: (direction: Node) => Node;
+    sampleValidityByDirection?: (direction: Node) => Node;
+}
+interface CreateTerrainSamplerParams {
+    terrainFieldStorage: TerrainFieldStorage;
+    spatialIndex: GpuSpatialIndexContext;
+    uniforms: TerrainUniformsContext;
+    elevationCallback: ElevationCallback;
+    /** Maximum quadtree level to probe during tile lookup. */
+    maxLevel: number;
+    projection?: TopologyProjection;
+}
+interface TerrainSample {
+    elevation: number;
+    normal: Vector3$1;
+    valid: boolean;
+}
+interface TerrainSampleBatch {
+    elevations: Float32Array;
+    normals: Float32Array;
+    valid: Uint8Array;
+    generation: number;
+}
+/**
+ * Result of sampling a cube-sphere surface from a direction/position/lat-long.
+ *
+ * `elevation` is the radial displacement above the base radius (already scaled
+ * by `elevationScale`); `position` is the full world-space surface point
+ * `center + direction * (radius + elevation)`.
+ */
+interface TerrainSurfaceSample {
+    position: Vector3$1;
+    normal: Vector3$1;
+    direction: Vector3$1;
+    elevation: number;
+    valid: boolean;
+}
+interface TerrainSurfaceSampleBatch {
+    positions: Float32Array;
+    normals: Float32Array;
+    elevations: Float32Array;
+    valid: Uint8Array;
+    generation: number;
+}
+interface TerrainTile {
+    /** Surface space index: 0 for flat terrain, 0..5 for cube-sphere faces. */
+    space: number;
+    level: number;
+    x: number;
+    y: number;
+    index: number;
+}
+interface TerrainTileBounds extends TerrainTile {
+    minElevation: number;
+    maxElevation: number;
+}
+interface ElevationRange {
+    min: number;
+    max: number;
+}
+/**
+ * Flat (heightfield) terrain query, keyed on world XZ. For cube-sphere
+ * surfaces use {@link TerrainSphereQuery} instead.
+ */
+interface TerrainQuery {
+    getElevation(worldX: number, worldZ: number): number | null;
+    getNormal(worldX: number, worldZ: number): Vector3$1 | null;
+    getTile(worldX: number, worldZ: number): TerrainTile | null;
+    getTileBounds(worldX: number, worldZ: number): TerrainTileBounds | null;
+    getGlobalElevationRange(): ElevationRange | null;
+    sampleTerrain(worldX: number, worldZ: number): TerrainSample;
+    sampleTerrainBatch(positions: Float32Array): TerrainSampleBatch;
+    readonly generation: number;
+}
+/**
+ * Cube-sphere terrain query. A surface location is identified by a direction
+ * from the planet center (the canonical form); `ByPosition` projects any world
+ * point onto its direction, and `ByLatLong` takes degrees (latitude
+ * `[-90, 90]`, longitude `[-180, 180]`). Elevation is the radial displacement
+ * above the base radius.
+ *
+ * Exposed only when the active surface uses the `cubeSphere` projection
+ * (otherwise `null` on the query context / runtime).
+ */
+interface TerrainSphereQuery {
+    readonly generation: number;
+    getElevationByDirection(direction: Vector3$1): number | null;
+    getElevationByPosition(position: Vector3$1): number | null;
+    getElevationByLatLong(latitudeDeg: number, longitudeDeg: number): number | null;
+    getNormalByDirection(direction: Vector3$1): Vector3$1 | null;
+    getNormalByPosition(position: Vector3$1): Vector3$1 | null;
+    getNormalByLatLong(latitudeDeg: number, longitudeDeg: number): Vector3$1 | null;
+    sampleTerrainByDirection(direction: Vector3$1): TerrainSurfaceSample;
+    sampleTerrainByPosition(position: Vector3$1): TerrainSurfaceSample;
+    sampleTerrainByLatLong(latitudeDeg: number, longitudeDeg: number): TerrainSurfaceSample;
+    getTileByDirection(direction: Vector3$1): TerrainTile | null;
+    getTileByPosition(position: Vector3$1): TerrainTile | null;
+    getTileByLatLong(latitudeDeg: number, longitudeDeg: number): TerrainTile | null;
+    getTileBoundsByDirection(direction: Vector3$1): TerrainTileBounds | null;
+    getTileBoundsByPosition(position: Vector3$1): TerrainTileBounds | null;
+    getTileBoundsByLatLong(latitudeDeg: number, longitudeDeg: number): TerrainTileBounds | null;
+    /** Batch sample; `directions` is a Float32Array of xyz triples. */
+    sampleTerrainBatchByDirection(directions: Float32Array): TerrainSurfaceSampleBatch;
+}
+interface RaycastOptions {
+    maxSteps?: number;
+    refinementSteps?: number;
+    maxDistance?: number;
+}
+interface TerrainRaycastResult {
+    position: Vector3$1;
+    normal: Vector3$1;
+    distance: number;
+}
+interface TerrainRaycast {
+    pick(ray: Ray, options?: RaycastOptions): TerrainRaycastResult | null;
+}
+
+type TerrainMeshParams = {
+    innerTileSegments: number;
+    maxNodes: number;
+    material: NodeMaterial;
+    /**
+     * Reverse tile triangle winding. Cube-sphere surfaces set this so the
+     * planet's outer shell is front-facing and renders with `FrontSide`.
+     */
+    flipWinding: boolean;
+};
+declare class TerrainMesh extends InstancedMesh {
+    private _innerTileSegments;
+    private _maxNodes;
+    private _flipWinding;
+    terrainRaycast: TerrainRaycast | null;
+    constructor(params?: Partial<TerrainMeshParams>);
+    get innerTileSegments(): number;
+    set innerTileSegments(tileSegments: number);
+    get flipWinding(): boolean;
+    set flipWinding(flip: boolean);
+    get maxNodes(): number;
+    set maxNodes(maxNodes: number);
+    raycast(raycaster: Raycaster, intersects: Intersection[]): void;
+}
+
+interface TileBoundsContext {
+    data: Float32Array<ArrayBuffer>;
+    attribute: StorageBufferAttribute;
+    node: StorageBufferNode;
+}
+
+type ComputeStageCallback = (nodeIndex: Node, globalVertexIndex: Node, uv: Node, localCoordinates: Node, texelSize: Node) => void;
+type ComputePipeline = ComputeStageCallback[];
+
+/**
+ * Default compile + execute tasks — uses terrainFieldStageTask as the leaf.
+ * Derived from the same factory as user pipelines to avoid duplicated logic.
+ */
+declare const compileComputeTask: _hello_terrain_work.Task<{
+    execute: (renderer: WebGPURenderer, instanceCount: number) => void;
+}, string, unknown>;
+declare const executeComputeTask: _hello_terrain_work.Task<any, string, {
+    renderer: WebGPURenderer;
+}>;
+/**
+ * Factory for user-extensible pipelines.
+ *
+ * Users who add custom compute stages create their own stage tasks using
+ * the accumulation pattern (`get()` predecessor, spread, append), then pass
+ * their leaf stage to this helper to get compile + execute tasks.
+ *
+ * @example
+ * ```ts
+ * const erosionStageTask = task((get, work) => {
+ *   const upstream = get(elevationFieldStageTask);
+ *   return work((): ComputePipeline => [
+ *     ...upstream,
+ *     (nodeIndex, globalVertexIndex, uv) => {
+ *       // custom erosion logic
+ *     },
+ *   ]);
+ * });
+ *
+ * const { compile, execute } = createComputePipelineTasks(erosionStageTask);
+ * ```
+ */
+declare function createComputePipelineTasks(leafStageTask: TaskRef<ComputePipeline>): {
+    compile: _hello_terrain_work.Task<{
+        execute: (renderer: WebGPURenderer, instanceCount: number) => void;
+    }, string, unknown>;
+    execute: _hello_terrain_work.Task<any, string, {
+        renderer: WebGPURenderer;
+    }>;
+};
+
+declare function createTileCompute(leafStorage: LeafStorageState, uniforms: TerrainUniformsContext, projection?: TopologyProjection): {
+    tileLevel: three_src_nodes_TSL_js.ShaderNodeFn<[number | Node]>;
+    tileFace: three_src_nodes_TSL_js.ShaderNodeFn<[number | Node]>;
+    tileOriginVec2: three_src_nodes_TSL_js.ShaderNodeFn<[number | Node]>;
+    tileSize: three_src_nodes_TSL_js.ShaderNodeFn<[number | Node]>;
+    tileFaceUV: three_src_nodes_TSL_js.ShaderNodeFn<[number | Node, number | Node, number | Node]>;
+    rootUVCompute: three_src_nodes_TSL_js.ShaderNodeFn<[number | Node, number | Node, number | Node]>;
+    tileVertexWorldPositionCompute: three_src_nodes_TSL_js.ShaderNodeFn<[number | Node, number | Node, number | Node]>;
+};
+
+type TerrainQueryConfig = {
+    rootSize: number;
+    originX: number;
+    originY: number;
+    originZ: number;
+    innerTileSegments: number;
+    elevationScale: number;
+    maxLevel: number;
+    /** Topology projection; `cubeSphere` enables the direction/lat-long queries. */
+    projection: TopologyProjection;
+    /** Sphere radius in world units (cube-sphere projection only). */
+    radius: number;
+};
+interface CpuTerrainCache {
+    readonly generation: number;
+    readonly ready: boolean;
+    updateConfig(config: TerrainQueryConfig): void;
+    triggerReadback(renderer: WebGPURenderer, attribute: StorageBufferAttribute, spatialIndex: SpatialIndex, boundsAttribute?: StorageBufferAttribute, activeLeafCount?: number): void;
+    getElevation(worldX: number, worldZ: number): number | null;
+    getNormal(worldX: number, worldZ: number): Vector3$1 | null;
+    getTile(worldX: number, worldZ: number): TerrainTile | null;
+    getTileBounds(worldX: number, worldZ: number): TerrainTileBounds | null;
+    getGlobalElevationRange(): ElevationRange | null;
+    sampleTerrainBatch(positions: Float32Array): TerrainSampleBatch;
+    sampleTerrain(worldX: number, worldZ: number): TerrainSample;
+    getElevationByDirection(direction: Vector3$1): number | null;
+    getElevationByPosition(position: Vector3$1): number | null;
+    getElevationByLatLong(latitudeDeg: number, longitudeDeg: number): number | null;
+    getNormalByDirection(direction: Vector3$1): Vector3$1 | null;
+    getNormalByPosition(position: Vector3$1): Vector3$1 | null;
+    getNormalByLatLong(latitudeDeg: number, longitudeDeg: number): Vector3$1 | null;
+    sampleTerrainByDirection(direction: Vector3$1): TerrainSurfaceSample;
+    sampleTerrainByPosition(position: Vector3$1): TerrainSurfaceSample;
+    sampleTerrainByLatLong(latitudeDeg: number, longitudeDeg: number): TerrainSurfaceSample;
+    getTileByDirection(direction: Vector3$1): TerrainTile | null;
+    getTileByPosition(position: Vector3$1): TerrainTile | null;
+    getTileByLatLong(latitudeDeg: number, longitudeDeg: number): TerrainTile | null;
+    getTileBoundsByDirection(direction: Vector3$1): TerrainTileBounds | null;
+    getTileBoundsByPosition(position: Vector3$1): TerrainTileBounds | null;
+    getTileBoundsByLatLong(latitudeDeg: number, longitudeDeg: number): TerrainTileBounds | null;
+    sampleTerrainBatchByDirection(directions: Float32Array): TerrainSurfaceSampleBatch;
+}
+
+interface QuadtreeConfigState {
+    state: QuadtreeState;
+    topology: Topology;
+}
+interface LeafGpuBufferState extends LeafStorageState {
+    count: number;
+}
+interface ElevationFieldContext {
+    data: Float32Array<ArrayBuffer>;
+    attribute: StorageBufferAttribute;
+    node: StorageBufferNode;
+}
+interface TerrainQueryContext {
+    cache: CpuTerrainCache;
+    query: TerrainQuery;
+    /** Cube-sphere query; `null` unless the topology uses the cubeSphere projection. */
+    sphereQuery: TerrainSphereQuery | null;
+    shapeKey: string;
+}
+/** Task refs for the standard terrain pipeline. */
+interface TerrainTasks {
+    instanceId: TaskRef<string>;
+    quadtreeConfig: TaskRef<QuadtreeConfigState>;
+    quadtreeUpdate: TaskRef<LeafSet>;
+    topology: TaskRef<Topology>;
+    leafStorage: TaskRef<LeafStorageState>;
+    leafGpuBuffer: TaskRef<LeafGpuBufferState>;
+    gpuSpatialIndexStorage: TaskRef<GpuSpatialIndexContext>;
+    gpuSpatialIndexUpload: TaskRef<GpuSpatialIndexContext>;
+    createUniforms: TaskRef<TerrainUniformsContext>;
+    updateUniforms: TaskRef<TerrainUniformsContext>;
+    positionNode: TaskRef<ShaderCallNodeInternal>;
+    createElevationFieldContext: TaskRef<ElevationFieldContext>;
+    createTileNodes: TaskRef<ReturnType<typeof createTileCompute>>;
+    createTerrainFieldTexture: TaskRef<TerrainFieldStorage>;
+    createTerrainSampler: TaskRef<TerrainSampler>;
+    elevationFieldStage: TaskRef<ComputePipeline>;
+    terrainFieldStage: TaskRef<ComputePipeline>;
+    compileCompute: TaskRef<{
+        execute: (renderer: WebGPURenderer, instanceCount: number) => void;
+    }>;
+    executeCompute: TaskRef<void | (() => void)>;
+    tileBoundsContext: TaskRef<TileBoundsContext & {
+        kernel: unknown;
+    }>;
+    tileBoundsReduction: TaskRef<TileBoundsContext>;
+    terrainQuery: TaskRef<TerrainQueryContext>;
+    terrainReadback: TaskRef<void>;
+    terrainRaycast: TaskRef<TerrainRaycast>;
+}
+type TerrainGraph = Graph<string, {
+    renderer: WebGPURenderer;
+}>;
+
+declare const createElevationFieldContextTask: _hello_terrain_work.Task<{
+    data: Float32Array<ArrayBuffer>;
+    attribute: StorageBufferAttribute;
+    node: three_webgpu.StorageBufferNode;
+}, string, unknown>;
+declare const tileNodesTask: _hello_terrain_work.Task<{
+    tileLevel: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node]>;
+    tileFace: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node]>;
+    tileOriginVec2: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node]>;
+    tileSize: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node]>;
+    tileFaceUV: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node, number | three_webgpu.Node, number | three_webgpu.Node]>;
+    rootUVCompute: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node, number | three_webgpu.Node, number | three_webgpu.Node]>;
+    tileVertexWorldPositionCompute: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node, number | three_webgpu.Node, number | three_webgpu.Node]>;
+}, string, unknown>;
+/**
+ * Root compute stage — generates elevation data and writes to the
+ * elevation field storage buffer. Returns a single-element `ComputePipeline`.
+ */
+declare const elevationFieldStageTask: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
+
+declare const gpuSpatialIndexStorageTask: _hello_terrain_work.Task<GpuSpatialIndexContext, string, unknown>;
+declare const gpuSpatialIndexUploadTask: _hello_terrain_work.Task<GpuSpatialIndexContext, string, unknown>;
+
+/** Generates a unique instance ID per graph (cached once). */
+declare const instanceIdTask: _hello_terrain_work.Task<`${string}-${string}-${string}-${string}-${string}`, string, unknown>;
+
+declare const createTerrainFieldTextureTask: _hello_terrain_work.Task<any, string, {
+    renderer: WebGPURenderer;
+}>;
+/**
+ * Normal field compute stage — reads height neighbors from the elevation field
+ * buffer, computes surface normals via central differences, packs XZ
+ * components into a u32 via `packHalf2x16`, and writes to the normal field
+ * storage buffer.
+ *
+ * Accumulates the upstream elevation pipeline via `get(elevationFieldStageTask)`.
+ */
+declare const terrainFieldStageTask: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
+
+declare const createTerrainSamplerTask: _hello_terrain_work.Task<TerrainSampler, string, unknown>;
+
+declare const terrainQueryTask: _hello_terrain_work.Task<TerrainQueryContext, string, unknown>;
+declare const terrainReadbackTask: _hello_terrain_work.Task<any, string, {
+    renderer: WebGPURenderer;
+}>;
+
+declare const terrainRaycastTask: _hello_terrain_work.Task<TerrainRaycast, string, unknown>;
+
+/** Root tile size in world units. */
+declare const rootSize: _hello_terrain_work.ParamRef<number>;
+/** World-space origin of the terrain. */
+declare const origin: _hello_terrain_work.ParamRef<{
+    x: number;
+    y: number;
+    z: number;
+}>;
+/**
+ * Default number of segments per inner tile edge. The effective edge vertex
+ * count is `innerTileSegments + 3`
+ */
+declare const innerTileSegments: _hello_terrain_work.ParamRef<number>;
+/** Skirt scale factor. */
+declare const skirtScale: _hello_terrain_work.ParamRef<number>;
+/** Elevation vertical scale. */
+declare const elevationScale: _hello_terrain_work.ParamRef<number>;
+/** Sphere radius in world units (cube-sphere projection only). */
+declare const radius: _hello_terrain_work.ParamRef<number>;
+/** Maximum quadtree nodes. */
+declare const maxNodes: _hello_terrain_work.ParamRef<number>;
+/** Maximum quadtree subdivision level. */
+declare const maxLevel: _hello_terrain_work.ParamRef<number>;
+/** Quadtree update configuration (camera, mode, etc.). */
+declare const quadtreeUpdate: _hello_terrain_work.ParamRef<UpdateParams>;
+/** Optional custom terrain topology; defaults to bounded flat topology when null. */
+declare const topology: _hello_terrain_work.ParamRef<Topology | null>;
+/** Terrain field texture filter mode. */
+declare const terrainFieldFilter: _hello_terrain_work.ParamRef<"nearest" | "linear">;
+/** Terrain elevation control function (per vertex, in gpu compute) */
+declare const elevationFn: _hello_terrain_work.ParamRef<ElevationCallback>;
+
+/**
+ * Builds the TSL position node for the terrain shader.
+ *
+ * Depends on leafStorageTask (buffer objects), updateUniformsTask
+ * (uniform nodes), and createTerrainFieldTextureTask (combined terrain field storage).
+ *
+ * The position node reads packed terrain samples (height + normal.xz)
+ * per-vertex and assigns them to the vNormal
+ * varying for use in the fragment shader.
+ *
+ * These only change when their GPU resources are recreated
+ * (e.g. buffer resize), so this task stays cached during normal quadtree
+ * updates — no unnecessary shader rebuilds.
+ */
+declare const positionNodeTask: _hello_terrain_work.Task<three_src_nodes_TSL_js.ShaderCallNodeInternal, string, unknown>;
+
+/**
+ * Derives the terrain topology from `rootSize` and `origin`.
+ * Automatically recomputes when either param changes, keeping the
+ * quadtree refinement in sync with the GPU-side tile positioning.
+ */
+declare const topologyTask: _hello_terrain_work.Task<Topology, string, unknown>;
+declare const quadtreeConfigTask: _hello_terrain_work.Task<QuadtreeConfigState, string, unknown>;
+declare const quadtreeUpdateTask: _hello_terrain_work.Task<LeafSet, string, unknown>;
+/**
+ * Creates the GPU storage buffer objects. Recreated when maxNodes changes.
+ *
+ * positionNodeTask depends on this (not leafGpuBufferTask) so
+ * the shader is only rebuilt when the buffer is resized, not on every
+ * quadtree update.
+ */
+declare const leafStorageTask: _hello_terrain_work.Task<LeafStorageState, string, unknown>;
+declare const leafGpuBufferTask: _hello_terrain_work.Task<{
+    count: number;
+    data: Int32Array<ArrayBuffer>;
+    attribute: three_webgpu.StorageBufferAttribute;
+    node: three_webgpu.StorageBufferNode;
+}, string, unknown>;
+
+declare function createTerrainUniforms(params: TerrainUniformsParams): TerrainUniformsContext;
+
+/**
+ * Creates the terrain uniform nodes once. Downstream tasks capture
+ * references to these nodes in shader graphs, so the same instances
+ * must persist across runs.
+ */
+declare const createUniformsTask: _hello_terrain_work.Task<TerrainUniformsContext, string, unknown>;
+/**
+ * Updates the terrain uniform values each run. Reads the persisted uniform
+ * nodes from createUniformsTask and writes the latest param values.
+ */
+declare const updateUniformsTask: _hello_terrain_work.Task<TerrainUniformsContext, string, unknown>;
+
+/** All terrain task refs for direct access. */
+declare const terrainTasks: {
+    readonly instanceId: _hello_terrain_work.Task<`${string}-${string}-${string}-${string}-${string}`, string, unknown>;
+    readonly quadtreeConfig: _hello_terrain_work.Task<QuadtreeConfigState, string, unknown>;
+    readonly quadtreeUpdate: _hello_terrain_work.Task<LeafSet, string, unknown>;
+    readonly leafStorage: _hello_terrain_work.Task<LeafStorageState, string, unknown>;
+    readonly topology: _hello_terrain_work.Task<Topology, string, unknown>;
+    readonly leafGpuBuffer: _hello_terrain_work.Task<{
+        count: number;
+        data: Int32Array<ArrayBuffer>;
+        attribute: three_webgpu.StorageBufferAttribute;
+        node: three_webgpu.StorageBufferNode;
+    }, string, unknown>;
+    readonly gpuSpatialIndexStorage: _hello_terrain_work.Task<GpuSpatialIndexContext, string, unknown>;
+    readonly gpuSpatialIndexUpload: _hello_terrain_work.Task<GpuSpatialIndexContext, string, unknown>;
+    readonly createUniforms: _hello_terrain_work.Task<TerrainUniformsContext, string, unknown>;
+    readonly updateUniforms: _hello_terrain_work.Task<TerrainUniformsContext, string, unknown>;
+    readonly positionNode: _hello_terrain_work.Task<three_src_nodes_TSL_js.ShaderCallNodeInternal, string, unknown>;
+    readonly createElevationFieldContext: _hello_terrain_work.Task<{
+        data: Float32Array<ArrayBuffer>;
+        attribute: three_webgpu.StorageBufferAttribute;
+        node: three_webgpu.StorageBufferNode;
+    }, string, unknown>;
+    readonly createTileNodes: _hello_terrain_work.Task<{
+        tileLevel: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node]>;
+        tileFace: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node]>;
+        tileOriginVec2: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node]>;
+        tileSize: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node]>;
+        tileFaceUV: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node, number | three_webgpu.Node, number | three_webgpu.Node]>;
+        rootUVCompute: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node, number | three_webgpu.Node, number | three_webgpu.Node]>;
+        tileVertexWorldPositionCompute: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node, number | three_webgpu.Node, number | three_webgpu.Node]>;
+    }, string, unknown>;
+    readonly createTerrainFieldTexture: _hello_terrain_work.Task<any, string, {
+        renderer: WebGPURenderer;
+    }>;
+    readonly createTerrainSampler: _hello_terrain_work.Task<TerrainSampler, string, unknown>;
+    readonly elevationFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
+    readonly terrainFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
+    readonly compileCompute: _hello_terrain_work.Task<{
+        execute: (renderer: WebGPURenderer, instanceCount: number) => void;
+    }, string, unknown>;
+    readonly executeCompute: _hello_terrain_work.Task<any, string, {
+        renderer: WebGPURenderer;
+    }>;
+    readonly tileBoundsContext: _hello_terrain_work.Task<TileBoundsContext & {
+        kernel: ReturnType<(elevationFieldNode: three_webgpu.StorageBufferNode, boundsNode: three_webgpu.StorageBufferNode, verticesPerNode: number) => three_webgpu.ComputeNode>;
+    }, string, unknown>;
+    readonly tileBoundsReduction: _hello_terrain_work.Task<any, string, {
+        renderer: WebGPURenderer;
+    }>;
+    readonly terrainQuery: _hello_terrain_work.Task<TerrainQueryContext, string, unknown>;
+    readonly terrainReadback: _hello_terrain_work.Task<any, string, {
+        renderer: WebGPURenderer;
+    }>;
+    readonly terrainRaycast: _hello_terrain_work.Task<TerrainRaycast, string, unknown>;
+};
+declare function terrainGraph(): TerrainGraph;
+
+type ComputeDeviceLimits = {
+    maxWorkgroupSizeX: number;
+    maxWorkgroupSizeY: number;
+    maxWorkgroupInvocations: number;
+};
+declare function getDeviceComputeLimits(renderer: WebGPURenderer): ComputeDeviceLimits;
+
+declare function createTerrainSampler(params: CreateTerrainSamplerParams): TerrainSampler;
+
+/** Flat (heightfield) query, keyed on world XZ. */
+declare function createTerrainQuery(cache: CpuTerrainCache): TerrainQuery;
+/** Cube-sphere query, keyed on a direction / position / lat-long. */
+declare function createTerrainSphereQuery(cache: CpuTerrainCache): TerrainSphereQuery;
+
+type CpuRaycastConfig = {
+    rootSize: number;
+    originX: number;
+    originZ: number;
+    minY: number;
+    maxY: number;
+    /** Topology projection; `cubeSphere` selects the radial sphere raycast. */
+    projection?: TopologyProjection;
+    /** Planet center (cube-sphere only). */
+    centerX?: number;
+    centerY?: number;
+    centerZ?: number;
+    /** Base sphere radius (cube-sphere only). */
+    radius?: number;
+    /** Inner/outer radial bounds of the terrain shell (cube-sphere only). */
+    minRadius?: number;
+    maxRadius?: number;
+};
+
+type TerrainRaycastConfig = CpuRaycastConfig;
+declare function createTerrainRaycast(params: {
+    getTerrainQuery: () => TerrainQuery | null;
+    getSphereQuery: () => TerrainSphereQuery | null;
+    getConfig: () => TerrainRaycastConfig;
+}): TerrainRaycast;
+
+type CubeFaceBasis = {
+    forward: Node;
+    right: Node;
+    up: Node;
+};
+/** Per-face basis vectors selected by the dynamic face index. */
+declare function cubeFaceBasis(face: Node): CubeFaceBasis;
+/**
+ * Cube-space point for face-local (u, v) in [0, 1]:
+ *   cube = forward + (2u-1) * right + (2v-1) * up
+ */
+declare function cubeFacePoint(basis: CubeFaceBasis, u: Node, v: Node): Node;
+/** Unit-sphere direction for face-local (u, v). */
+declare function cubeFaceDirection(basis: CubeFaceBasis, u: Node, v: Node): Node;
+/**
+ * Project a basis axis onto the tangent plane at `dir` and normalize.
+ * Used to build the sphere tangent frame for normal reconstruction.
+ */
+declare function tangentFromAxis(dir: Node, axis: Node): Node;
+/**
+ * Reconstruct a unit tangent-space normal from its packed horizontal
+ * components: `ny = sqrt(max(0, 1 - nx² - nz²))`.
+ */
+declare function unpackTangentNormal(nx: Node, nz: Node): Node;
+/**
+ * Rotate a tangent-space normal into the sphere tangent frame
+ * `(tu, dir, tv)` at `dir` and normalize.
+ *
+ * Mirrors: the CPU `computeSphereNormal` in `query/cpu-terrain-cache.ts`.
+ */
+declare function sphereTangentFrameNormal(dir: Node, basis: CubeFaceBasis, tangentNormal: Node): Node;
+/**
+ * Pick the cube face index (0..5) whose normal axis dominates `dir`.
+ * GPU mirror of `directionToFace` in `quadtree/topology/cubeSphereInverse.ts`.
+ */
+declare function cubeFaceFromDirection(dir: Node): Node;
+/**
+ * Face-local (u, v) in [0, 1] for a direction known to fall on `face`.
+ * GPU mirror of `directionToFaceUV` in `quadtree/topology/cubeSphereInverse.ts`.
+ */
+declare function cubeFaceUVFromDirection(basis: CubeFaceBasis, dir: Node): Node;
+
+/**
+ * Maps a value or node from texture space [0, 1] to vector space [-1, 1].
+ *
+ * @param value - The node or value in the range [0, 1].
+ * @returns A node mapping the input value to the range [-1, 1].
+ */
+declare const textureSpaceToVectorSpace: three_src_nodes_TSL_js.ShaderNodeFn<[number | Node$1]>;
+/**
+ * Maps a value or node from vector space [-1, 1] to texture space [0, 1].
+ *
+ * @param value - The node or value in the range [-1, 1].
+ * @returns A node mapping the input value to the range [0, 1].
+ */
+declare const vectorSpaceToTextureSpace: three_src_nodes_TSL_js.ShaderNodeFn<[number | Node$1]>;
+/**
+ * Blends two normal maps using the Reoriented Normal Mapping technique.
+ * This is the same algorithm used by Unreal Engine's BlendAngleCorrectedNormals node.
+ *
+ * Both inputs should be in vector space [-1, 1].
+ *
+ * @see https://blog.selfshadow.com/publications/blending-in-detail/
+ */
+declare const blendAngleCorrectedNormals: three_src_nodes_TSL_js.ShaderNodeFn<[number | Node$1, number | Node$1]>;
+/**
+ * Reconstructs the Z component of a normal from the X and Y components.
+ *
+ * @param normalXY - A vec2 containing the X and Y components of the normal
+ * @returns A vec3 with the reconstructed normal (X, Y, derived Z)
+ */
+declare const deriveNormalZ: three_src_nodes_TSL_js.ShaderNodeFn<[number | Node$1]>;
+
+/**
+ * Input type for segment count: either a JS number or a TSL integer node.
+ * When a number is provided, it's automatically converted to an int node.
+ * When a Node is provided, it should resolve to an integer value.
+ */
+type IntNodeInput = number | ConstNode<number> | Node;
 /**
  * Returns a node that is true for skirt vertices in the vertex stage.
  *
@@ -113,4 +1149,15 @@ declare const isSkirtVertex: three_src_nodes_TSL_js.ShaderNodeFn<[segments: numb
  */
 declare const isSkirtUV: three_src_nodes_TSL_js.ShaderNodeFn<[segments: number | Node]>;
 
-export { TerrainGeometry, isSkirtUV, isSkirtVertex };
+declare const vGlobalVertexIndex: three_webgpu.PropertyNode;
+declare const vElevation: three_webgpu.PropertyNode;
+
+declare const voronoiCells: three_src_nodes_TSL_js.ShaderNodeFn<[three_tsl.ProxiedObject<{
+    scale: number;
+    facet: number;
+    seed: number;
+    uv: Node;
+}>]>;
+
+export { ArrayTextureBackend, AtlasBackend, CUBE_FACES, CUBE_FACE_COUNT, Dir, TerrainGeometry, TerrainMesh, U32_EMPTY, allocLeafSet, allocSeamTable, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, compileComputeTask, createComputePipelineTasks, createCubeSphereTopology, createElevationFieldContextTask, createFlatTopology, createInfiniteFlatTopology, createSpatialIndex, createState, createTerrainFieldStorage, createTerrainFieldTextureTask, createTerrainQuery, createTerrainRaycast, createTerrainSampler, createTerrainSamplerTask, createTerrainSphereQuery, createTerrainUniforms, createUniformsTask, cubeFaceBasis, cubeFaceDirection, cubeFaceFromDirection, cubeFacePoint, cubeFaceUVFromDirection, deriveNormalZ, directionToFace, directionToFaceUV, directionToLatLong, elevationFieldStageTask, elevationFn, elevationScale, executeComputeTask, faceUVToCube, getDeviceComputeLimits, gpuSpatialIndexStorageTask, gpuSpatialIndexUploadTask, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, latLongToDirection, leafGpuBufferTask, leafStorageTask, loadTerrainField, loadTerrainFieldElevation, loadTerrainFieldNormal, maxLevel, maxNodes, origin, packTerrainFieldSample, positionNodeTask, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, radius, resetLeafSet, resetSeamTable, rootSize, sampleTerrainField, sampleTerrainFieldElevation, skirtScale, sphereTangentFrameNormal, storeTerrainField, tangentFromAxis, terrainFieldFilter, terrainFieldStageTask, terrainGraph, terrainQueryTask, terrainRaycastTask, terrainReadbackTask, terrainTasks, textureSpaceToVectorSpace, tileNodesTask, topology, topologyTask, unpackTangentNormal, update, updateUniformsTask, vElevation, vGlobalVertexIndex, vectorSpaceToTextureSpace, voronoiCells };
+export type { ComputePipeline, ComputeStageCallback, CreateTerrainSamplerParams, CubeFace, CubeFaceBasis, CubeSphereTopologyConfig, ElevationCallback, ElevationFieldContext, ElevationParams, ElevationRange, FlatTopologyConfig, GpuSpatialIndexContext, InfiniteFlatTopologyConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodMode, QuadtreeConfig, QuadtreeConfigState, QuadtreeState, RaycastOptions, SeamTable, SpatialIndex, TerrainFieldStorage, TerrainFieldStorageBackendType, TerrainFieldStorageFormat, TerrainFieldStorageOptions, TerrainGraph, TerrainQuery, TerrainQueryContext, TerrainRaycast, TerrainRaycastConfig, TerrainRaycastResult, TerrainSample, TerrainSampleBatch, TerrainSampler, TerrainSphereQuery, TerrainSurfaceSample, TerrainSurfaceSampleBatch, TerrainTasks, TerrainTile, TerrainTileBounds, TerrainUniformsContext, TerrainUniformsParams, TileBounds, TileId, Topology, TopologyProjection, UpdateParams, Vec3, Vec3Mutable };