@hello-terrain/three 0.0.0-alpha.4 → 0.0.0-alpha.5

package/dist/index.d.mts

@@ -1,11 +1,12 @@
 import { BufferGeometry } from 'three';
 import * as three_webgpu from 'three/webgpu';
-import { InstancedMesh, NodeMaterial, ConstNode, Node as Node$1, StorageBufferAttribute, StorageBufferNode, UniformNode, Vector3, Vector3Like } from 'three/webgpu';
+import { InstancedMesh, NodeMaterial, Node, WebGPURenderer, StorageBufferAttribute, StorageBufferNode, UniformNode, Vector3, Vector3Like, ConstNode } from 'three/webgpu';
 import * as three_src_nodes_TSL_js from 'three/src/nodes/TSL.js';
 import { ShaderCallNodeInternal } from 'three/src/nodes/TSL.js';
-import Node from 'three/src/nodes/core/Node.js';
 import * as _hello_terrain_work from '@hello-terrain/work';
 import { TaskRef } from '@hello-terrain/work';
+import Node$1 from 'three/src/nodes/core/Node.js';
+import * as three_tsl from 'three/tsl';
 
 /**
  * Custom geometry for terrain tiles with properly handled skirts.
@@ -108,67 +109,47 @@ declare class TerrainMesh extends InstancedMesh {
     set maxNodes(maxNodes: number);
 }
 
-/**
- * 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]>;
-/**
- * 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]>;
-/**
- * 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, number | Node]>;
-/**
- * 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]>;
+type ComputeStageCallback = (nodeIndex: Node, globalVertexIndex: Node, uv: Node, localCoordinates: Node, texelSize: Node) => void;
+type ComputePipeline = ComputeStageCallback[];
 
+/** Default compile task — uses normalFieldStageTask as the leaf. */
+declare const compileComputeTask: _hello_terrain_work.Task<{
+    execute: (renderer: WebGPURenderer, instanceCount: number) => void;
+}, string, unknown>;
+/** Default execute task — dispatches the compiled kernel. */
+declare const executeComputeTask: _hello_terrain_work.Task<any, string, {
+    renderer: WebGPURenderer;
+}>;
 /**
- * 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$1;
-/**
- * Returns a node that is true for skirt vertices in the vertex stage.
+ * Factory for user-extensible pipelines.
  *
- * @remarks
- * Only valid in the vertex shader. A vertex belongs to the skirt if it is on
- * the outermost ring of the tile grid (first/last column or row). The grid
- * resolution is derived from `segments`.
+ * 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.
  *
- * @param segments - The number of inner segments in the terrain grid.
- * @returns A node resolving to a boolean indicating a skirt vertex.
- */
-declare const isSkirtVertex: three_src_nodes_TSL_js.ShaderNodeFn<[segments: number | Node$1]>;
-/**
- * Returns a node that is true for skirt UVs.
- *
- * @remarks
- * Uses interpolated UVs and the grid size
- * from `segments` to mark fragments outside the inner range
- * `(step, 1 - step)` on either axis as skirt, where `step = 1 / (segments + 2)`.
+ * @example
+ * ```ts
+ * const erosionStageTask = task((get, work) => {
+ *   const upstream = get(elevationFieldStageTask);
+ *   return work((): ComputePipeline => [
+ *     ...upstream,
+ *     (nodeIndex, globalVertexIndex, uv) => {
+ *       // custom erosion logic
+ *     },
+ *   ]);
+ * });
  *
- * @param segments - The number of inner segments in the terrain grid.
- * @returns A node resolving to a boolean indicating a skirt fragment.
+ * const { compile, execute } = createComputePipelineTasks(erosionStageTask);
+ * ```
  */
