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

package/dist/index.d.ts

@@ -1,7 +1,12 @@
-import * as THREE from 'three';
 import { BufferGeometry } from 'three';
+import * as three_webgpu 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 { Node } from 'three/webgpu';
+import { ShaderCallNodeInternal } from 'three/src/nodes/TSL.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.
@@ -89,286 +94,621 @@ declare class TerrainGeometry extends BufferGeometry {
     private generateNormals;
 }
 
+type TerrainMeshParams = {
+    innerTileSegments: number;
+    maxNodes: number;
+    material: NodeMaterial;
+};
+declare class TerrainMesh extends InstancedMesh {
+    private _innerTileSegments;
+    private _maxNodes;
+    constructor(params?: Partial<TerrainMeshParams>);
+    get innerTileSegments(): number;
+    set innerTileSegments(tileSegments: number);
+    get maxNodes(): number;
+    set maxNodes(maxNodes: number);
+}
+
+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;
+}>;
 /**
- * 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`.
- *
- * @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.
+ * 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.
  *
- * @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]>;
+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;
+    }>;
+};
 
-type NeighborIndices = [number, number, number, number];
-type ChildIndices = [number, number, number, number];
-/**
- * Class that manages all node-related buffer arrays and provides access methods
- */
-declare class QuadtreeNodeView {
-    private maxNodeCount;
-    private childrenIndicesBuffer;
-    private neighborsIndicesBuffer;
-    private nodeBuffer;
-    private leafNodeMask;
-    private leafNodeCountBuffer;
-    private activeLeafIndices;
-    private activeLeafCount;
-    constructor(maxNodeCount: number, childrenIndicesBuffer?: Uint16Array, neighborsIndicesBuffer?: Uint16Array, nodeBuffer?: Int32Array, leafNodeMask?: Uint8Array, leafNodeCountBuffer?: Uint16Array);
+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;
     /**
-     * Clear all buffers
+     * Conservative camera-relative bounds for LOD decisions.
+     * Avoids absolute world coordinates so Earth-scale worlds remain stable.
      */
-    clear(): void;
+    tileBounds(tile: TileId, cameraOrigin: {
+        x: number;
+        y: number;
+        z: number;
+    }, out: TileBounds): void;
     /**
-     * Get buffer references for direct access (useful for GPU operations)
+     * Fill root tiles for the current frame and return the count.
+     * Implementations should write level-0 tiles into `out[0..count)`.
      */
-    getBuffers(): {
-        childrenIndicesBuffer: Uint16Array<ArrayBufferLike>;
-        neighborsIndicesBuffer: Uint16Array<ArrayBufferLike>;
-        nodeBuffer: Int32Array<ArrayBufferLike>;
-        leafNodeMask: Uint8Array<ArrayBufferLike>;
+    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;
     };
     /**
-     * Get the maximum node count
+     * Controls how subdivision decisions are made.
+     * `distance` is the initial focus; `screen` is supported for future parity.
      */
-    getMaxNodeCount(): number;
-    getLevel(index: number): number;
-    getX(index: number): number;
-    getY(index: number): number;
-    getLeafNodeCount(): number;
-    getLeaf(index: number): boolean;
-    getChildren(index: number): ChildIndices;
-    getNeighbors(index: number): NeighborIndices;
-    setLevel(index: number, level: number): void;
-    setX(index: number, x: number): void;
-    setY(index: number, y: number): void;
-    setLeaf(index: number, leaf: boolean): void;
-    setChildren(index: number, children: ChildIndices): void;
-    setNeighbors(index: number, neighbors: NeighborIndices): void;
+    mode?: LodMode;
     /**
-     * Get array of active leaf node indices with count (zero-copy, no allocation)
+     * Distance-based refinement threshold.
+     * Interpretation is criteria-dependent; keep it stable across surfaces by using bounds.
      */
-    getActiveLeafNodeIndices(): {
-        indices: Uint16Array;
-        count: number;
-    };
+    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 = {
     /**
-     * Release internal buffers and mark this view as destroyed
+     * World-space size of the root tile edge.
+     * The root tile covers [-rootSize/2, +rootSize/2] around origin in X/Z.
      */
-    destroy(): void;
-    clone(): QuadtreeNodeView;
-}
+    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;
+};
 /**
- * Context passed to subdivision strategy functions.
- * Contains all information needed to make subdivision decisions.
+ * Placeholder cube-sphere surface.
+ *
+ * This exists to localize future planet work behind the `Surface` interface.
+ * Topology remapping across face edges is intentionally TODO.
  */
