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

package/dist/index.d.cts

@@ -237,17 +237,6 @@ type Topology = {
      * 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.
@@ -305,42 +294,36 @@ type SeamTable = {
 declare function allocSeamTable(capacity: number): SeamTable;
 declare function resetSeamTable(seams: SeamTable): void;
 type LodMode = "distance" | "screen";
+/**
+ * How subdivision decisions are made. A discriminated union so each mode only
+ * carries (and requires) its own thresholds.
+ * - `distance` (default): split when the camera is within `distanceFactor × r`.
+ * - `screen`: split when the projected pixel radius exceeds `targetPixels`.
+ */
+type LodCriteria = {
+    mode?: "distance";
+    distanceFactor?: number;
+} | {
+    mode: "screen";
+    /** Screen-space projection factor = screenHeight / (2*tan(fovY/2)). */
+    projectionFactor: number;
+    /** Target pixel radius/size threshold for screen-space refinement. */
+    targetPixels: number;
+};
+/**
+ * Per-tile elevation range provider: previous-frame world-space displacement
+ * min/max (already scaled by `elevationScale`). Returns false when no data is
+ * available yet. Allocation-free via the `out` scratch.
+ */
+type TileElevationRangeFn = (tile: TileId, out: ElevationRangeOut) => boolean;
 type UpdateParams = {
     cameraOrigin: {
         x: number;
         y: number;
         z: number;
     };
-    /**
-     * Terrain elevation beneath the camera (from the previous frame). During
-     * refinement it offsets the camera toward the terrain surface so LOD distance
-     * is measured relative to the surface rather than the datum:
-     * - flat: subtracted from `cameraOrigin.y`.
-     * - cube-sphere: subtracted along the radial up-direction from the planet center.
-     */
-    elevationAtCameraXZ?: number;
-    /**
-     * Controls how subdivision decisions are made.
-     * `distance` is the initial focus; `screen` is supported for future parity.
-     */
-    mode?: LodMode;
-    /**
-     * Distance-based refinement threshold.
-     * Interpretation is criteria-dependent; keep it stable across surfaces by using bounds.
-     */
-    distanceFactor?: number;
-    /** Screen-space projection factor = screenHeight / (2*tan(fovY/2)) */
-    projectionFactor?: number;
-    /** Target pixel radius/size threshold for screen-space refinement */
-    targetPixels?: number;
-    /** Prevent flicker by separating split/merge thresholds (0..1 typical) */
-    hysteresis?: number;
-    /**
-     * 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;
-};
+    tileElevationRange?: TileElevationRangeFn;
+} & LodCriteria;
 type QuadtreeConfig = {
     maxNodes: number;
     maxLevel: number;
@@ -623,6 +606,12 @@ interface CpuTerrainCache {
     sampleTerrain(worldX: number, worldZ: number): TerrainSample;
     /** True when the active projection supplies surface ops. */
     readonly hasSurface: boolean;
+    /**
+     * Swap the projection surface ops (CPU position/normal math). Used when the
+     * surface geometry changes (e.g. cube-sphere radius/center) without changing
+     * the buffer shape, so picks/queries stay in sync without reallocating.
+     */
+    setSurfaceOps(surfaceOps: CpuSurfaceOps | null): void;
     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;
@@ -735,12 +724,6 @@ interface RuntimeQueries {
     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).
@@ -748,7 +731,10 @@ interface SurfaceProjectionCpu {
     createSurfaceOps(): CpuSurfaceOps | null;
     /** Build the runtime query objects the projection exposes. */
     createRuntimeQueries(cache: CpuTerrainCache): RuntimeQueries;
-    /** Projection-specific CPU raycast (precise, falling back to bounds). */
+    /**
+     * Projection-specific CPU raycast against the displaced surface. Returns
+     * `null` when the ray misses the surface or the query snapshot isn't ready.
+     */
     raycast(ctx: ProjectionRaycastContext): TerrainRaycastResult | null;
 }
 interface SurfaceProjection {
@@ -1043,7 +1029,14 @@ interface TerrainQueryContext {
     surfaceQuery: TerrainSurfaceQuery | null;
     /** Cube-sphere query; `null` unless the topology uses the cubeSphere projection. */
     sphereQuery: TerrainSphereQuery | null;
+    /** Buffer-shape identity (maxNodes/segments/projection kind); change recreates the cache. */
     shapeKey: string;
+    /**
+     * The projection these queries close over. Recreated on any geometry change
+     * (e.g. cube-sphere radius, torus major/minor); an identity change rebuilds
+     * the surface ops + queries so picks/markers stay in sync.
+     */
+    projection: SurfaceProjection;
 }
 /** Task refs for the standard terrain pipeline. */
 interface TerrainTasks {
@@ -1242,7 +1235,7 @@ declare const terrainTasks: {
         renderer: WebGPURenderer;
     }>;
     readonly tileBoundsContext: _hello_terrain_work.Task<TileBoundsContext & {
-        kernel: ReturnType<(elevationFieldNode: three_webgpu.StorageBufferNode, boundsNode: three_webgpu.StorageBufferNode, verticesPerNode: number) => three_webgpu.ComputeNode>;
+        kernel: ReturnType<(elevationFieldNode: three_webgpu.StorageBufferNode, boundsNode: three_webgpu.StorageBufferNode, verticesPerNode: number, edgeVertexCount: number) => three_webgpu.ComputeNode>;
     }, string, unknown>;
     readonly tileBoundsReduction: _hello_terrain_work.Task<any, string, {
         renderer: WebGPURenderer;
@@ -1430,4 +1423,4 @@ interface TorusProjectionConfig {
 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 };
+export type { ComputePipeline, ComputeStageCallback, CpuSurfaceOps, CreateTerrainSamplerParams, CubeFace, CubeFaceBasis, CubeSphereProjectionConfig, CubeSphereTopologyConfig, ElevationCallback, ElevationFieldContext, ElevationParams, ElevationRange, ElevationRangeOut, FieldNormalContext, FieldNormalFn, FlatTopologyConfig, GpuSpatialIndexContext, InfiniteFlatTopologyConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodCriteria, 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, TileElevationRangeFn, TileId, Topology, TorusProjectionConfig, TorusSurfaceParams, TorusTopologyConfig, UpdateParams, Vec3, Vec3Like, Vec3Mutable$1 as Vec3Mutable };

package/dist/index.d.mts

@@ -237,17 +237,6 @@ type Topology = {
      * 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.
@@ -305,42 +294,36 @@ type SeamTable = {
 declare function allocSeamTable(capacity: number): SeamTable;
 declare function resetSeamTable(seams: SeamTable): void;
 type LodMode = "distance" | "screen";
+/**
+ * How subdivision decisions are made. A discriminated union so each mode only
+ * carries (and requires) its own thresholds.
+ * - `distance` (default): split when the camera is within `distanceFactor × r`.
+ * - `screen`: split when the projected pixel radius exceeds `targetPixels`.
+ */
+type LodCriteria = {
+    mode?: "distance";
+    distanceFactor?: number;
+} | {
+    mode: "screen";
+    /** Screen-space projection factor = screenHeight / (2*tan(fovY/2)). */
+    projectionFactor: number;
+    /** Target pixel radius/size threshold for screen-space refinement. */
+    targetPixels: number;
+};
+/**
+ * Per-tile elevation range provider: previous-frame world-space displacement
+ * min/max (already scaled by `elevationScale`). Returns false when no data is
+ * available yet. Allocation-free via the `out` scratch.
+ */
+type TileElevationRangeFn = (tile: TileId, out: ElevationRangeOut) => boolean;
 type UpdateParams = {
     cameraOrigin: {
         x: number;
         y: number;
         z: number;
     };
-    /**
-     * Terrain elevation beneath the camera (from the previous frame). During
-     * refinement it offsets the camera toward the terrain surface so LOD distance
-     * is measured relative to the surface rather than the datum:
-     * - flat: subtracted from `cameraOrigin.y`.
-     * - cube-sphere: subtracted along the radial up-direction from the planet center.
-     */
-    elevationAtCameraXZ?: number;
-    /**
-     * Controls how subdivision decisions are made.
-     * `distance` is the initial focus; `screen` is supported for future parity.
-     */
-    mode?: LodMode;
-    /**
-     * Distance-based refinement threshold.
-     * Interpretation is criteria-dependent; keep it stable across surfaces by using bounds.
-     */
-    distanceFactor?: number;
-    /** Screen-space projection factor = screenHeight / (2*tan(fovY/2)) */
-    projectionFactor?: number;
-    /** Target pixel radius/size threshold for screen-space refinement */
-    targetPixels?: number;
-    /** Prevent flicker by separating split/merge thresholds (0..1 typical) */
-    hysteresis?: number;
-    /**
-     * 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;
-};
+    tileElevationRange?: TileElevationRangeFn;
+} & LodCriteria;
 type QuadtreeConfig = {
     maxNodes: number;
     maxLevel: number;
@@ -623,6 +606,12 @@ interface CpuTerrainCache {
     sampleTerrain(worldX: number, worldZ: number): TerrainSample;
     /** True when the active projection supplies surface ops. */
     readonly hasSurface: boolean;
+    /**
+     * Swap the projection surface ops (CPU position/normal math). Used when the
+     * surface geometry changes (e.g. cube-sphere radius/center) without changing
+     * the buffer shape, so picks/queries stay in sync without reallocating.
+     */
+    setSurfaceOps(surfaceOps: CpuSurfaceOps | null): void;
     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;
@@ -735,12 +724,6 @@ interface RuntimeQueries {
     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).
@@ -748,7 +731,10 @@ interface SurfaceProjectionCpu {
     createSurfaceOps(): CpuSurfaceOps | null;
     /** Build the runtime query objects the projection exposes. */
     createRuntimeQueries(cache: CpuTerrainCache): RuntimeQueries;
-    /** Projection-specific CPU raycast (precise, falling back to bounds). */
+    /**
+     * Projection-specific CPU raycast against the displaced surface. Returns
+     * `null` when the ray misses the surface or the query snapshot isn't ready.
+     */
     raycast(ctx: ProjectionRaycastContext): TerrainRaycastResult | null;
 }
 interface SurfaceProjection {
@@ -1043,7 +1029,14 @@ interface TerrainQueryContext {
     surfaceQuery: TerrainSurfaceQuery | null;
     /** Cube-sphere query; `null` unless the topology uses the cubeSphere projection. */
     sphereQuery: TerrainSphereQuery | null;
+    /** Buffer-shape identity (maxNodes/segments/projection kind); change recreates the cache. */
     shapeKey: string;
+    /**
+     * The projection these queries close over. Recreated on any geometry change
+     * (e.g. cube-sphere radius, torus major/minor); an identity change rebuilds
+     * the surface ops + queries so picks/markers stay in sync.
+     */
+    projection: SurfaceProjection;
 }
 /** Task refs for the standard terrain pipeline. */
 interface TerrainTasks {
@@ -1242,7 +1235,7 @@ declare const terrainTasks: {
         renderer: WebGPURenderer;
     }>;
     readonly tileBoundsContext: _hello_terrain_work.Task<TileBoundsContext & {
-        kernel: ReturnType<(elevationFieldNode: three_webgpu.StorageBufferNode, boundsNode: three_webgpu.StorageBufferNode, verticesPerNode: number) => three_webgpu.ComputeNode>;
+        kernel: ReturnType<(elevationFieldNode: three_webgpu.StorageBufferNode, boundsNode: three_webgpu.StorageBufferNode, verticesPerNode: number, edgeVertexCount: number) => three_webgpu.ComputeNode>;
     }, string, unknown>;
     readonly tileBoundsReduction: _hello_terrain_work.Task<any, string, {
         renderer: WebGPURenderer;
@@ -1430,4 +1423,4 @@ interface TorusProjectionConfig {
 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 };
+export type { ComputePipeline, ComputeStageCallback, CpuSurfaceOps, CreateTerrainSamplerParams, CubeFace, CubeFaceBasis, CubeSphereProjectionConfig, CubeSphereTopologyConfig, ElevationCallback, ElevationFieldContext, ElevationParams, ElevationRange, ElevationRangeOut, FieldNormalContext, FieldNormalFn, FlatTopologyConfig, GpuSpatialIndexContext, InfiniteFlatTopologyConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodCriteria, 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, TileElevationRangeFn, TileId, Topology, TorusProjectionConfig, TorusSurfaceParams, TorusTopologyConfig, UpdateParams, Vec3, Vec3Like, Vec3Mutable$1 as Vec3Mutable };

package/dist/index.d.ts

@@ -237,17 +237,6 @@ type Topology = {
      * 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.
@@ -305,42 +294,36 @@ type SeamTable = {
 declare function allocSeamTable(capacity: number): SeamTable;
 declare function resetSeamTable(seams: SeamTable): void;
 type LodMode = "distance" | "screen";
+/**
+ * How subdivision decisions are made. A discriminated union so each mode only
+ * carries (and requires) its own thresholds.
+ * - `distance` (default): split when the camera is within `distanceFactor × r`.
+ * - `screen`: split when the projected pixel radius exceeds `targetPixels`.
+ */
+type LodCriteria = {
+    mode?: "distance";
+    distanceFactor?: number;
+} | {
+    mode: "screen";
+    /** Screen-space projection factor = screenHeight / (2*tan(fovY/2)). */
+    projectionFactor: number;
+    /** Target pixel radius/size threshold for screen-space refinement. */
+    targetPixels: number;
+};
+/**
+ * Per-tile elevation range provider: previous-frame world-space displacement
+ * min/max (already scaled by `elevationScale`). Returns false when no data is
+ * available yet. Allocation-free via the `out` scratch.
+ */
+type TileElevationRangeFn = (tile: TileId, out: ElevationRangeOut) => boolean;
 type UpdateParams = {
     cameraOrigin: {
         x: number;
         y: number;
         z: number;
     };
-    /**
-     * Terrain elevation beneath the camera (from the previous frame). During
-     * refinement it offsets the camera toward the terrain surface so LOD distance
-     * is measured relative to the surface rather than the datum:
-     * - flat: subtracted from `cameraOrigin.y`.
-     * - cube-sphere: subtracted along the radial up-direction from the planet center.
-     */
-    elevationAtCameraXZ?: number;
-    /**
-     * Controls how subdivision decisions are made.
-     * `distance` is the initial focus; `screen` is supported for future parity.
-     */
-    mode?: LodMode;
-    /**
-     * Distance-based refinement threshold.
-     * Interpretation is criteria-dependent; keep it stable across surfaces by using bounds.
-     */
-    distanceFactor?: number;
-    /** Screen-space projection factor = screenHeight / (2*tan(fovY/2)) */
-    projectionFactor?: number;
-    /** Target pixel radius/size threshold for screen-space refinement */
-    targetPixels?: number;
-    /** Prevent flicker by separating split/merge thresholds (0..1 typical) */
-    hysteresis?: number;
-    /**
-     * 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;
-};
+    tileElevationRange?: TileElevationRangeFn;
+} & LodCriteria;
 type QuadtreeConfig = {
     maxNodes: number;
     maxLevel: number;
@@ -623,6 +606,12 @@ interface CpuTerrainCache {
     sampleTerrain(worldX: number, worldZ: number): TerrainSample;
     /** True when the active projection supplies surface ops. */
     readonly hasSurface: boolean;
+    /**
+     * Swap the projection surface ops (CPU position/normal math). Used when the
+     * surface geometry changes (e.g. cube-sphere radius/center) without changing
+     * the buffer shape, so picks/queries stay in sync without reallocating.
+     */
+    setSurfaceOps(surfaceOps: CpuSurfaceOps | null): void;
     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;
@@ -735,12 +724,6 @@ interface RuntimeQueries {
     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).
@@ -748,7 +731,10 @@ interface SurfaceProjectionCpu {
     createSurfaceOps(): CpuSurfaceOps | null;
     /** Build the runtime query objects the projection exposes. */
     createRuntimeQueries(cache: CpuTerrainCache): RuntimeQueries;
-    /** Projection-specific CPU raycast (precise, falling back to bounds). */
+    /**
+     * Projection-specific CPU raycast against the displaced surface. Returns
+     * `null` when the ray misses the surface or the query snapshot isn't ready.
+     */
     raycast(ctx: ProjectionRaycastContext): TerrainRaycastResult | null;
 }
 interface SurfaceProjection {
@@ -1043,7 +1029,14 @@ interface TerrainQueryContext {
     surfaceQuery: TerrainSurfaceQuery | null;
     /** Cube-sphere query; `null` unless the topology uses the cubeSphere projection. */
     sphereQuery: TerrainSphereQuery | null;
+    /** Buffer-shape identity (maxNodes/segments/projection kind); change recreates the cache. */
     shapeKey: string;
+    /**
+     * The projection these queries close over. Recreated on any geometry change
+     * (e.g. cube-sphere radius, torus major/minor); an identity change rebuilds
+     * the surface ops + queries so picks/markers stay in sync.
+     */
+    projection: SurfaceProjection;
 }
 /** Task refs for the standard terrain pipeline. */
 interface TerrainTasks {
@@ -1242,7 +1235,7 @@ declare const terrainTasks: {
         renderer: WebGPURenderer;
     }>;
     readonly tileBoundsContext: _hello_terrain_work.Task<TileBoundsContext & {
-        kernel: ReturnType<(elevationFieldNode: three_webgpu.StorageBufferNode, boundsNode: three_webgpu.StorageBufferNode, verticesPerNode: number) => three_webgpu.ComputeNode>;
+        kernel: ReturnType<(elevationFieldNode: three_webgpu.StorageBufferNode, boundsNode: three_webgpu.StorageBufferNode, verticesPerNode: number, edgeVertexCount: number) => three_webgpu.ComputeNode>;
     }, string, unknown>;
     readonly tileBoundsReduction: _hello_terrain_work.Task<any, string, {
         renderer: WebGPURenderer;
@@ -1430,4 +1423,4 @@ interface TorusProjectionConfig {
 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 };
+export type { ComputePipeline, ComputeStageCallback, CpuSurfaceOps, CreateTerrainSamplerParams, CubeFace, CubeFaceBasis, CubeSphereProjectionConfig, CubeSphereTopologyConfig, ElevationCallback, ElevationFieldContext, ElevationParams, ElevationRange, ElevationRangeOut, FieldNormalContext, FieldNormalFn, FlatTopologyConfig, GpuSpatialIndexContext, InfiniteFlatTopologyConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodCriteria, 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, TileElevationRangeFn, TileId, Topology, TorusProjectionConfig, TorusSurfaceParams, TorusTopologyConfig, UpdateParams, Vec3, Vec3Like, Vec3Mutable$1 as Vec3Mutable };