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

package/dist/index.d.mts

@@ -1,11 +1,11 @@
-import { BufferGeometry, Ray, Vector3 as Vector3$1, Raycaster, Intersection } from 'three';
+import { BufferGeometry, Vector3 as Vector3$1, Ray, 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 { 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_src_nodes_TSL_js from 'three/src/nodes/TSL.js';
+import { ShaderCallNodeInternal } from 'three/src/nodes/TSL.js';
 import * as three_tsl from 'three/tsl';
 
 /**
@@ -13,7 +13,14 @@ import * as three_tsl from 'three/tsl';
  * This geometry ensures that corner triangles are subdivided correctly.
  */
 declare class TerrainGeometry extends BufferGeometry {
-    constructor(innerSegments?: number, extendUV?: boolean);
+    /**
+     * @param flipWinding Reverse triangle winding so front faces point the
+     *   opposite way. The default winding makes flat tiles front-face `+Y`; the
+     *   cube-sphere maps `(u→right, v→up)`, which would otherwise leave the
+     *   planet's outer shell back-facing, so it passes `flipWinding` to render
+     *   the outer surface with `FrontSide`.
+     */
+    constructor(innerSegments?: number, extendUV?: boolean, flipWinding?: boolean);
     /**
      * Generate indices for terrain geometry with proper skirt corner handling.
      * The key improvement is in how corner triangles are subdivided.
@@ -116,11 +123,6 @@ interface TerrainFieldStorage {
 }
 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;
@@ -132,20 +134,14 @@ declare function loadTerrainFieldNormal(storage: TerrainFieldStorage, ix: Node,
  */
 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;
+/**
+ * Pack a terrain field sample into RGBA: `[height, Nx, Ny, Nz]` where
+ * `(Nx, Ny, Nz)` is the unit world-space surface normal. Storing the full
+ * world normal (rather than a face-local tangent pair) keeps shading
+ * continuous across cube-face seams, since adjacent faces no longer rotate the
+ * normal through their own parametric tangent frame.
+ */
+declare function packTerrainFieldSample(height: Node, normal: Node): Node;
 
 interface TerrainUniformsParams {
     rootSize: number;
@@ -153,6 +149,7 @@ interface TerrainUniformsParams {
     innerTileSegments: number;
     skirtScale: number;
     elevationScale: number;
+    radius: number;
     instanceId: string;
 }
 interface TerrainUniformsContext {
@@ -161,6 +158,7 @@ interface TerrainUniformsContext {
     uInnerTileSegments: UniformNode<number>;
     uSkirtScale: UniformNode<number>;
     uElevationScale: UniformNode<number>;
+    uRadius: UniformNode<number>;
 }
 interface LeafStorageState {
     data: Int32Array<ArrayBuffer>;
@@ -168,145 +166,36 @@ interface LeafStorageState {
     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;
+/** Shared (projection-independent) tile-compute helpers. */
+type SharedTileCompute = {
+    tileLevel: (nodeIndex: Node) => Node;
+    tileFace: (nodeIndex: Node) => Node;
+    tileOriginVec2: (nodeIndex: Node) => Node;
+    /** Face-local (u, v) in [0, 1] for a grid sample, including skirt border. */
+    tileFaceUV: (nodeIndex: Node, ix: Node, iy: Node) => Node;
+};
+/** Projection-specific tile-compute builders. */
+type TileComputeParts = {
+    tileSize: (nodeIndex: Node) => Node;
+    rootUV: (nodeIndex: Node, ix: Node, iy: Node) => Node;
+    tileVertexWorldPosition: (nodeIndex: Node, ix: Node, iy: Node) => Node;
+};
+type TileComputePartsContext = {
+    leafStorage: LeafStorageState;
     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;
+    shared: SharedTileCompute;
+};
+type TileCompute = SharedTileCompute & {
+    tileSize: (nodeIndex: Node) => Node;
+    rootUVCompute: (nodeIndex: Node, ix: Node, iy: Node) => Node;
+    tileVertexWorldPositionCompute: (nodeIndex: Node, ix: Node, iy: Node) => Node;
 };
-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);
- * ```
+ * Build the per-tile compute helpers, composing projection-independent
+ * decoders with the projection-specific position/size/uv builders supplied by
+ * `projection.gpu.createTileComputeParts`.
  */
-declare function createComputePipelineTasks(leafStageTask: TaskRef<ComputePipeline>): {
-    compile: _hello_terrain_work.Task<{
-        execute: (renderer: WebGPURenderer, instanceCount: number) => void;
-    }, string, unknown>;
-    execute: _hello_terrain_work.Task<any, string, {
-        renderer: WebGPURenderer;
-    }>;
-};
+declare function createTileCompute(leafStorage: LeafStorageState, uniforms: TerrainUniformsContext, projection: SurfaceProjection): TileCompute;
 
 declare const Dir: {
     readonly LEFT: 0;
@@ -333,10 +222,32 @@ type TileBounds = {
     /** conservative radius */
     r: number;
 };
-type Surface = {
+/** Scaled world-space elevation displacement range for a tile. */
+type ElevationRangeOut = {
+    min: number;
+    max: number;
+};
+type Topology = {
     spaceCount: number;
     /** maximum number of roots returned by `rootTiles` */
     maxRootCount: number;
+    /**
+     * Injected surface projection strategy. Encapsulates the GPU position/normal
+     * assembly and the CPU query/raycast/LOD behavior for this topology, so the
+     * pipeline never branches on a projection kind.
+     */
+    projection: SurfaceProjection;
+    /** Representative surface radius in world units (curved projections only). */
+    radius?: number;
+    /**
+     * Surface center in world space (curved projections only). Used to apply the
+     * camera elevation offset along the surface up-direction during LOD.
+     */
+    center?: {
+        x: number;
+        y: number;
+        z: number;
+    };
     /**
      * Compute the same-level neighbor TileId in the requested direction.
      * Returns false if the neighbor is outside the valid topology.
@@ -347,12 +258,13 @@ type Surface = {
     /**
      * Conservative camera-relative bounds for LOD decisions.
      * Avoids absolute world coordinates so Earth-scale worlds remain stable.
+     * When `elevationRange` is provided, bounds should account for displaced geometry.
      */
     tileBounds(tile: TileId, cameraOrigin: {
         x: number;
         y: number;
         z: number;
-    }, out: TileBounds): void;
+    }, out: TileBounds, elevationRange?: ElevationRangeOut): void;
     /**
      * Fill root tiles for the current frame and return the count.
      * Implementations should write level-0 tiles into `out[0..count)`.
@@ -400,9 +312,11 @@ type UpdateParams = {
         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.
+     * Terrain elevation beneath the camera (from the previous frame). During
+     * refinement it offsets the camera toward the terrain surface so LOD distance
+     * is measured relative to the surface rather than the datum:
+     * - flat: subtracted from `cameraOrigin.y`.
+     * - cube-sphere: subtracted along the radial up-direction from the planet center.
      */
     elevationAtCameraXZ?: number;
     /**
@@ -421,6 +335,11 @@ type UpdateParams = {
     targetPixels?: number;
     /** Prevent flicker by separating split/merge thresholds (0..1 typical) */
     hysteresis?: number;
+    /**
+     * Previous-frame per-tile elevation range in world-space displacement units
+     * (already scaled by `elevationScale`). Returns false when no data is available.
+     */
+    tileElevationRange?: (space: number, level: number, x: number, y: number, out: ElevationRangeOut) => boolean;
 };
 type QuadtreeConfig = {
     maxNodes: number;
@@ -487,19 +406,20 @@ type QuadtreeState = {
     scratchTile: TileId;
     scratchNeighbor: TileId;
     scratchBounds: TileBounds;
+    scratchElevationRange: ElevationRangeOut;
     scratchRootTiles: TileId[];
-    /** surface space count is fixed for a given state */
+    /** topology 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;
+declare function createState(cfg: QuadtreeConfig, topology: Topology): QuadtreeState;
+declare function beginUpdate(state: QuadtreeState, topology: Topology, params: UpdateParams): void;
 
 /**
- * Update the quadtree for the given surface + camera parameters.
+ * Update the quadtree for the given topology + camera parameters.
  *
  * Produces a LeafSet of TileIds (SoA typed arrays).
  */
-declare function update(state: QuadtreeState, surface: Surface, params: UpdateParams, outLeaves?: LeafSet): LeafSet;
+declare function update(state: QuadtreeState, topology: Topology, params: UpdateParams, outLeaves?: LeafSet): LeafSet;
 
 /**
  * Build a fixed-width seam/neighbor table for balanced leaves (2:1).
@@ -507,9 +427,9 @@ declare function update(state: QuadtreeState, surface: Surface, params: UpdatePa
  * 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;
+declare function buildSeams2to1(topology: Topology, leaves: LeafSet, outSeams: SeamTable, outIndex?: SpatialIndex): SeamTable;
 
-type FlatSurfaceConfig = {
+type FlatTopologyConfig = {
     /**
      * World-space size of the root tile edge.
      * The root tile covers [-rootSize/2, +rootSize/2] around origin in X/Z.
@@ -520,44 +440,157 @@ type FlatSurfaceConfig = {
         y: number;
         z: number;
     };
-    /** optional conservative vertical extent, included in bounds radius */
-    maxHeight?: number;
 };
-declare function createFlatSurface(cfg: FlatSurfaceConfig): Surface;
+declare function createFlatTopology(cfg: FlatTopologyConfig): Topology;
 
-type InfiniteFlatSurfaceConfig = {
+type InfiniteFlatTopologyConfig = {
     rootSize: number;
     origin: {
         x: number;
         y: number;
         z: number;
     };
-    /** optional conservative vertical extent, included in bounds radius */
-    maxHeight?: number;
     /** half-width of root grid in root tiles (1 => 3x3 roots) */
     rootGridRadius?: number;
 };
-declare function createInfiniteFlatSurface(cfg: InfiniteFlatSurfaceConfig): Surface;
+declare function createInfiniteFlatTopology(cfg: InfiniteFlatTopologyConfig): Topology;
 
-type CubeSphereSurfaceConfig = {
+type CubeSphereTopologyConfig = {
+    /** Sphere radius in world units. */
     radius: number;
-    maxHeight?: number;
+    /** Planet center in world space (defaults to origin). */
+    center?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** When true, elevation displaces inward and skirts point outward. */
+    invert?: boolean;
+};
+/**
+ * Cube-sphere topology: six quadtree faces wrapped onto a sphere.
+ *
+ * Topology (`neighborSameLevel`) is derived numerically from the shared
+ * `CUBE_FACES` basis so cross-face edges (including rotated pole edges)
+ * resolve to the correct neighbor tile without hand-coded transforms.
+ */
+declare function createCubeSphereTopology(cfg: CubeSphereTopologyConfig): Topology;
+
+/**
+ * Canonical cube-sphere face basis.
+ *
+ * Shared single source of truth between the CPU surface topology
+ * (`cubeSphere.ts`) and the GPU position/normal assembly (`tsl/cubeSphere.ts`)
+ * so both agree on geometry and faces seam correctly.
+ *
+ * Each face maps a face-local coordinate (u, v) in [0, 1] to a point on the
+ * cube `[-1, 1]^3` via:
+ *
+ *   s = 2u - 1, t = 2v - 1
+ *   cube = forward + s * right + t * up
+ *
+ * Normalizing `cube` yields the unit-sphere direction for that vertex.
+ *
+ * Bases are right-handed (`forward = right x up`) and outward-facing.
+ * Space indices: 0:+X 1:-X 2:+Y 3:-Y 4:+Z 5:-Z.
+ */
+type Vec3 = readonly [number, number, number];
+type CubeFace = {
+    forward: Vec3;
+    right: Vec3;
+    up: Vec3;
 };
+declare const CUBE_FACE_COUNT = 6;
+declare const CUBE_FACES: readonly CubeFace[];
+
+type Vec3Mutable$1 = [number, number, number];
+/**
+ * Cube-space point for a face-local coordinate (u, v) in [0, 1]:
+ *   cube = forward + (2u-1) * right + (2v-1) * up
+ * The result is unnormalized; normalize it to obtain the sphere direction.
+ */
+declare function faceUVToCube(face: number, u: number, v: number, out: Vec3Mutable$1): void;
+/** Pick the cube face whose normal axis dominates the direction. */
+declare function directionToFace(d: Vec3): number;
+/** Face-local (u, v) in [0, 1] for a direction known to fall on `face`. */
+declare function directionToFaceUV(face: number, d: Vec3, out: [number, number]): void;
 /**
- * Placeholder cube-sphere surface.
+ * Convert latitude/longitude (degrees) to a unit sphere direction.
  *
- * This exists to localize future planet work behind the `Surface` interface.
- * Topology remapping across face edges is intentionally TODO.
+ * Convention matches `CUBE_FACES` (+Y is the north pole):
+ * - latitude is the angle above the equator, in `[-90, 90]`
+ * - longitude is the angle around the +Y axis, in `[-180, 180]`,
+ *   measured from +Z toward +X (lon = 0 points along +Z).
  */
-declare function createCubeSphereSurface(_cfg: CubeSphereSurfaceConfig): Surface;
+declare function latLongToDirection(latDeg: number, lonDeg: number, out: Vec3Mutable$1): void;
+/** Inverse of {@link latLongToDirection}; returns degrees. */
+declare function directionToLatLong(d: Vec3): {
+    latitude: number;
+    longitude: number;
+};
 
-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 TorusTopologyConfig = {
+    /** Distance from the torus center to the tube center (the donut radius). */
+    majorRadius: number;
+    /** Radius of the tube cross-section. */
+    minorRadius: number;
+    /** Torus center in world space (defaults to origin). */
+    center?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** When true, elevation displaces inward and skirts point outward. */
+    invert?: boolean;
 };
+/**
+ * Torus (donut) topology: a single quadtree space whose `(u, v)` axes wrap
+ * around the major circle and the tube cross-section. Both axes are periodic,
+ * so every same-level neighbor exists (wrapping modulo the level resolution).
+ *
+ * Level-0 resolution is anisotropic: `baseU = round(major/minor)` tiles along
+ * `u` and `baseV = 1` along `v`, so root tiles are approximately square in
+ * world space before isotropic LOD subdivision.
+ */
+declare function createTorusTopology(cfg: TorusTopologyConfig): Topology;
+
+type Vec3Mutable = [number, number, number];
+/** Wrap a value into [0, 1). */
+declare function wrap01(t: number): number;
+/**
+ * Torus surface point for parameters (u, v) in [0, 1].
+ *
+ * Convention (matches `latLongToDirection`'s longitude axis):
+ * - `theta = 2*pi*u` sweeps around the +Y axis, measured from +Z toward +X.
+ * - `phi = 2*pi*v` sweeps around the tube cross-section, `phi = 0` pointing
+ *   radially outward in the XZ plane and `phi = pi/2` pointing toward +Y.
+ *
+ * `displacement` is the elevation added to the tube (minor) radius.
+ */
+declare function torusUVToPoint(u: number, v: number, majorRadius: number, minorRadius: number, displacement: number, center: {
+    x: number;
+    y: number;
+    z: number;
+}, out: Vec3Mutable, invert?: boolean): void;
+/** Outward unit surface normal of the base (undisplaced) torus at (u, v). */
+declare function torusOutwardNormal(u: number, v: number, out: Vec3Mutable, invert?: boolean): void;
+type TorusSurfaceParams = {
+    /** Wrapped major-circle parameter in [0, 1). */
+    u: number;
+    /** Wrapped tube parameter in [0, 1). */
+    v: number;
+    /** Distance from the point to the tube center circle. */
+    tubeDistance: number;
+};
+/**
+ * Map a world point to torus surface parameters. `tubeDistance - minorRadius`
+ * is the signed radial displacement of the point relative to the base torus.
+ */
+declare function positionToTorusParams(px: number, py: number, pz: number, majorRadius: number, center: {
+    x: number;
+    y: number;
+    z: number;
+}, out: TorusSurfaceParams): void;
 
 type TerrainQueryConfig = {
     rootSize: number;
@@ -567,12 +600,20 @@ type TerrainQueryConfig = {
     innerTileSegments: number;
     elevationScale: number;
     maxLevel: number;
+    /** Representative surface radius (curved projections only). */
+    radius: number;
+    /** Level-0 tile count along u before LOD subdivision (defaults to 1). */
+    baseU?: number;
+    /** Level-0 tile count along v before LOD subdivision (defaults to 1). */
+    baseV?: 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;
+    /** Release GPU readback staging buffers owned by this cache. */
+    dispose(): void;
     getElevation(worldX: number, worldZ: number): number | null;
     getNormal(worldX: number, worldZ: number): Vector3$1 | null;
     getTile(worldX: number, worldZ: number): TerrainTile | null;
@@ -580,11 +621,412 @@ interface CpuTerrainCache {
     getGlobalElevationRange(): ElevationRange | null;
     sampleTerrainBatch(positions: Float32Array): TerrainSampleBatch;
     sampleTerrain(worldX: number, worldZ: number): TerrainSample;
+    /** True when the active projection supplies surface ops. */
+    readonly hasSurface: boolean;
+    sampleSurfaceByPosition(px: number, py: number, pz: number): TerrainSurfaceSample;
+    getElevationBySurfacePosition(px: number, py: number, pz: number): number | null;
+    getNormalBySurfacePosition(px: number, py: number, pz: number): Vector3$1 | null;
+    getTileBySurfacePosition(px: number, py: number, pz: number): TerrainTile | null;
+    getTileBoundsBySurfacePosition(px: number, py: number, pz: number): TerrainTileBounds | null;
+    sampleSurfaceBatchByPosition(positions: Float32Array): TerrainSurfaceSampleBatch;
+    /**
+     * Previous-frame raw elevation min/max for a tile (unscaled field values).
+     * Returns false when no snapshot data is available for the tile.
+     */
+    getTileElevationRange(space: number, level: number, x: number, y: number, out: {
+        min: number;
+        max: number;
+    }): boolean;
 }
 
+/**
+ * CPU sampling over a snapshot elevation-field buffer laid out as
+ * `maxNodes × (edgeVertexCount × edgeVertexCount)` raw heights.
+ *
+ * Plain-number math only (no three.js, no TSL); callers build vectors at the
+ * consumer-facing boundary.
+ */
+interface ElevationGridShape {
+    edgeVertexCount: number;
+    verticesPerNode: number;
+}
+
+/** Stable projection identifier — for debugging/telemetry only, never switched on. */
+type ProjectionKind = "flat" | "cubeSphere" | "torus" | (string & {});
+interface Vec3Like {
+    x: number;
+    y: number;
+    z: number;
+}
+interface RenderVertexPositionContext {
+    leafStorage: LeafStorageState;
+    uniforms: TerrainUniformsContext;
+    terrainFieldStorage?: TerrainFieldStorage;
+}
+interface FieldNormalContext {
+    elevationFieldNode: Node;
+    edgeVertexCount: number;
+    tile: TileCompute;
+    uniforms: TerrainUniformsContext;
+}
+/** Per-vertex field-stage normal: `(nodeIndex, ix, iy) => unit world normal`. */
+type FieldNormalFn = (nodeIndex: Node, ix: Node, iy: Node) => Node;
+interface SurfaceProjectionGpu {
+    /** Render-path world position; also assigns the vertex normal varying. */
+    renderVertexPosition(ctx: RenderVertexPositionContext): Node;
+    /** Projection-specific compute-stage tile builders (size / uv / position). */
+    createTileComputeParts(ctx: TileComputePartsContext): TileComputeParts;
+    /** Field-stage surface normal builder. */
+    createFieldNormal(ctx: FieldNormalContext): FieldNormalFn;
+    /** Optional extra GPU samplers (e.g. sphere ByDirection); no-op for flat. */
+    augmentSampler?(sampler: TerrainSampler, params: CreateTerrainSamplerParams): void;
+}
+/** A world point projected onto a closed surface: tile space + face-local uv. */
+interface SurfaceKey {
+    /** Tile space/face index (0 for torus, 0..5 for cube-sphere faces). */
+    space: number;
+    /** Face-local u in [0, 1). */
+    u: number;
+    /** Face-local v in [0, 1). */
+    v: number;
+    /** Outward unit direction at the key (for the surface sample `direction`). */
+    dirX: number;
+    dirY: number;
+    dirZ: number;
+}
+/** Grid neighborhood passed to {@link CpuSurfaceOps.surfaceNormal}. */
+interface SurfaceNormalContext {
+    elevation: Float32Array;
+    shape: ElevationGridShape;
+    leafIndex: number;
+    /** Fractional grid coords of the sample within the leaf. */
+    gx: number;
+    gy: number;
+    innerTileSegments: number;
+    elevationScale: number;
+    level: number;
+}
+/**
+ * Projection-specific CPU surface math, injected into the terrain cache so the
+ * cache stays projection-agnostic. Implementations own their scratch (no
+ * module-scope state).
+ */
+interface CpuSurfaceOps {
+    /** Map a world position to a surface key; `false` if it has no projection. */
+    positionToKey(px: number, py: number, pz: number, out: SurfaceKey): boolean;
+    /** Displaced world position from a key + scaled elevation (writes `out`). */
+    surfacePosition(key: SurfaceKey, elevation: number, out: Vector3$1): void;
+    /** Unit world-space surface normal from a key + grid neighborhood. */
+    surfaceNormal(key: SurfaceKey, ctx: SurfaceNormalContext): Vector3$1;
+}
+interface ProjectionRaycastContext {
+    ray: Ray;
+    options?: RaycastOptions;
+    terrainQuery: TerrainQuery | null;
+    surfaceQuery: TerrainSurfaceQuery | null;
+    sphereQuery: TerrainSphereQuery | null;
+    config: TerrainRaycastConfig;
+}
+interface RuntimeQueries {
+    query: TerrainQuery;
+    /** Generic surface query (position/uv keyed); `null` on flat surfaces. */
+    surfaceQuery: TerrainSurfaceQuery | null;
+    /** Cube-sphere query (adds direction/lat-long); `null` unless cube-sphere. */
+    sphereQuery: TerrainSphereQuery | null;
+}
+interface SurfaceProjectionCpu {
+    /**
+     * Offset the camera toward the terrain surface so LOD distance is measured
+     * from the surface, not the datum. Mutates `cam` in place by `elevation`
+     * along the projection's up-direction.
+     */
+    cameraSurfaceOffset(cam: Vec3Like, elevation: number): void;
+    /**
+     * Surface sampling ops injected into the terrain cache; `null` for flat
+     * surfaces (which have no closed-surface query).
+     */
+    createSurfaceOps(): CpuSurfaceOps | null;
+    /** Build the runtime query objects the projection exposes. */
+    createRuntimeQueries(cache: CpuTerrainCache): RuntimeQueries;
+    /** Projection-specific CPU raycast (precise, falling back to bounds). */
+    raycast(ctx: ProjectionRaycastContext): TerrainRaycastResult | null;
+}
+interface SurfaceProjection {
+    /** Identifier; never switched on internally. */
+    readonly kind: ProjectionKind;
+    /** Representative radius (bounds/uniform helper); undefined for flat. */
+    readonly radius?: number;
+    /** Surface center in world space; undefined for flat. */
+    readonly center?: Vec3Like;
+    /** Closed surfaces face outward → flip triangle winding. */
+    readonly faceOutward: boolean;
+    /**
+     * Per-axis level-0 tile count before LOD subdivision. Defaults to `{ u: 1, v: 1 }`.
+     * At level `L`, resolution is `baseU * 2^L` by `baseV * 2^L` tiles.
+     */
+    readonly baseResolution?: {
+        u: number;
+        v: number;
+    };
+    gpu: SurfaceProjectionGpu;
+    cpu: SurfaceProjectionCpu;
+}
+
+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 GpuSpatialIndexContext {
+    data: Uint32Array<ArrayBuffer>;
+    size: number;
+    mask: number;
+    stampGen: UniformNode<number>;
+    attribute: StorageBufferAttribute;
+    node: StorageBufferNode;
+}
+interface TerrainSampler {
+    sampleElevation: (worldX: Node, worldZ: Node) => Node;
+    sampleNormal: (worldX: Node, worldZ: Node) => Node;
+    sampleTerrain: (worldX: Node, worldZ: Node) => Node;
+    sampleValidity: (worldX: Node, worldZ: Node) => Node;
+    evaluateElevation: (worldX: Node, worldZ: Node) => Node;
+    evaluateNormal: (worldX: Node, worldZ: Node, epsilon?: Node) => Node;
+    /** Packed `vec4(elevation, nx, ny, nz)` where the normal is tangent-space. */
+    sampleTerrainByDirection?: (direction: Node) => Node;
+    sampleElevationByDirection?: (direction: Node) => Node;
+    /** World-space surface normal reconstructed in the sphere tangent frame. */
+    sampleNormalByDirection?: (direction: Node) => Node;
+    sampleValidityByDirection?: (direction: Node) => Node;
+}
+interface CreateTerrainSamplerParams {
+    terrainFieldStorage: TerrainFieldStorage;
+    spatialIndex: GpuSpatialIndexContext;
+    uniforms: TerrainUniformsContext;
+    elevationCallback: ElevationCallback;
+    /** Maximum quadtree level to probe during tile lookup. */
+    maxLevel: number;
+    /** Active surface projection (drives optional GPU sampler augmentation). */
+    projection: SurfaceProjection;
+}
+interface TerrainSample {
+    elevation: number;
+    normal: Vector3$1;
+    valid: boolean;
+}
+interface TerrainSampleBatch {
+    elevations: Float32Array;
+    normals: Float32Array;
+    valid: Uint8Array;
+    generation: number;
+}
+/**
+ * Result of sampling a cube-sphere surface from a direction/position/lat-long.
+ *
+ * `elevation` is the radial displacement above the base radius (already scaled
+ * by `elevationScale`); `position` is the full world-space surface point
+ * `center + direction * (radius + elevation)`.
+ */
+interface TerrainSurfaceSample {
+    position: Vector3$1;
+    normal: Vector3$1;
+    direction: Vector3$1;
+    elevation: number;
+    valid: boolean;
+}
+interface TerrainSurfaceSampleBatch {
+    positions: Float32Array;
+    normals: Float32Array;
+    elevations: Float32Array;
+    valid: Uint8Array;
+    generation: number;
+}
+interface TerrainTile {
+    /** Surface space index: 0 for flat terrain, 0..5 for cube-sphere faces. */
+    space: number;
+    level: number;
+    x: number;
+    y: number;
+    index: number;
+}
+interface TerrainTileBounds extends TerrainTile {
+    minElevation: number;
+    maxElevation: number;
+}
+interface ElevationRange {
+    min: number;
+    max: number;
+}
+/**
+ * Flat (heightfield) terrain query, keyed on world XZ. For cube-sphere
+ * surfaces use {@link TerrainSphereQuery} instead.
+ */
+interface TerrainQuery {
+    getElevation(worldX: number, worldZ: number): number | null;
+    getNormal(worldX: number, worldZ: number): Vector3$1 | null;
+    getTile(worldX: number, worldZ: number): TerrainTile | null;
+    getTileBounds(worldX: number, worldZ: number): TerrainTileBounds | null;
+    getGlobalElevationRange(): ElevationRange | null;
+    sampleTerrain(worldX: number, worldZ: number): TerrainSample;
+    sampleTerrainBatch(positions: Float32Array): TerrainSampleBatch;
+    readonly generation: number;
+}
+/**
+ * Generic closed-surface terrain query, keyed on a world position projected
+ * onto the surface. Exposed for every non-flat projection (cube-sphere, torus,
+ * ...); `null` on flat surfaces. Elevation is the displacement above the base
+ * surface (already scaled by `elevationScale`); `position` is the full
+ * world-space surface point.
+ */
+interface TerrainSurfaceQuery {
+    readonly generation: number;
+    getElevationByPosition(position: Vector3$1): number | null;
+    getNormalByPosition(position: Vector3$1): Vector3$1 | null;
+    sampleTerrainByPosition(position: Vector3$1): TerrainSurfaceSample;
+    getTileByPosition(position: Vector3$1): TerrainTile | null;
+    getTileBoundsByPosition(position: Vector3$1): TerrainTileBounds | null;
+    /** Batch sample; `positions` is a Float32Array of xyz triples. */
+    sampleTerrainBatchByPosition(positions: Float32Array): TerrainSurfaceSampleBatch;
+}
+/**
+ * Cube-sphere terrain query. Extends the generic surface query with the
+ * sphere-only direction/lat-long keys. A surface location is identified by a
+ * direction from the planet center (the canonical form); `ByPosition` projects
+ * any world point onto its direction, and `ByLatLong` takes degrees (latitude
+ * `[-90, 90]`, longitude `[-180, 180]`).
+ *
+ * Exposed only when the active surface uses the `cubeSphere` projection
+ * (otherwise `null` on the query context / runtime).
+ */
+interface TerrainSphereQuery extends TerrainSurfaceQuery {
+    getElevationByDirection(direction: Vector3$1): number | null;
+    getElevationByLatLong(latitudeDeg: number, longitudeDeg: number): number | null;
+    getNormalByDirection(direction: Vector3$1): Vector3$1 | null;
+    getNormalByLatLong(latitudeDeg: number, longitudeDeg: number): Vector3$1 | null;
+    sampleTerrainByDirection(direction: Vector3$1): TerrainSurfaceSample;
+    sampleTerrainByLatLong(latitudeDeg: number, longitudeDeg: number): TerrainSurfaceSample;
+    getTileByDirection(direction: Vector3$1): TerrainTile | null;
+    getTileByLatLong(latitudeDeg: number, longitudeDeg: number): TerrainTile | null;
+    getTileBoundsByDirection(direction: Vector3$1): TerrainTileBounds | null;
+    getTileBoundsByLatLong(latitudeDeg: number, longitudeDeg: number): TerrainTileBounds | null;
+    /** Batch sample; `directions` is a Float32Array of xyz triples. */
+    sampleTerrainBatchByDirection(directions: Float32Array): TerrainSurfaceSampleBatch;
+}
+interface RaycastOptions {
+    maxSteps?: number;
+    refinementSteps?: number;
+    maxDistance?: number;
+}
+/**
+ * Shared raycast bounds for the CPU marcher. Flat raycasts use the XZ extent +
+ * `[minY, maxY]`; curved projections derive their own radial shell from their
+ * geometry plus the query's global elevation range, and only read `center*`.
+ */
+interface TerrainRaycastConfig {
+    rootSize: number;
+    originX: number;
+    originY: number;
+    originZ: number;
+    minY: number;
+    maxY: number;
+    centerX: number;
+    centerY: number;
+    centerZ: number;
+}
+interface TerrainRaycastResult {
+    position: Vector3$1;
+    normal: Vector3$1;
+    distance: number;
+}
+interface TerrainRaycast {
+    pick(ray: Ray, options?: RaycastOptions): TerrainRaycastResult | null;
+}
+
+type TerrainMeshParams = {
+    innerTileSegments: number;
+    maxNodes: number;
+    material: NodeMaterial;
+    /**
+     * Reverse tile triangle winding. Cube-sphere surfaces set this so the
+     * planet's outer shell is front-facing and renders with `FrontSide`.
+     */
+    flipWinding: boolean;
+};
+declare class TerrainMesh extends InstancedMesh {
+    private _innerTileSegments;
+    private _maxNodes;
+    private _flipWinding;
+    terrainRaycast: TerrainRaycast | null;
+    constructor(params?: Partial<TerrainMeshParams>);
+    get innerTileSegments(): number;
+    set innerTileSegments(tileSegments: number);
+    get flipWinding(): boolean;
+    set flipWinding(flip: boolean);
+    get maxNodes(): number;
+    set maxNodes(maxNodes: number);
+    raycast(raycaster: Raycaster, intersects: Intersection[]): void;
+}
+
+interface TileBoundsContext {
+    data: Float32Array<ArrayBuffer>;
+    attribute: StorageBufferAttribute;
+    node: StorageBufferNode;
+}
+
+type ComputeStageCallback = (nodeIndex: Node, globalVertexIndex: Node, uv: Node, localCoordinates: Node, texelSize: Node) => void;
+type ComputePipeline = ComputeStageCallback[];
+
+/**
+ * Default compile + execute tasks — uses terrainFieldStageTask as the leaf.
+ * Derived from the same factory as user pipelines to avoid duplicated logic.
+ */
+declare const compileComputeTask: _hello_terrain_work.Task<{
+    execute: (renderer: WebGPURenderer, instanceCount: number) => void;
+}, string, unknown>;
+declare const executeComputeTask: _hello_terrain_work.Task<any, string, {
+    renderer: WebGPURenderer;
+}>;
+/**
+ * Factory for user-extensible pipelines.
+ *
+ * Users who add custom compute stages create their own stage tasks using
+ * the accumulation pattern (`get()` predecessor, spread, append), then pass
+ * their leaf stage to this helper to get compile + execute tasks.
+ *
+ * @example
+ * ```ts
+ * const erosionStageTask = task((get, work) => {
+ *   const upstream = get(elevationFieldStageTask);
+ *   return work((): ComputePipeline => [
+ *     ...upstream,
+ *     (nodeIndex, globalVertexIndex, uv) => {
+ *       // custom erosion logic
+ *     },
+ *   ]);
+ * });
+ *
+ * const { compile, execute } = createComputePipelineTasks(erosionStageTask);
+ * ```
+ */
+declare function createComputePipelineTasks(leafStageTask: TaskRef<ComputePipeline>): {
+    compile: _hello_terrain_work.Task<{
+        execute: (renderer: WebGPURenderer, instanceCount: number) => void;
+    }, string, unknown>;
+    execute: _hello_terrain_work.Task<any, string, {
+        renderer: WebGPURenderer;
+    }>;
+};
+
 interface QuadtreeConfigState {
     state: QuadtreeState;
-    surface: Surface;
+    topology: Topology;
 }
 interface LeafGpuBufferState extends LeafStorageState {
     count: number;
@@ -597,6 +1039,10 @@ interface ElevationFieldContext {
 interface TerrainQueryContext {
     cache: CpuTerrainCache;
     query: TerrainQuery;
+    /** Generic closed-surface query; `null` on flat surfaces. */
+    surfaceQuery: TerrainSurfaceQuery | null;
+    /** Cube-sphere query; `null` unless the topology uses the cubeSphere projection. */
+    sphereQuery: TerrainSphereQuery | null;
     shapeKey: string;
 }
 /** Task refs for the standard terrain pipeline. */
@@ -604,7 +1050,7 @@ interface TerrainTasks {
     instanceId: TaskRef<string>;
     quadtreeConfig: TaskRef<QuadtreeConfigState>;
     quadtreeUpdate: TaskRef<LeafSet>;
-    surface: TaskRef<Surface>;
+    topology: TaskRef<Topology>;
     leafStorage: TaskRef<LeafStorageState>;
     leafGpuBuffer: TaskRef<LeafGpuBufferState>;
     gpuSpatialIndexStorage: TaskRef<GpuSpatialIndexContext>;
@@ -639,13 +1085,7 @@ declare const createElevationFieldContextTask: _hello_terrain_work.Task<{
     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>;
+declare const tileNodesTask: _hello_terrain_work.Task<TileCompute, string, unknown>;
 /**
  * Root compute stage — generates elevation data and writes to the
  * elevation field storage buffer. Returns a single-element `ComputePipeline`.
@@ -689,22 +1129,24 @@ declare const origin: _hello_terrain_work.ParamRef<{
     z: number;
 }>;
 /**
- * Number of segments per inner tile edge.
- * Effective edge vertex count is `innerTileSegments + 3`.
+ * Default number of segments per inner tile edge. The effective edge vertex
+ * count is `innerTileSegments + 3`
  */
 declare const innerTileSegments: _hello_terrain_work.ParamRef<number>;
 /** Skirt scale factor. */
 declare const skirtScale: _hello_terrain_work.ParamRef<number>;
 /** Elevation vertical scale. */
 declare const elevationScale: _hello_terrain_work.ParamRef<number>;
+/** Sphere radius in world units (cube-sphere projection only). */
+declare const radius: _hello_terrain_work.ParamRef<number>;
 /** Maximum quadtree nodes. */
 declare const maxNodes: _hello_terrain_work.ParamRef<number>;
 /** Maximum quadtree subdivision level. */
 declare const maxLevel: _hello_terrain_work.ParamRef<number>;
 /** Quadtree update configuration (camera, mode, etc.). */
 declare const quadtreeUpdate: _hello_terrain_work.ParamRef<UpdateParams>;
-/** Optional custom terrain surface; defaults to bounded flat surface when null. */
-declare const surface: _hello_terrain_work.ParamRef<Surface | null>;
+/** Optional custom terrain topology; defaults to bounded flat topology when null. */
+declare const topology: _hello_terrain_work.ParamRef<Topology | null>;
 /** Terrain field texture filter mode. */
 declare const terrainFieldFilter: _hello_terrain_work.ParamRef<"nearest" | "linear">;
 /** Terrain elevation control function (per vertex, in gpu compute) */
@@ -724,14 +1166,14 @@ declare const elevationFn: _hello_terrain_work.ParamRef<ElevationCallback>;
  * (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>;
+declare const positionNodeTask: _hello_terrain_work.Task<three_webgpu.Node, string, unknown>;
 
 /**
- * Derives the terrain surface from `rootSize` and `origin`.
+ * Derives the terrain topology from `rootSize` and `origin`.
  * Automatically recomputes when either param changes, keeping the
  * quadtree refinement in sync with the GPU-side tile positioning.
  */
-declare const surfaceTask: _hello_terrain_work.Task<Surface, string, unknown>;
+declare const topologyTask: _hello_terrain_work.Task<Topology, string, unknown>;
 declare const quadtreeConfigTask: _hello_terrain_work.Task<QuadtreeConfigState, string, unknown>;
 declare const quadtreeUpdateTask: _hello_terrain_work.Task<LeafSet, string, unknown>;
 /**
@@ -763,14 +1205,13 @@ declare const createUniformsTask: _hello_terrain_work.Task<TerrainUniformsContex
  */
 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 topology: _hello_terrain_work.Task<Topology, string, unknown>;
     readonly leafGpuBuffer: _hello_terrain_work.Task<{
         count: number;
         data: Int32Array<ArrayBuffer>;
@@ -781,19 +1222,13 @@ declare const terrainTasks: {
     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 positionNode: _hello_terrain_work.Task<three_webgpu.Node, 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 createTileNodes: _hello_terrain_work.Task<TileCompute, string, unknown>;
     readonly createTerrainFieldTexture: _hello_terrain_work.Task<any, string, {
         renderer: WebGPURenderer;
     }>;
@@ -818,6 +1253,7 @@ declare const terrainTasks: {
     }>;
     readonly terrainRaycast: _hello_terrain_work.Task<TerrainRaycast, string, unknown>;
 };
+declare function terrainGraph(): TerrainGraph;
 
 type ComputeDeviceLimits = {
     maxWorkgroupSizeX: number;
@@ -826,24 +1262,75 @@ type ComputeDeviceLimits = {
 };
 declare function getDeviceComputeLimits(renderer: WebGPURenderer): ComputeDeviceLimits;
 
+/**
+ * Add the cube-sphere direction samplers to a base sampler. Called from the
+ * cube-sphere projection's `gpu.augmentSampler` hook.
+ */
+declare function augmentCubeSphereSampler(sampler: TerrainSampler, params: CreateTerrainSamplerParams): void;
 declare function createTerrainSampler(params: CreateTerrainSamplerParams): TerrainSampler;
 
+/** Flat (heightfield) query, keyed on world XZ. */
 declare function createTerrainQuery(cache: CpuTerrainCache): TerrainQuery;
+/**
+ * Generic closed-surface query, keyed on a world position projected onto the
+ * surface. Cube-sphere extends this with direction/lat-long keys.
+ */
+declare function createTerrainSurfaceQuery(cache: CpuTerrainCache): TerrainSurfaceQuery;
 
-type CpuRaycastConfig = {
-    rootSize: number;
-    originX: number;
-    originZ: number;
-    minY: number;
-    maxY: number;
-};
-
-type TerrainRaycastConfig = CpuRaycastConfig;
+/**
+ * Build a terrain raycaster that delegates the projection-specific marching to
+ * the active surface projection — no branching on a projection kind here.
+ */
 declare function createTerrainRaycast(params: {
+    getProjection: () => SurfaceProjection;
     getTerrainQuery: () => TerrainQuery | null;
+    getSurfaceQuery: () => TerrainSurfaceQuery | null;
+    getSphereQuery: () => TerrainSphereQuery | null;
     getConfig: () => TerrainRaycastConfig;
 }): TerrainRaycast;
 
+type CubeFaceBasis = {
+    forward: Node;
+    right: Node;
+    up: Node;
+};
+/** Per-face basis vectors selected by the dynamic face index. */
+declare function cubeFaceBasis(face: Node): CubeFaceBasis;
+/**
+ * Cube-space point for face-local (u, v) in [0, 1]:
+ *   cube = forward + (2u-1) * right + (2v-1) * up
+ */
+declare function cubeFacePoint(basis: CubeFaceBasis, u: Node, v: Node): Node;
+/** Unit-sphere direction for face-local (u, v). */
+declare function cubeFaceDirection(basis: CubeFaceBasis, u: Node, v: Node): Node;
+/**
+ * Project a basis axis onto the tangent plane at `dir` and normalize.
+ * Used to build the sphere tangent frame for normal reconstruction.
+ */
+declare function tangentFromAxis(dir: Node, axis: Node): Node;
+/**
+ * Reconstruct a unit tangent-space normal from its packed horizontal
+ * components: `ny = sqrt(max(0, 1 - nx² - nz²))`.
+ */
+declare function unpackTangentNormal(nx: Node, nz: Node): Node;
+/**
+ * Rotate a tangent-space normal into the sphere tangent frame
+ * `(tu, dir, tv)` at `dir` and normalize.
+ *
+ * Mirrors: the CPU `computeSphereNormal` in `query/cpu-terrain-cache.ts`.
+ */
+declare function sphereTangentFrameNormal(dir: Node, basis: CubeFaceBasis, tangentNormal: Node): Node;
+/**
+ * Pick the cube face index (0..5) whose normal axis dominates `dir`.
+ * GPU mirror of `directionToFace` in `quadtree/topology/cubeSphereInverse.ts`.
+ */
+declare function cubeFaceFromDirection(dir: Node): Node;
+/**
+ * Face-local (u, v) in [0, 1] for a direction known to fall on `face`.
+ * GPU mirror of `directionToFaceUV` in `quadtree/topology/cubeSphereInverse.ts`.
+ */
+declare function cubeFaceUVFromDirection(basis: CubeFaceBasis, dir: Node): Node;
+
 /**
  * Maps a value or node from texture space [0, 1] to vector space [-1, 1].
  *
@@ -916,5 +1403,31 @@ declare const voronoiCells: three_src_nodes_TSL_js.ShaderNodeFn<[three_tsl.Proxi
     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 };
+/** Flat heightfield projection: tiles in the XZ plane, elevation along +Y. */
+declare function createFlatProjection(): SurfaceProjection;
+
+interface CubeSphereProjectionConfig {
+    radius: number;
+    center?: Vec3Like;
+    /** When true, elevation displaces inward and skirts point outward. */
+    invert?: boolean;
+}
+/** Cube-sphere projection: six faces wrapped radially onto a sphere. */
+declare function createCubeSphereProjection(config: CubeSphereProjectionConfig): SurfaceProjection;
+
+interface TorusProjectionConfig {
+    majorRadius: number;
+    minorRadius: number;
+    center?: Vec3Like;
+    /** When true, elevation displaces inward and skirts point outward. */
+    invert?: boolean;
+    /** Level-0 tile count along u before LOD subdivision (defaults to 1). */
+    baseU?: number;
+    /** Level-0 tile count along v before LOD subdivision (defaults to 1). */
+    baseV?: number;
+}
+/** Torus (donut) projection: a single closed surface periodic in both axes. */
+declare function createTorusProjection(config: TorusProjectionConfig): SurfaceProjection;
+
+export { ArrayTextureBackend, AtlasBackend, CUBE_FACES, CUBE_FACE_COUNT, Dir, TerrainGeometry, TerrainMesh, U32_EMPTY, allocLeafSet, allocSeamTable, augmentCubeSphereSampler, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, compileComputeTask, createComputePipelineTasks, createCubeSphereProjection, createCubeSphereTopology, createElevationFieldContextTask, createFlatProjection, createFlatTopology, createInfiniteFlatTopology, createSpatialIndex, createState, createTerrainFieldStorage, createTerrainFieldTextureTask, createTerrainQuery, createTerrainRaycast, createTerrainSampler, createTerrainSamplerTask, createTerrainSurfaceQuery, createTerrainUniforms, createTorusProjection, createTorusTopology, createUniformsTask, cubeFaceBasis, cubeFaceDirection, cubeFaceFromDirection, cubeFacePoint, cubeFaceUVFromDirection, deriveNormalZ, directionToFace, directionToFaceUV, directionToLatLong, elevationFieldStageTask, elevationFn, elevationScale, executeComputeTask, faceUVToCube, getDeviceComputeLimits, gpuSpatialIndexStorageTask, gpuSpatialIndexUploadTask, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, latLongToDirection, leafGpuBufferTask, leafStorageTask, loadTerrainField, loadTerrainFieldElevation, loadTerrainFieldNormal, maxLevel, maxNodes, origin, packTerrainFieldSample, positionNodeTask, positionToTorusParams, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, radius, resetLeafSet, resetSeamTable, rootSize, sampleTerrainField, sampleTerrainFieldElevation, skirtScale, sphereTangentFrameNormal, storeTerrainField, tangentFromAxis, terrainFieldFilter, terrainFieldStageTask, terrainGraph, terrainQueryTask, terrainRaycastTask, terrainReadbackTask, terrainTasks, textureSpaceToVectorSpace, tileNodesTask, topology, topologyTask, torusOutwardNormal, torusUVToPoint, unpackTangentNormal, update, updateUniformsTask, vElevation, vGlobalVertexIndex, vectorSpaceToTextureSpace, voronoiCells, wrap01 };
+export type { ComputePipeline, ComputeStageCallback, CpuSurfaceOps, CreateTerrainSamplerParams, CubeFace, CubeFaceBasis, CubeSphereProjectionConfig, CubeSphereTopologyConfig, ElevationCallback, ElevationFieldContext, ElevationParams, ElevationRange, ElevationRangeOut, FieldNormalContext, FieldNormalFn, FlatTopologyConfig, GpuSpatialIndexContext, InfiniteFlatTopologyConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodMode, ProjectionKind, ProjectionRaycastContext, QuadtreeConfig, QuadtreeConfigState, QuadtreeState, RaycastOptions, RenderVertexPositionContext, RuntimeQueries, SeamTable, SpatialIndex, SurfaceKey, SurfaceNormalContext, SurfaceProjection, SurfaceProjectionCpu, SurfaceProjectionGpu, TerrainFieldStorage, TerrainFieldStorageBackendType, TerrainFieldStorageFormat, TerrainFieldStorageOptions, TerrainGraph, TerrainQuery, TerrainQueryContext, TerrainRaycast, TerrainRaycastConfig, TerrainRaycastResult, TerrainSample, TerrainSampleBatch, TerrainSampler, TerrainSphereQuery, TerrainSurfaceQuery, TerrainSurfaceSample, TerrainSurfaceSampleBatch, TerrainTasks, TerrainTile, TerrainTileBounds, TerrainUniformsContext, TerrainUniformsParams, TileBounds, TileId, Topology, TorusProjectionConfig, TorusSurfaceParams, TorusTopologyConfig, UpdateParams, Vec3, Vec3Like, Vec3Mutable$1 as Vec3Mutable };