-interface SubdivisionContext {
-    /** Current node's quadtree level (0 = root) */
-    level: number;
-    /** Distance from camera/position to node center in world units */
-    distance: number;
-    /** World-space size of the node (edge length) */
-    nodeSize: number;
-    /** Minimum allowed node size from config */
-    minNodeSize: number;
-    /** Root terrain size from config */
+declare function createCubeSphereSurface(_cfg: CubeSphereSurfaceConfig): Surface;
+
+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;
+}
+
+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<QuadtreeConfigState>;
+    quadtreeUpdate: TaskRef<LeafSet>;
+    surface: TaskRef<Surface>;
+    leafStorage: TaskRef<LeafStorageState>;
+    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>;
 /**
- * Function type for subdivision strategies.
- * Returns true if the node should be subdivided, false otherwise.
+ * Root compute stage — generates elevation data and writes to the
+ * elevation field storage buffer. Returns a single-element `ComputePipeline`.
  */
-type SubdivisionStrategy = (context: SubdivisionContext) => boolean;
+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>;
 /**
- * Screen-space projection info for LOD calculations.
- * Computed from camera properties each frame.
+ * 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)`.
  */
-interface ScreenSpaceInfo {
-    /**
-     * Projection factor: screenHeight / (2 * tan(fovY / 2))
-     * This converts world-space size to screen-space pixels at distance 1.
-     */
-    projectionFactor: number;
-    /**
-     * Screen height in pixels (for reference/debugging)
-     */
-    screenHeight: number;
+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. */
+declare const origin: _hello_terrain_work.ParamRef<{
+    x: number;
+    y: number;
+    z: number;
+}>;
 /**
- * Distance-based subdivision strategy with hysteresis to prevent LOD flickering.
- * Subdivides when: distance < nodeSize * factor
- *
- * @param factor Multiplier for subdivision threshold (default: 2)
- * @returns SubdivisionStrategy function
+ * Number of segments per inner tile edge.
+ * 13 is the max tiles we can support for 256 workgroups (13 + 3 === 16.. 16x16)
  */
-declare function distanceBasedSubdivision(factor?: number): SubdivisionStrategy;
+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 elevation control function (per vertex, in gpu compute) */
+declare const elevationFn: _hello_terrain_work.ParamRef<ElevationCallback>;
+
 /**
- * Screen-space subdivision strategy.
- * Subdivides based on projected triangle size in pixels.
- * Ensures triangles don't exceed a target pixel size on screen.
+ * Builds the TSL position node for the terrain shader.
+ *
+ * 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.
  *
- * @param options Configuration for screen-space subdivision
- * @returns SubdivisionStrategy function
+ * 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 function screenSpaceSubdivision(options: {
-    /**
-     * Target triangle size in screen pixels.
-     * Subdivide when triangles would be larger than this.
-     * Recommended: 4-8 pixels
-     * @default 6
-     */
-    targetTrianglePixels?: number;
-    /**
-     * Number of segments per tile edge.
-     * Should match TerrainMesh.innerTileSegments.
-     * @default 13
-     */
-    tileSegments?: number;
-    /**
-     * Function that returns current screen-space projection info.
-     * Called each time subdivision is evaluated.
-     */
-    getScreenSpaceInfo: () => ScreenSpaceInfo | null;
-}): SubdivisionStrategy;
+declare const positionNodeTask: _hello_terrain_work.Task<three_src_nodes_TSL_js.ShaderCallNodeInternal, string, unknown>;
+
 /**
- * Compute screen-space info from camera parameters.
- * Helper function to create ScreenSpaceInfo from typical Three.js camera values.
- *
- * @param fovY Vertical field of view in radians
- * @param screenHeight Screen height in pixels
- * @returns ScreenSpaceInfo for use with screenSpaceSubdivision
+ * 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.
  *
- * @example
- * ```ts
- * // In your render loop:
- * const fovRadians = camera.fov * Math.PI / 180;
- * const screenInfo = computeScreenSpaceInfo(fovRadians, renderer.domElement.height);
- * ```
+ * positionNodeTask depends on this (not leafGpuBufferTask) so
+ * the shader is only rebuilt when the buffer is resized, not on every
+ * quadtree update.
  */