-declare const isSkirtUV: three_src_nodes_TSL_js.ShaderNodeFn<[segments: number | Node$1]>;
+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 const Dir: {
     readonly LEFT: 0;
@@ -182,7 +163,9 @@ 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 = {
@@ -195,6 +178,8 @@ type TileBounds = {
 };
 type Surface = {
     spaceCount: number;
+    /** maximum number of roots returned by `rootTiles` */
+    maxRootCount: number;
     /**
      * Compute the same-level neighbor TileId in the requested direction.
      * Returns false if the neighbor is outside the valid topology.
@@ -211,6 +196,15 @@ type Surface = {
         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 */
@@ -219,8 +213,8 @@ type LeafSet = {
     count: number;
     space: Uint8Array;
     level: Uint8Array;
-    x: Uint32Array;
-    y: Uint32Array;
+    x: Int32Array;
+    y: Int32Array;
 };
 declare function allocLeafSet(capacity: number): LeafSet;
 declare function resetLeafSet(leaves: LeafSet): void;
@@ -278,8 +272,8 @@ type NodeStore = {
     gen: Uint16Array;
     space: Uint8Array;
     level: Uint8Array;
-    x: Uint32Array;
-    y: Uint32Array;
+    x: Int32Array;
+    y: Int32Array;
     /** sentinel U32_EMPTY means no children; otherwise children are [firstChild..firstChild+3] */
     firstChild: Uint32Array;
     flags: Uint8Array;
@@ -319,6 +313,9 @@ type QuadtreeState = {
     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;
@@ -327,11 +324,12 @@ type QuadtreeState = {
     scratchTile: TileId;
     scratchNeighbor: TileId;
     scratchBounds: TileBounds;
+    scratchRootTiles: TileId[];
     /** surface space count is fixed for a given state */
     spaceCount: number;
 };
 declare function createState(cfg: QuadtreeConfig, surface: Surface): QuadtreeState;
-declare function beginUpdate(state: QuadtreeState, surface: Surface): void;
+declare function beginUpdate(state: QuadtreeState, surface: Surface, params: UpdateParams): void;
 
 /**
  * Update the quadtree for the given surface + camera parameters.
@@ -364,6 +362,20 @@ type FlatSurfaceConfig = {
 };
 declare function createFlatSurface(cfg: FlatSurfaceConfig): Surface;
 
+type InfiniteFlatSurfaceConfig = {
+    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 createInfiniteFlatSurface(cfg: InfiniteFlatSurfaceConfig): Surface;
+
 type CubeSphereSurfaceConfig = {
     radius: number;
     maxHeight?: number;
@@ -376,41 +388,12 @@ type CubeSphereSurfaceConfig = {
  */
 declare function createCubeSphereSurface(_cfg: CubeSphereSurfaceConfig): Surface;
 
-interface LeafStorageState {
-    data: Int32Array<ArrayBuffer>;
-    attribute: StorageBufferAttribute;
-    node: StorageBufferNode;
-}
-declare const quadtreeConfigTask: _hello_terrain_work.Task<{
-    state: QuadtreeState;
-    surface: Surface;
-}, string, unknown>;
-declare const quadtreeUpdateTask: _hello_terrain_work.Task<LeafSet, string, unknown>;
-/**
- * Creates the GPU storage buffer objects. Recreated when maxNodes changes.
- *
- * terrainVertextPositionNodeTask 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<{
-    data: Int32Array<ArrayBuffer>;
-    attribute: StorageBufferAttribute;
-    node: StorageBufferNode;
-}, string, unknown>;
-declare const leafGpuBufferTask: _hello_terrain_work.Task<{
-    count: number;
-    data: Int32Array<ArrayBuffer>;
-    attribute: StorageBufferAttribute;
-    node: StorageBufferNode;
-}, string, unknown>;
-
 interface TerrainUniformsParams {
     rootSize: number;
     rootOrigin: Vector3Like;
     innerTileSegments: number;
     skirtScale: number;
-    heightmapScale: number;
+    elevationScale: number;
     instanceId: string;
 }
 interface TerrainUniformsContext {
@@ -418,56 +401,109 @@ interface TerrainUniformsContext {
     uRootSize: UniformNode<number>;
     uInnerTileSegments: UniformNode<number>;
     uSkirtScale: UniformNode<number>;
-    uHeightmapScale: UniformNode<number>;
+    uElevationScale: UniformNode<number>;
+}
+interface LeafStorageState {
+    data: Int32Array<ArrayBuffer>;
+    attribute: StorageBufferAttribute;
+    node: StorageBufferNode;
 }
-/**
- * Factory function for instance-specific uniforms for a TerrainMesh.
- * Each TerrainMesh gets its own set of uniforms to avoid global state conflicts.
- */
-declare function createTerrainUniforms(params: TerrainUniformsParams): TerrainUniformsContext;
-
-declare function createTileWorldPosition(leafStorage: LeafStorageState, terrainUniforms: TerrainUniformsContext): three_src_nodes_TSL_js.ShaderCallNodeInternal;
-
-/** Generates a unique instance ID per graph (cached once). */
-declare const instanceIdTask: _hello_terrain_work.Task<`${string}-${string}-${string}-${string}-${string}`, string, unknown>;
 
-declare function terrainGraph(): _hello_terrain_work.Graph<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<{
-        state: QuadtreeState;
-        surface: Surface;
-    }, string, unknown>;
-    readonly quadtreeUpdate: _hello_terrain_work.Task<LeafSet, string, unknown>;
-    readonly leafStorage: _hello_terrain_work.Task<{
-        data: Int32Array<ArrayBuffer>;
-        attribute: three_webgpu.StorageBufferAttribute;
-        node: three_webgpu.StorageBufferNode;
-    }, string, unknown>;
-    readonly leafGpuBuffer: _hello_terrain_work.Task<{
-        count: number;
-        data: Int32Array<ArrayBuffer>;
-        attribute: three_webgpu.StorageBufferAttribute;
-        node: three_webgpu.StorageBufferNode;
-    }, 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>;
+declare function createTileCompute(leafStorage: LeafStorageState, uniforms: TerrainUniformsContext): {
+    tileLevel: 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]>;
+    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]>;
 };
 
+interface QuadtreeConfigState {
+    state: QuadtreeState;
+    surface: Surface;
+}
+interface LeafGpuBufferState extends LeafStorageState {
+    count: number;
+}
+interface ElevationFieldContext {
+    data: Float32Array<ArrayBuffer>;
+    attribute: StorageBufferAttribute;
+    node: StorageBufferNode;
+}
+interface NormalFieldContext {
+    data: Uint32Array<ArrayBuffer>;
+    attribute: StorageBufferAttribute;
+    node: StorageBufferNode;
+}
 /** Task refs for the standard terrain pipeline. */
 interface TerrainTasks {
     instanceId: TaskRef<string>;
-    quadtreeConfig: TaskRef<any>;
-    quadtreeUpdate: TaskRef<any>;
+    quadtreeConfig: TaskRef<QuadtreeConfigState>;
+    quadtreeUpdate: TaskRef<LeafSet>;
+    surface: TaskRef<Surface>;
     leafStorage: TaskRef<LeafStorageState>;
-    leafGpuBuffer: TaskRef<any>;
+    leafGpuBuffer: TaskRef<LeafGpuBufferState>;
     createUniforms: TaskRef<TerrainUniformsContext>;
     updateUniforms: TaskRef<TerrainUniformsContext>;
     positionNode: TaskRef<ShaderCallNodeInternal>;
+    createElevationFieldContext: TaskRef<ElevationFieldContext>;
+    createTileNodes: TaskRef<ReturnType<typeof createTileCompute>>;
+    createNormalFieldContext: TaskRef<NormalFieldContext>;
+    elevationFieldStage: TaskRef<ComputePipeline>;
+    normalFieldStage: TaskRef<ComputePipeline>;
+    compileCompute: TaskRef<{
+        execute: (renderer: WebGPURenderer, instanceCount: number) => void;
+    }>;
+    executeCompute: TaskRef<void | (() => void)>;
 }
 
+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]>;
+    tileOriginVec2: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node]>;
+    tileSize: three_src_nodes_TSL_js.ShaderNodeFn<[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>;
+
+/** 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 createNormalFieldContextTask: _hello_terrain_work.Task<{
+    data: Uint32Array<ArrayBuffer>;
+    attribute: StorageBufferAttribute;
+    node: three_webgpu.StorageBufferNode;
+}, string, unknown>;
+/**
+ * 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 normalFieldStageTask: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
+
+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;
+
 /** Root tile size in world units. */
 declare const rootSize: _hello_terrain_work.ParamRef<number>;
 /** World-space origin of the terrain. */
@@ -476,29 +512,71 @@ declare const origin: _hello_terrain_work.ParamRef<{
     y: number;
     z: number;
 }>;
-/** Number of segments per inner tile edge. */
+/**
+ * Number of segments per inner tile edge.
+ * 13 is the max tiles we can support for 256 workgroups (13 + 3 === 16.. 16x16)
+ */
 declare const innerTileSegments: _hello_terrain_work.ParamRef<number>;
 /** Skirt scale factor. */
 declare const skirtScale: _hello_terrain_work.ParamRef<number>;
-/** Heightmap vertical scale. */
-declare const heightmapScale: _hello_terrain_work.ParamRef<number>;
+/** Elevation vertical scale. */
+declare const elevationScale: _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 surface; defaults to bounded flat surface when null. */
+declare const surface: _hello_terrain_work.ParamRef<Surface | null>;
+/** 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) and createUniformsTask
- * (uniform nodes). Both only change when their GPU resources are recreated
+ * Depends on leafStorageTask (buffer objects), createUniformsTask
+ * (uniform nodes), createElevationFieldContextTask (elevation field storage),
+ * and createNormalFieldContextTask (normal field storage).
+ *
+ * The position node also reads normals from the normal field buffer
+ * per-vertex (using vertexIndex) 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 surface from `rootSize` and `origin`.
+ * Automatically recomputes when either param changes, keeping the
+ * quadtree refinement in sync with the GPU-side tile positioning.
+ */
+declare const surfaceTask: _hello_terrain_work.Task<Surface, string, unknown>;
+declare const quadtreeConfigTask: _hello_terrain_work.Task<{
+    state: QuadtreeState;
+    surface: Surface;
+}, 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
@@ -511,5 +589,126 @@ declare const createUniformsTask: _hello_terrain_work.Task<TerrainUniformsContex
  */
 declare const updateUniformsTask: _hello_terrain_work.Task<TerrainUniformsContext, string, unknown>;
 
-export { Dir, TerrainGeometry, TerrainMesh, U32_EMPTY, allocLeafSet, allocSeamTable, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, createCubeSphereSurface, createFlatSurface, createSpatialIndex, createState, createTerrainUniforms, createTileWorldPosition, createUniformsTask, deriveNormalZ, heightmapScale, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, leafGpuBufferTask, leafStorageTask, maxLevel, maxNodes, origin, positionNodeTask, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, resetLeafSet, resetSeamTable, rootSize, skirtScale, terrainGraph, terrainTasks, textureSpaceToVectorSpace, update, updateUniformsTask, vectorSpaceToTextureSpace };
-export type { CubeSphereSurfaceConfig, FlatSurfaceConfig, IntNodeInput, LeafSet, LeafStorageState, LodMode, QuadtreeConfig, QuadtreeState, SeamTable, SpatialIndex, Surface, TerrainTasks, TerrainUniformsContext, TerrainUniformsParams, TileBounds, TileId, UpdateParams };
+declare function terrainGraph(): _hello_terrain_work.Graph<string, {
+    renderer: WebGPURenderer;
+}>;
+/** 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<{
+        state: QuadtreeState;
+        surface: Surface;
+    }, string, unknown>;
+    readonly quadtreeUpdate: _hello_terrain_work.Task<LeafSet, string, unknown>;
+    readonly leafStorage: _hello_terrain_work.Task<LeafStorageState, string, unknown>;
+    readonly surface: _hello_terrain_work.Task<Surface, string, unknown>;
+    readonly leafGpuBuffer: _hello_terrain_work.Task<{
+        count: number;
+        data: Int32Array<ArrayBuffer>;
+        attribute: three_webgpu.StorageBufferAttribute;
+        node: three_webgpu.StorageBufferNode;
+    }, 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]>;
+        tileOriginVec2: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node]>;
+        tileSize: three_src_nodes_TSL_js.ShaderNodeFn<[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 createNormalFieldContext: _hello_terrain_work.Task<{
+        data: Uint32Array<ArrayBuffer>;
+        attribute: three_webgpu.StorageBufferAttribute;
+        node: three_webgpu.StorageBufferNode;
+    }, string, unknown>;
+    readonly elevationFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
+    readonly normalFieldStage: _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;
+    }>;
+};
+
+/**
+ * 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.
+ *
+ * @remarks
+ * Only valid in the vertex shader. A vertex belongs to the skirt if it is on
+ * the outermost ring of the tile grid (first/last column or row). The grid
+ * resolution is derived from `segments`.
+ *
+ * @param segments - The number of inner segments in the terrain grid.
+ * @returns A node resolving to a boolean indicating a skirt vertex.
+ */
+declare const isSkirtVertex: three_src_nodes_TSL_js.ShaderNodeFn<[segments: number | Node]>;
+/**
+ * Returns a node that is true for skirt UVs.
+ *
+ * @remarks
+ * Uses interpolated UVs and the grid size
+ * from `segments` to mark fragments outside the inner range
+ * `(step, 1 - step)` on either axis as skirt, where `step = 1 / (segments + 2)`.
+ *
+ * @param segments - The number of inner segments in the terrain grid.
+ * @returns A node resolving to a boolean indicating a skirt fragment.
+ */
+declare const isSkirtUV: three_src_nodes_TSL_js.ShaderNodeFn<[segments: number | Node]>;
+
+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 { Dir, TerrainGeometry, TerrainMesh, U32_EMPTY, allocLeafSet, allocSeamTable, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, compileComputeTask, createComputePipelineTasks, createCubeSphereSurface, createElevationFieldContextTask, createFlatSurface, createInfiniteFlatSurface, createNormalFieldContextTask, createSpatialIndex, createState, createTerrainUniforms, createUniformsTask, deriveNormalZ, elevationFieldStageTask, elevationFn, elevationScale, executeComputeTask, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, leafGpuBufferTask, leafStorageTask, maxLevel, maxNodes, normalFieldStageTask, origin, positionNodeTask, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, resetLeafSet, resetSeamTable, rootSize, skirtScale, surface, surfaceTask, terrainGraph, terrainTasks, textureSpaceToVectorSpace, tileNodesTask, update, updateUniformsTask, vElevation, vGlobalVertexIndex, vectorSpaceToTextureSpace, voronoiCells };
+export type { ComputePipeline, ComputeStageCallback, CubeSphereSurfaceConfig, ElevationCallback, ElevationFieldContext, ElevationParams, FlatSurfaceConfig, InfiniteFlatSurfaceConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodMode, NormalFieldContext, QuadtreeConfig, QuadtreeConfigState, QuadtreeState, SeamTable, SpatialIndex, Surface, TerrainTasks, TerrainUniformsContext, TerrainUniformsParams, TileBounds, TileId, UpdateParams };