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

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { BufferGeometry, Vector3 as Vector3$1, Ray, Raycaster, Intersection } from 'three';
+import { BufferGeometry, Vector3 as Vector3$1, Ray, Raycaster, Intersection, Texture } 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 { StorageArrayTexture, StorageTexture, Node, WebGPURenderer, StorageBufferNode, StorageBufferAttribute, UniformNode, Vector3, Vector3Like, InstancedMesh, NodeMaterial, ConstNode } from 'three/webgpu';
 import Node$1 from 'three/src/nodes/core/Node.js';
 import * as _hello_terrain_work from '@hello-terrain/work';
 import { TaskRef, Graph } from '@hello-terrain/work';
@@ -105,6 +105,14 @@ declare class TerrainGeometry extends BufferGeometry {
 
 type TerrainFieldStorageBackendType = "array-texture" | "atlas" | "texture-3d";
 type TerrainFieldStorageFormat = "rgba16float" | "rgba32float";
+/** Floats stored per tile in the tile bounds GPU buffer. */
+declare const TILE_BOUNDS_FLOATS_PER_TILE = 4;
+declare const TILE_BOUNDS_LOD_MIN_OFFSET = 0;
+declare const TILE_BOUNDS_LOD_MAX_OFFSET = 1;
+declare const TILE_BOUNDS_PACK_MIN_OFFSET = 2;
+declare const TILE_BOUNDS_PACK_MAX_OFFSET = 3;
+/** Minimum elevation span (meters) when normalizing flat tiles. */
+declare const TERRAIN_FIELD_PACK_EPSILON = 0.0001;
 type TerrainFieldStorageOptions = {
     backend?: TerrainFieldStorageBackendType;
     filter?: "nearest" | "linear";
@@ -142,6 +150,14 @@ declare function sampleTerrainFieldElevation(storage: TerrainFieldStorage, u: No
  * normal through their own parametric tangent frame.
  */
 declare function packTerrainFieldSample(height: Node, normal: Node): Node;
+declare function loadTilePackBounds(boundsNode: StorageBufferNode, tileIndex: Node): {
+    packMin: three_webgpu.StorageArrayElementNode;
+    packMax: three_webgpu.StorageArrayElementNode;
+};
+/** Normalize elevation into [0, 1] for rgba16float terrain-field storage. */
+declare function packNormalizedTerrainFieldSample(height: Node, normal: Node, packMin: Node, packMax: Node): Node;
+/** Restore absolute elevation (meters) from a normalized terrain-field sample. */
+declare function denormalizeTerrainFieldElevation(normalized: Node, packMin: Node, packMax: Node): Node;
 
 interface TerrainUniformsParams {
     rootSize: number;
@@ -237,17 +253,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,64 +310,41 @@ 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;
 };
 
-type NodeStore = {
-    maxNodes: number;
-    nodesUsed: number;
-    /** generation stamping to avoid clearing buffers */
-    currentGen: number;
-    gen: Uint16Array;
-    space: Uint8Array;
-    level: Uint8Array;
-    x: Int32Array;
-    y: Int32Array;
-    /** sentinel U32_EMPTY means no children; otherwise children are [firstChild..firstChild+3] */
-    firstChild: Uint32Array;
-    flags: Uint8Array;
-    /** root node id per space */
-    roots: Uint32Array;
-};
-
 type SpatialIndex = {
     size: number;
     mask: number;
@@ -376,222 +358,6 @@ type SpatialIndex = {
 };
 declare function createSpatialIndex(maxEntries: number): SpatialIndex;
 
-/**
- * Build a spatial index for the current LeafSet.
- * Maps (space, level, x, y) -> leafIndex.
- *
- * Allocation-free if `out` is provided.
- */
-declare function buildLeafIndex(leaves: LeafSet, out?: SpatialIndex): SpatialIndex;
-
-type QuadtreeState = {
-    cfg: QuadtreeConfig;
-    store: NodeStore;
-    /** default reusable leaf buffers (capacity = cfg.maxNodes) */
-    leaves: LeafSet;
-    /** internal: node id per leaf entry (parallel to leaves.* arrays) */
-    leafNodeIds: Uint32Array;
-    /** reusable leaf spatial index (capacity = cfg.maxNodes) */
-    leafIndex: SpatialIndex;
-    /** traversal scratch */
-    stack: Uint32Array;
-    /** root nodes for this frame */
-    rootNodeIds: Uint32Array;
-    rootCount: number;
-    /** split scheduling scratch (dedupe without allocations) */
-    splitQueue: Uint32Array;
-    splitStamp: Uint16Array;
-    splitGen: number;
-    /** scratch objects to avoid allocations */
-    scratchTile: TileId;
-    scratchNeighbor: TileId;
-    scratchBounds: TileBounds;
-    scratchElevationRange: ElevationRangeOut;
-    scratchRootTiles: TileId[];
-    /** topology space count is fixed for a given state */
-    spaceCount: number;
-};
-declare function createState(cfg: QuadtreeConfig, topology: Topology): QuadtreeState;
-declare function beginUpdate(state: QuadtreeState, topology: Topology, params: UpdateParams): void;
-
-/**
- * Update the quadtree for the given topology + camera parameters.
- *
- * Produces a LeafSet of TileIds (SoA typed arrays).
- */
-declare function update(state: QuadtreeState, topology: Topology, params: UpdateParams, outLeaves?: LeafSet): LeafSet;
-
-/**
- * Build a fixed-width seam/neighbor table for balanced leaves (2:1).
- *
- * Output neighbors are leaf-list indices, with U32_EMPTY for missing entries.
- * Layout: neighbors[leafIndex * 8 + edge*2 + slot].
- */
-declare function buildSeams2to1(topology: Topology, leaves: LeafSet, outSeams: SeamTable, outIndex?: SpatialIndex): SeamTable;
-
-type FlatTopologyConfig = {
-    /**
-     * World-space size of the root tile edge.
-     * The root tile covers [-rootSize/2, +rootSize/2] around origin in X/Z.
-     */
-    rootSize: number;
-    origin: {
-        x: number;
-        y: number;
-        z: number;
-    };
-};
-declare function createFlatTopology(cfg: FlatTopologyConfig): Topology;
-
-type InfiniteFlatTopologyConfig = {
-    rootSize: number;
-    origin: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    /** half-width of root grid in root tiles (1 => 3x3 roots) */
-    rootGridRadius?: number;
-};
-declare function createInfiniteFlatTopology(cfg: InfiniteFlatTopologyConfig): Topology;
-
-type CubeSphereTopologyConfig = {
-    /** Sphere radius in world units. */
-    radius: 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;
-/**
- * Convert latitude/longitude (degrees) to a unit sphere direction.
- *
- * 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 latLongToDirection(latDeg: number, lonDeg: number, out: Vec3Mutable$1): void;
-/** Inverse of {@link latLongToDirection}; returns degrees. */
-declare function directionToLatLong(d: Vec3): {
-    latitude: number;
-    longitude: number;
-};
-
-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;
     originX: number;
@@ -623,6 +389,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;
@@ -662,6 +434,7 @@ interface RenderVertexPositionContext {
     leafStorage: LeafStorageState;
     uniforms: TerrainUniformsContext;
     terrainFieldStorage?: TerrainFieldStorage;
+    tileBoundsNode?: StorageBufferNode;
 }
 interface FieldNormalContext {
     elevationFieldNode: Node;
@@ -735,12 +508,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 +515,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 {
@@ -808,6 +578,7 @@ interface TerrainSampler {
 }
 interface CreateTerrainSamplerParams {
     terrainFieldStorage: TerrainFieldStorage;
+    tileBoundsNode: StorageBufferNode;
     spatialIndex: GpuSpatialIndexContext;
     uniforms: TerrainUniformsContext;
     elevationCallback: ElevationCallback;
@@ -979,6 +750,13 @@ interface TileBoundsContext {
     attribute: StorageBufferAttribute;
     node: StorageBufferNode;
 }
+declare function buildReductionKernel(elevationFieldNode: StorageBufferNode, boundsNode: StorageBufferNode, verticesPerNode: number, edgeVertexCount: number): three_webgpu.ComputeNode;
+declare function runTileBoundsReduction(renderer: WebGPURenderer, boundsContext: TileBoundsContext & {
+    kernel: ReturnType<typeof buildReductionKernel>;
+}, leafCount: number): void;
+declare const tileBoundsContextTask: _hello_terrain_work.Task<TileBoundsContext & {
+    kernel: ReturnType<typeof buildReductionKernel>;
+}, string, unknown>;
 
 type ComputeStageCallback = (nodeIndex: Node, globalVertexIndex: Node, uv: Node, localCoordinates: Node, texelSize: Node) => void;
 type ComputePipeline = ComputeStageCallback[];
@@ -1000,6 +778,10 @@ declare const executeComputeTask: _hello_terrain_work.Task<any, string, {
  * the accumulation pattern (`get()` predecessor, spread, append), then pass
  * their leaf stage to this helper to get compile + execute tasks.
  *
+ * When the pipeline has multiple stages, elevation (and any custom upstream
+ * stages) run first, tile bounds are reduced, then the final stage (typically
+ * terrain-field pack) runs. Keep terrain-field pack as the last stage.
+ *
  * @example
  * ```ts
  * const erosionStageTask = task((get, work) => {
@@ -1023,6 +805,243 @@ declare function createComputePipelineTasks(leafStageTask: TaskRef<ComputePipeli
         renderer: WebGPURenderer;
     }>;
 };
+/** Bounds are reduced mid-pipeline inside {@link executeComputeTask}. */
+declare const tileBoundsReductionTask: _hello_terrain_work.Task<any, string, {
+    renderer: WebGPURenderer;
+}>;
+
+type NodeStore = {
+    maxNodes: number;
+    nodesUsed: number;
+    /** generation stamping to avoid clearing buffers */
+    currentGen: number;
+    gen: Uint16Array;
+    space: Uint8Array;
+    level: Uint8Array;
+    x: Int32Array;
+    y: Int32Array;
+    /** sentinel U32_EMPTY means no children; otherwise children are [firstChild..firstChild+3] */
+    firstChild: Uint32Array;
+    flags: Uint8Array;
+    /** root node id per space */
+    roots: Uint32Array;
+};
+
+/**
+ * Build a spatial index for the current LeafSet.
+ * Maps (space, level, x, y) -> leafIndex.
+ *
+ * Allocation-free if `out` is provided.
+ */
+declare function buildLeafIndex(leaves: LeafSet, out?: SpatialIndex): SpatialIndex;
+
+type QuadtreeState = {
+    cfg: QuadtreeConfig;
+    store: NodeStore;
+    /** default reusable leaf buffers (capacity = cfg.maxNodes) */
+    leaves: LeafSet;
+    /** internal: node id per leaf entry (parallel to leaves.* arrays) */
+    leafNodeIds: Uint32Array;
+    /** reusable leaf spatial index (capacity = cfg.maxNodes) */
+    leafIndex: SpatialIndex;
+    /** traversal scratch */
+    stack: Uint32Array;
+    /** root nodes for this frame */
+    rootNodeIds: Uint32Array;
+    rootCount: number;
+    /** split scheduling scratch (dedupe without allocations) */
+    splitQueue: Uint32Array;
+    splitStamp: Uint16Array;
+    splitGen: number;
+    /** scratch objects to avoid allocations */
+    scratchTile: TileId;
+    scratchNeighbor: TileId;
+    scratchBounds: TileBounds;
+    scratchElevationRange: ElevationRangeOut;
+    scratchRootTiles: TileId[];
+    /** topology space count is fixed for a given state */
+    spaceCount: number;
+};
+declare function createState(cfg: QuadtreeConfig, topology: Topology): QuadtreeState;
+declare function beginUpdate(state: QuadtreeState, topology: Topology, params: UpdateParams): void;
+
+/**
+ * Update the quadtree for the given topology + camera parameters.
+ *
+ * Produces a LeafSet of TileIds (SoA typed arrays).
+ */
+declare function update(state: QuadtreeState, topology: Topology, params: UpdateParams, outLeaves?: LeafSet): LeafSet;
+
+/**
+ * Build a fixed-width seam/neighbor table for balanced leaves (2:1).
+ *
+ * Output neighbors are leaf-list indices, with U32_EMPTY for missing entries.
+ * Layout: neighbors[leafIndex * 8 + edge*2 + slot].
+ */
+declare function buildSeams2to1(topology: Topology, leaves: LeafSet, outSeams: SeamTable, outIndex?: SpatialIndex): SeamTable;
+
+type FlatTopologyConfig = {
+    /**
+     * World-space size of the root tile edge.
+     * The root tile covers [-rootSize/2, +rootSize/2] around origin in X/Z.
+     */
+    rootSize: number;
+    origin: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+declare function createFlatTopology(cfg: FlatTopologyConfig): Topology;
+
+type InfiniteFlatTopologyConfig = {
+    rootSize: number;
+    origin: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** half-width of root grid in root tiles (1 => 3x3 roots) */
+    rootGridRadius?: number;
+};
+declare function createInfiniteFlatTopology(cfg: InfiniteFlatTopologyConfig): Topology;
+
+type CubeSphereTopologyConfig = {
+    /** Sphere radius in world units. */
+    radius: 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;
+/**
+ * Convert latitude/longitude (degrees) to a unit sphere direction.
+ *
+ * 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 latLongToDirection(latDeg: number, lonDeg: number, out: Vec3Mutable$1): void;
+/** Inverse of {@link latLongToDirection}; returns degrees. */
+declare function directionToLatLong(d: Vec3): {
+    latitude: number;
+    longitude: number;
+};
+
+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;
 
 interface QuadtreeConfigState {
     state: QuadtreeState;
@@ -1043,7 +1062,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 {
@@ -1156,9 +1182,10 @@ declare const elevationFn: _hello_terrain_work.ParamRef<ElevationCallback>;
  * Builds the TSL position node for the terrain shader.
  *
  * Depends on leafStorageTask (buffer objects), updateUniformsTask
- * (uniform nodes), and createTerrainFieldTextureTask (combined terrain field storage).
+ * (uniform nodes), createTerrainFieldTextureTask (combined terrain field storage),
+ * and tileBoundsContextTask (per-tile pack bounds for denormalization).
  *
- * The position node reads packed terrain samples (height + normal.xz)
+ * The position node reads packed terrain samples (normalized height + normal)
  * per-vertex and assigns them to the vNormal
  * varying for use in the fragment shader.
  *
@@ -1242,7 +1269,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;
@@ -1331,6 +1358,22 @@ declare function cubeFaceFromDirection(dir: Node): Node;
  */
 declare function cubeFaceUVFromDirection(basis: CubeFaceBasis, dir: Node): Node;
 
+/**
+ * Decode an RG-packed 16-bit heightmap sample (R/G in [0, 1]) to a normalized
+ * value in [0, 1].
+ */
+declare const decodeUint16RG: three_src_nodes_TSL_js.ShaderNodeFn<[number | Node]>;
+/**
+ * Bilinearly sample an RG-packed 16-bit heightmap and return elevation in meters.
+ *
+ * @param heightmapTexture - Texture or texture node (RG encoding).
+ * @param uv - Sample coordinates in [0, 1].
+ * @param minM - Minimum elevation in meters.
+ * @param maxM - Maximum elevation in meters (unused; kept for API symmetry with range-based callers).
+ * @param rangeM - Elevation span in meters (`maxM - minM`).
+ */
+declare const sampleHeightmapMeters: three_src_nodes_TSL_js.ShaderNodeFn<[number | Node | Texture<unknown>, number | Node, number | Node, number | Node, number | Node]>;
+
 /**
  * Maps a value or node from texture space [0, 1] to vector space [-1, 1].
  *
@@ -1429,5 +1472,5 @@ interface TorusProjectionConfig {
 /** 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 };
+export { ArrayTextureBackend, AtlasBackend, CUBE_FACES, CUBE_FACE_COUNT, Dir, TERRAIN_FIELD_PACK_EPSILON, TILE_BOUNDS_FLOATS_PER_TILE, TILE_BOUNDS_LOD_MAX_OFFSET, TILE_BOUNDS_LOD_MIN_OFFSET, TILE_BOUNDS_PACK_MAX_OFFSET, TILE_BOUNDS_PACK_MIN_OFFSET, 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, decodeUint16RG, denormalizeTerrainFieldElevation, deriveNormalZ, directionToFace, directionToFaceUV, directionToLatLong, elevationFieldStageTask, elevationFn, elevationScale, executeComputeTask, faceUVToCube, getDeviceComputeLimits, gpuSpatialIndexStorageTask, gpuSpatialIndexUploadTask, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, latLongToDirection, leafGpuBufferTask, leafStorageTask, loadTerrainField, loadTerrainFieldElevation, loadTerrainFieldNormal, loadTilePackBounds, maxLevel, maxNodes, origin, packNormalizedTerrainFieldSample, packTerrainFieldSample, positionNodeTask, positionToTorusParams, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, radius, resetLeafSet, resetSeamTable, rootSize, runTileBoundsReduction, sampleHeightmapMeters, sampleTerrainField, sampleTerrainFieldElevation, skirtScale, sphereTangentFrameNormal, storeTerrainField, tangentFromAxis, terrainFieldFilter, terrainFieldStageTask, terrainGraph, terrainQueryTask, terrainRaycastTask, terrainReadbackTask, terrainTasks, textureSpaceToVectorSpace, tileBoundsContextTask, tileBoundsReductionTask, 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, 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, TileBoundsContext, TileElevationRangeFn, TileId, Topology, TorusProjectionConfig, TorusSurfaceParams, TorusTopologyConfig, UpdateParams, Vec3, Vec3Like, Vec3Mutable$1 as Vec3Mutable };