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

package/dist/index.d.ts

@@ -1,6 +1,12 @@
-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.
@@ -28,17 +34,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 +96,791 @@ declare class TerrainGeometry extends BufferGeometry {
     private generateNormals;
 }
 
+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;
+/**
+ * Placeholder backend for future true 3D storage-texture support in Three.js.
+ * We keep it present to preserve the backend API shape.
+ */
+declare function Texture3DBackend(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 sampleTerrainFieldNormal(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;
+    instanceId: string;
+}
+interface TerrainUniformsContext {
+    uRootOrigin: UniformNode<Vector3>;
+    uRootSize: UniformNode<number>;
+    uInnerTileSegments: UniformNode<number>;
+    uSkirtScale: UniformNode<number>;
+    uElevationScale: 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;
+}
+interface CreateTerrainSamplerParams {
+    terrainFieldStorage: TerrainFieldStorage;
+    spatialIndex: GpuSpatialIndexContext;
+    uniforms: TerrainUniformsContext;
+    elevationCallback: ElevationCallback;
+}
+interface TerrainSample {
+    elevation: number;
+    normal: Vector3$1;
+    valid: boolean;
+}
+interface TerrainElevationSample {
+    elevation: number;
+    valid: boolean;
+}
+interface TerrainSampleBatch {
+    elevations: Float32Array;
+    normals: Float32Array;
+    valid: Uint8Array;
+    generation: number;
+}
+interface TerrainTile {
+    level: number;
+    x: number;
+    y: number;
+    index: number;
+}
+interface TerrainTileBounds extends TerrainTile {
+    minElevation: number;
+    maxElevation: number;
+}
+interface ElevationRange {
+    min: number;
+    max: number;
+}
+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;
+}
+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;
+};
+declare class TerrainMesh extends InstancedMesh {
+    private _innerTileSegments;
+    private _maxNodes;
+    terrainRaycast: TerrainRaycast | null;
+    constructor(params?: Partial<TerrainMeshParams>);
+    get innerTileSegments(): number;
+    set innerTileSegments(tileSegments: number);
+    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 task — uses terrainFieldStageTask 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;
+}>;
+/**
+ * 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 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 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.
+     *
+     * 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 at the camera's XZ position (from previous frame).
+     * Subtracted from `cameraOrigin.y` during refinement so that LOD
+     * distance is measured relative to the terrain surface, not the datum.
+     */
+    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[];
+    /** 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, params: UpdateParams): void;
+
+/**
+ * Update the quadtree for the given surface + camera parameters.
+ *
+ * Produces a LeafSet of TileIds (SoA typed arrays).
+ */
+declare function update(state: QuadtreeState, surface: Surface, 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(surface: Surface, leaves: LeafSet, outSeams: SeamTable, outIndex?: SpatialIndex): SeamTable;
+
+type FlatSurfaceConfig = {
+    /**
+     * 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 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;
+};
+/**
+ * Placeholder cube-sphere surface.
+ *
+ * This exists to localize future planet work behind the `Surface` interface.
+ * Topology remapping across face edges is intentionally TODO.
+ */
+declare function createCubeSphereSurface(_cfg: CubeSphereSurfaceConfig): Surface;
+
+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]>;
+};
+
+type TerrainQueryConfig = {
+    rootSize: number;
+    originX: number;
+    originY: number;
+    originZ: number;
+    innerTileSegments: number;
+    elevationScale: number;
+    maxLevel: 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;
+}
+
+interface QuadtreeConfigState {
+    state: QuadtreeState;
+    surface: Surface;
+}
+interface LeafGpuBufferState extends LeafStorageState {
+    count: number;
+}
+interface ElevationFieldContext {
+    data: Float32Array<ArrayBuffer>;
+    attribute: StorageBufferAttribute;
+    node: StorageBufferNode;
+}
+interface TerrainQueryContext {
+    cache: CpuTerrainCache;
+    query: TerrainQuery;
+    shapeKey: string;
+}
+/** Task refs for the standard terrain pipeline. */
+interface TerrainTasks {
+    instanceId: TaskRef<string>;
+    quadtreeConfig: TaskRef<QuadtreeConfigState>;
+    quadtreeUpdate: TaskRef<LeafSet>;
+    surface: TaskRef<Surface>;
+    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]>;
+    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>;
+
+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;
+}>;
+/**
+ * Number of segments per inner tile edge.
+ * 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>;
+/** 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 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 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<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>;
+
+declare function terrainGraph(): TerrainGraph;
+/** 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 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 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]>;
+        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 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>;
+};
+
+type ComputeDeviceLimits = {
+    maxWorkgroupSizeX: number;
+    maxWorkgroupSizeY: number;
+    maxWorkgroupInvocations: number;
+};
+declare function getDeviceComputeLimits(renderer: WebGPURenderer): ComputeDeviceLimits;
+
+declare function createTerrainSampler(params: CreateTerrainSamplerParams): TerrainSampler;
+
+declare function createTerrainQuery(cache: CpuTerrainCache): TerrainQuery;
+
+type CpuRaycastConfig = {
+    rootSize: number;
+    originX: number;
+    originZ: number;
+    minY: number;
+    maxY: number;
+};
+
+type TerrainRaycastConfig = CpuRaycastConfig;
+declare function createTerrainRaycast(params: {
+    getTerrainQuery: () => TerrainQuery | null;
+    getConfig: () => TerrainRaycastConfig;
+}): TerrainRaycast;
+
+/**
+ * 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 +906,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, Dir, TerrainGeometry, TerrainMesh, Texture3DBackend, U32_EMPTY, allocLeafSet, allocSeamTable, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, compileComputeTask, createComputePipelineTasks, createCubeSphereSurface, createElevationFieldContextTask, createFlatSurface, createInfiniteFlatSurface, createSpatialIndex, createState, createTerrainFieldStorage, createTerrainFieldTextureTask, createTerrainQuery, createTerrainRaycast, createTerrainSampler, createTerrainSamplerTask, createTerrainUniforms, createUniformsTask, deriveNormalZ, elevationFieldStageTask, elevationFn, elevationScale, executeComputeTask, getDeviceComputeLimits, gpuSpatialIndexStorageTask, gpuSpatialIndexUploadTask, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, leafGpuBufferTask, leafStorageTask, loadTerrainField, loadTerrainFieldElevation, loadTerrainFieldNormal, maxLevel, maxNodes, origin, packTerrainFieldSample, positionNodeTask, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, resetLeafSet, resetSeamTable, rootSize, sampleTerrainField, sampleTerrainFieldElevation, sampleTerrainFieldNormal, skirtScale, storeTerrainField, surface, surfaceTask, terrainFieldFilter, terrainFieldStageTask, terrainGraph, terrainQueryTask, terrainRaycastTask, terrainReadbackTask, terrainTasks, textureSpaceToVectorSpace, tileNodesTask, update, updateUniformsTask, vElevation, vGlobalVertexIndex, vectorSpaceToTextureSpace, voronoiCells };
+export type { ComputePipeline, ComputeStageCallback, CreateTerrainSamplerParams, CubeSphereSurfaceConfig, ElevationCallback, ElevationFieldContext, ElevationParams, ElevationRange, FlatSurfaceConfig, GpuSpatialIndexContext, InfiniteFlatSurfaceConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodMode, QuadtreeConfig, QuadtreeConfigState, QuadtreeState, RaycastOptions, SeamTable, SpatialIndex, Surface, TerrainElevationSample, TerrainFieldStorage, TerrainFieldStorageBackendType, TerrainFieldStorageFormat, TerrainFieldStorageOptions, TerrainGraph, TerrainQuery, TerrainQueryContext, TerrainRaycast, TerrainRaycastConfig, TerrainRaycastResult, TerrainSample, TerrainSampleBatch, TerrainSampler, TerrainTasks, TerrainTile, TerrainTileBounds, TerrainUniformsContext, TerrainUniformsParams, TileBounds, TileId, UpdateParams };