-declare function computeScreenSpaceInfo(fovY: number, screenHeight: number): ScreenSpaceInfo;
+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>;
 
-interface QuadtreeParams {
-    maxLevel: number;
-    rootSize: number;
-    minNodeSize: number;
-    origin: THREE.Vector3;
-    maxNodes: number;
-}
-declare class Quadtree {
-    private nodeCount;
-    private deepestLevel;
-    private config;
-    private nodeView;
-    private subdivisionStrategy;
-    private tempChildIndices;
-    private tempNeighborIndices;
-    /**
-     * Create a new Quadtree.
-     *
-     * @param config Quadtree configuration parameters
-     * @param subdivisionStrategy Strategy function for subdivision decisions.
-     *        Defaults to distanceBasedSubdivision(2).
-     * @param nodeView Optional pre-allocated NodeView for buffer reuse
-     */
-    constructor(config: QuadtreeParams, subdivisionStrategy?: SubdivisionStrategy, nodeView?: QuadtreeNodeView);
-    /**
-     * Set the subdivision strategy.
-     * Use this to change LOD behavior at runtime.
-     *
-     * @param strategy The subdivision strategy function
-     */
-    setSubdivisionStrategy(strategy: SubdivisionStrategy): void;
-    /**
-     * Get the current subdivision strategy
-     */
-    getSubdivisionStrategy(): SubdivisionStrategy;
-    private initialize;
-    /**
-     * Update the quadtree based on the given position and return the index
-     * of the leaf node that best corresponds to the position (closest leaf).
-     */
-    update(position: THREE.Vector3, frustum?: THREE.Frustum): number;
-    /**
-     * Recursively update a node and its children based on distance and size criteria
-     * and return the closest leaf node index to the provided position.
-     */
-    private updateNode;
-    /**
-     * Determine if a node should be subdivided using the configured strategy
-     */
-    private shouldSubdivide;
-    /**
-     * Create a new node and return its index
-     */
-    private createNode;
-    /**
-     * Subdivide a node by creating its four children
-     */
-    private subdivideNode;
-    /**
-     * Update neighbor relationships for child nodes
-     */
-    private updateChildNeighbors;
-    /**
-     * Get the deepest subdivision level currently in the quadtree
-     */
-    getDeepestLevel(): number;
-    /**
-     * Get the total number of nodes
-     */
-    getNodeCount(): number;
-    getLeafNodeCount(): number;
-    /**
-     * Get active leaf node indices for efficient GPU processing
-     */
-    getActiveLeafNodeIndices(): {
-        indices: Uint16Array;
+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(): _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;
-    };
-    /**
-     * Get the configuration
-     */
-    getConfig(): QuadtreeParams;
-    /**
-     * Get all leaf nodes as an array of node objects
-     */
-    getLeafNodes(): Array<{
-        level: number;
-        x: number;
-        y: 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;
     }>;
-    /**
-     * Reset the quadtree
-     */
-    reset(): void;
-    /**
-     * Get the NodeView instance for direct access
-     */
-    getNodeView(): QuadtreeNodeView;
-    /**
-     * Release internal resources associated with this quadtree
-     */
-    destroy(): void;
-    /**
-     * Set the configuration
-     */
-    setConfig(config: QuadtreeParams, reset?: boolean): void;
-}
+};
+
+/**
+ * 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 { Quadtree, TerrainGeometry, computeScreenSpaceInfo, distanceBasedSubdivision, isSkirtUV, isSkirtVertex, screenSpaceSubdivision };
-export type { QuadtreeParams, ScreenSpaceInfo, SubdivisionContext, SubdivisionStrategy };
+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 };