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

package/dist/index.mjs

@@ -1,32 +1,31 @@
 import { BufferGeometry, BufferAttribute, RGBAFormat, ClampToEdgeWrapping, HalfFloatType, FloatType, LinearFilter, NearestFilter, Vector3 } from 'three';
 import { MeshStandardNodeMaterial, InstancedMesh, InstancedBufferAttribute, StorageTexture, StorageArrayTexture, StorageBufferAttribute, Vector3 as Vector3$1 } from 'three/webgpu';
 import { param, task, graph } from '@hello-terrain/work';
-import { uniform, Fn, float, globalId, int, vec2, uint, If, workgroupBarrier, textureStore, uvec3, vec4, texture, ivec2, ivec3, textureLoad, pow, vec3, storage, workgroupArray, localId, workgroupId, min, Loop, max, Break, vertexIndex, uv, select, instanceIndex, positionLocal, normalLocal, remap, dot, varyingProperty, mx_noise_float, mix } from 'three/tsl';
+import { float, uniform, Fn, globalId, int, vec2, uint, If, textureStore, uvec3, vec4, texture, ivec2, ivec3, textureLoad, select, vec3, pow, storage, workgroupArray, localId, workgroupId, min, Loop, max, workgroupBarrier, Break, vertexIndex, uv, instanceIndex, positionLocal, normalLocal, remap, dot as dot$1, varyingProperty, mx_noise_float, mix } from 'three/tsl';
 import { Fn as Fn$1 } from 'three/src/nodes/TSL.js';
 
 class TerrainGeometry extends BufferGeometry {
-  constructor(innerSegments = 14, extendUV = false) {
+  /**
+   * @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 = 14, extendUV = false, flipWinding = false) {
     super();
     if (innerSegments < 1 || !Number.isFinite(innerSegments) || !Number.isInteger(innerSegments)) {
-      throw new Error(
-        `Invalid innerSegments: ${innerSegments}. Must be a positive integer.`
-      );
+      throw new Error(`Invalid innerSegments: ${innerSegments}. Must be a positive integer.`);
     }
     try {
-      this.setIndex(this.generateIndices(innerSegments));
+      this.setIndex(this.generateIndices(innerSegments, flipWinding));
       this.setAttribute(
         "position",
-        new BufferAttribute(
-          new Float32Array(this.generatePositions(innerSegments)),
-          3
-        )
+        new BufferAttribute(new Float32Array(this.generatePositions(innerSegments)), 3)
       );
       this.setAttribute(
         "normal",
-        new BufferAttribute(
-          new Float32Array(this.generateNormals(innerSegments)),
-          3
-        )
+        new BufferAttribute(new Float32Array(this.generateNormals(innerSegments)), 3)
       );
       this.setAttribute(
         "uv",
@@ -101,12 +100,16 @@ class TerrainGeometry extends BufferGeometry {
    *   triangle 1: a, c, b
    *   triangle 2: b, c, d
    */
-  generateIndices(innerSegments) {
+  generateIndices(innerSegments, flipWinding = false) {
     const innerEdgeVertexCount = innerSegments + 1;
     const edgeVertexCountWithSkirt = innerEdgeVertexCount + 2;
     const indices = [];
     const cellsPerEdge = edgeVertexCountWithSkirt - 1;
     const mid = Math.floor(cellsPerEdge / 2);
+    const pushTri = (v0, v1, v2) => {
+      if (flipWinding) indices.push(v0, v2, v1);
+      else indices.push(v0, v1, v2);
+    };
     for (let y = 0; y < cellsPerEdge; y++) {
       for (let x = 0; x < cellsPerEdge; x++) {
         const a = y * edgeVertexCountWithSkirt + x;
@@ -123,11 +126,11 @@ class TerrainGeometry extends BufferGeometry {
           useDefaultDiagonal = (x + y) % 2 === 0;
         }
         if (useDefaultDiagonal) {
-          indices.push(a, d, b);
-          indices.push(a, c, d);
+          pushTri(a, d, b);
+          pushTri(a, c, d);
         } else {
-          indices.push(a, c, b);
-          indices.push(b, c, d);
+          pushTri(a, c, b);
+          pushTri(b, c, d);
         }
       }
     }
@@ -218,32 +221,70 @@ class TerrainGeometry extends BufferGeometry {
   }
 }
 
+const rootSize = param(256).displayName("rootSize");
+const origin = param({
+  x: 0,
+  y: 0,
+  z: 0
+}).displayName("origin");
+const innerTileSegments = param(61).displayName("innerTileSegments");
+const skirtScale = param(100).displayName("skirtScale");
+const elevationScale = param(1).displayName("elevationScale");
+const radius = param(1e3).displayName("radius");
+const maxNodes = param(1024).displayName("maxNodes");
+const maxLevel = param(16).displayName("maxLevel");
+const quadtreeUpdate = param({
+  cameraOrigin: { x: 0, y: 0, z: 0 },
+  mode: "distance",
+  distanceFactor: 1.5
+}).displayName("quadtreeUpdate");
+const topology = param(null).displayName("topology");
+const terrainFieldFilter = param("linear").displayName(
+  "terrainFieldFilter"
+);
+const elevationFn = param(() => float(0));
+
 const defaultTerrainMeshParams = {
-  innerTileSegments: 14,
+  // Source of truth is the `innerTileSegments` param itself.
+  innerTileSegments: innerTileSegments.get(),
   maxNodes: 1024,
-  material: new MeshStandardNodeMaterial()
+  material: new MeshStandardNodeMaterial(),
+  flipWinding: false
 };
 class TerrainMesh extends InstancedMesh {
   _innerTileSegments;
   _maxNodes;
+  _flipWinding;
   terrainRaycast = null;
   constructor(params = defaultTerrainMeshParams) {
     const mergedParams = { ...defaultTerrainMeshParams, ...params };
-    const { innerTileSegments, maxNodes, material } = mergedParams;
-    const geometry = new TerrainGeometry(innerTileSegments, true);
+    const { innerTileSegments, maxNodes, material, flipWinding } = mergedParams;
+    const geometry = new TerrainGeometry(innerTileSegments, true, flipWinding);
     super(geometry, material, maxNodes);
     this.frustumCulled = false;
     this._innerTileSegments = innerTileSegments;
     this._maxNodes = maxNodes;
+    this._flipWinding = flipWinding;
   }
   get innerTileSegments() {
     return this._innerTileSegments;
   }
   set innerTileSegments(tileSegments) {
+    if (tileSegments === this._innerTileSegments) return;
     const oldGeometry = this.geometry;
-    this.geometry = new TerrainGeometry(tileSegments, true);
+    this.geometry = new TerrainGeometry(tileSegments, true, this._flipWinding);
     this._innerTileSegments = tileSegments;
-    setTimeout(oldGeometry.dispose);
+    setTimeout(() => oldGeometry.dispose());
+  }
+  get flipWinding() {
+    return this._flipWinding;
+  }
+  set flipWinding(flip) {
+    if (flip === this._flipWinding) return;
+    const oldGeometry = this.geometry;
+    this.geometry = new TerrainGeometry(this._innerTileSegments, true, flip);
+    this._flipWinding = flip;
+    setTimeout(() => oldGeometry.dispose());
   }
   get maxNodes() {
     return this._maxNodes;
@@ -309,13 +350,8 @@ function compileComputePipeline(stages, width, options) {
     WORKGROUP_X,
     WORKGROUP_Y
   ];
-  const preferSingleKernelWhenPossible = options?.preferSingleKernelWhenPossible ?? true;
   const uInstanceCount = uniform(0, "uint");
-  let singleKernel;
   const stagedKernelCache = /* @__PURE__ */ new Map();
-  function canRunSingleKernel(widthValue, limits) {
-    return widthValue <= limits.maxWorkgroupSizeX && widthValue <= limits.maxWorkgroupSizeY && widthValue * widthValue <= limits.maxWorkgroupInvocations;
-  }
   function clampWorkgroupToLimits(requested, limits) {
     let x = Math.max(1, Math.floor(requested[0]));
     let y = Math.max(1, Math.floor(requested[1]));
@@ -331,37 +367,6 @@ function compileComputePipeline(stages, width, options) {
     );
     return [x, y];
   }
-  function buildSingleKernel(workgroupSize) {
-    return Fn(() => {
-      bindings?.forEach((b) => b.toVar());
-      const fWidth = float(width);
-      const activeIndex = globalId.z;
-      const nodeIndex = int(activeIndex).toVar();
-      const iWidth = int(width);
-      const ix = int(globalId.x);
-      const iy = int(globalId.y);
-      const texelSize = vec2(1, 1).div(fWidth);
-      const localCoordinates = vec2(globalId.x, globalId.y);
-      const localUVCoords = localCoordinates.div(fWidth);
-      const verticesPerNode = iWidth.mul(iWidth);
-      const globalIndex = int(nodeIndex).mul(verticesPerNode).add(iy.mul(iWidth).add(ix));
-      const inBounds = ix.lessThan(iWidth).and(iy.lessThan(iWidth)).and(uint(activeIndex).lessThan(uInstanceCount)).toVar();
-      for (let i = 0; i < stages.length; i++) {
-        if (i > 0) {
-          workgroupBarrier();
-        }
-        If(inBounds, () => {
-          stages[i](
-            nodeIndex,
-            globalIndex,
-            localUVCoords,
-            localCoordinates,
-            texelSize
-          );
-        });
-      }
-    })().computeKernel(workgroupSize);
-  }
   function buildStagedKernels(workgroupSize) {
     return stages.map(
       (stage) => Fn(() => {
@@ -392,15 +397,7 @@ function compileComputePipeline(stages, width, options) {
   }
   function execute(renderer, instanceCount) {
     const limits = getDeviceComputeLimits(renderer);
-    const canUseSingleKernel = preferSingleKernelWhenPossible && canRunSingleKernel(width, limits);
     uInstanceCount.value = instanceCount;
-    if (canUseSingleKernel) {
-      if (!singleKernel) {
-        singleKernel = buildSingleKernel([width, width, 1]);
-      }
-      renderer.compute(singleKernel, [1, 1, instanceCount]);
-      return;
-    }
     const [workgroupX, workgroupY] = clampWorkgroupToLimits(
       preferredWorkgroup,
       limits
@@ -543,40 +540,9 @@ function AtlasBackend(edgeVertexCount, tileCount, options) {
     }
   };
 }
-function Texture3DBackend(edgeVertexCount, tileCount, options) {
-  let currentEdgeVertexCount = edgeVertexCount;
-  let currentTileCount = tileCount;
-  const tex = new StorageArrayTexture(
-    edgeVertexCount,
-    edgeVertexCount,
-    tileCount
-  );
-  configureStorageTexture(tex, options.format, options.filter);
-  return {
-    backendType: "texture-3d",
-    get edgeVertexCount() {
-      return currentEdgeVertexCount;
-    },
-    get tileCount() {
-      return currentTileCount;
-    },
-    texture: tex,
-    uv(ix, iy, _tileIndex) {
-      return vec2(ix.toFloat(), iy.toFloat());
-    },
-    texel(ix, iy, tileIndex) {
-      return ivec3(ix, iy, tileIndex);
-    },
-    sample(u, v, tileIndex) {
-      return texture(tex, vec2(u, v)).depth(int(tileIndex));
-    },
-    resize(width, height, nextTileCount) {
-      currentEdgeVertexCount = width;
-      currentTileCount = nextTileCount;
-      tex.setSize(width, height, nextTileCount);
-      tex.needsUpdate = true;
-    }
-  };
+function texture3DBackend(edgeVertexCount, tileCount, options) {
+  const storage = ArrayTextureBackend(edgeVertexCount, tileCount, options);
+  return { ...storage, backendType: "texture-3d" };
 }
 function tryGetDeviceLimits(renderer) {
   const backend = renderer;
@@ -590,7 +556,7 @@ function createTerrainFieldStorage(edgeVertexCount, tileCount, renderer, options
     return AtlasBackend(edgeVertexCount, tileCount, { filter, format });
   }
   if (forcedBackend === "texture-3d") {
-    return Texture3DBackend(edgeVertexCount, tileCount, { filter, format });
+    return texture3DBackend(edgeVertexCount, tileCount, { filter, format });
   }
   if (forcedBackend === "array-texture") {
     return ArrayTextureBackend(edgeVertexCount, tileCount, { filter, format });
@@ -633,10 +599,6 @@ function sampleTerrainField(storage, u, v, tileIndex) {
 function sampleTerrainFieldElevation(storage, u, v, tileIndex) {
   return sampleTerrainField(storage, u, v, tileIndex).r;
 }
-function sampleTerrainFieldNormal(storage, u, v, tileIndex) {
-  const raw = sampleTerrainField(storage, u, v, tileIndex);
-  return vec2(raw.g, raw.b);
-}
 function packTerrainFieldSample(height, normalXZ, extra = float(0)) {
   return vec4(height, normalXZ.x, normalXZ.y, extra);
 }
@@ -663,23 +625,132 @@ const createElevation = (tile, uniforms, elevationFn) => {
   };
 };
 
-function createTileCompute(leafStorage, uniforms) {
+const CUBE_FACE_COUNT = 6;
+const CUBE_FACES = [
+  // 0: +X
+  { forward: [1, 0, 0], right: [0, 0, -1], up: [0, 1, 0] },
+  // 1: -X
+  { forward: [-1, 0, 0], right: [0, 0, 1], up: [0, 1, 0] },
+  // 2: +Y (north pole)
+  { forward: [0, 1, 0], right: [1, 0, 0], up: [0, 0, -1] },
+  // 3: -Y (south pole)
+  { forward: [0, -1, 0], right: [1, 0, 0], up: [0, 0, 1] },
+  // 4: +Z
+  { forward: [0, 0, 1], right: [1, 0, 0], up: [0, 1, 0] },
+  // 5: -Z
+  { forward: [0, 0, -1], right: [-1, 0, 0], up: [0, 1, 0] }
+];
+
+function vec3Const(v) {
+  return vec3(float(v[0]), float(v[1]), float(v[2]));
+}
+function selectFaceVec3(face, pick) {
+  const last = CUBE_FACES.length - 1;
+  let acc = vec3Const(pick(CUBE_FACES[last]));
+  for (let i = last - 1; i >= 0; i--) {
+    acc = select(int(face).equal(int(i)), vec3Const(pick(CUBE_FACES[i])), acc);
+  }
+  return acc;
+}
+function cubeFaceBasis(face) {
+  return {
+    forward: selectFaceVec3(face, (f) => f.forward),
+    right: selectFaceVec3(face, (f) => f.right),
+    up: selectFaceVec3(face, (f) => f.up)
+  };
+}
+function cubeFacePoint(basis, u, v) {
+  const s = float(u).mul(2).sub(1);
+  const t = float(v).mul(2).sub(1);
+  return basis.forward.add(basis.right.mul(s)).add(basis.up.mul(t));
+}
+function cubeFaceDirection(basis, u, v) {
+  return cubeFacePoint(basis, u, v).normalize();
+}
+function tangentFromAxis(dir, axis) {
+  return axis.sub(dir.mul(dir.dot(axis))).normalize();
+}
+function unpackTangentNormal(nx, nz) {
+  const ny = float(1).sub(nx.mul(nx)).sub(nz.mul(nz)).max(float(0)).sqrt();
+  return vec3(nx, ny, nz);
+}
+function sphereTangentFrameNormal(dir, basis, tangentNormal) {
+  const n = vec3(tangentNormal);
+  const tu = tangentFromAxis(dir, basis.right);
+  const tv = tangentFromAxis(dir, basis.up);
+  return tu.mul(n.x).add(dir.mul(n.y)).add(tv.mul(n.z)).normalize();
+}
+function cubeFaceFromDirection(dir) {
+  const d = vec3(dir);
+  const ax = d.x.abs();
+  const ay = d.y.abs();
+  const az = d.z.abs();
+  const faceX = select(d.x.greaterThanEqual(float(0)), int(0), int(1));
+  const faceY = select(d.y.greaterThanEqual(float(0)), int(2), int(3));
+  const faceZ = select(d.z.greaterThanEqual(float(0)), int(4), int(5));
+  const xDominant = ax.greaterThanEqual(ay).and(ax.greaterThanEqual(az));
+  const yDominant = ay.greaterThanEqual(ax).and(ay.greaterThanEqual(az));
+  return select(xDominant, faceX, select(yDominant, faceY, faceZ));
+}
+function cubeFaceUVFromDirection(basis, dir) {
+  const d = vec3(dir);
+  const p = d.div(d.dot(basis.forward));
+  const s = p.dot(basis.right);
+  const t = p.dot(basis.up);
+  return vec2(s.add(float(1)).mul(float(0.5)), t.add(float(1)).mul(float(0.5)));
+}
+
+const HALF_PI = Math.PI * 0.5;
+const FIELD_INNER_TEXEL_OFFSET = 1.5;
+const FIELD_EDGE_EXTRA_TEXELS = 3;
+function sphereTileArcLength(radius, levelDivisor) {
+  return radius * HALF_PI / levelDivisor;
+}
+function decodeLeafTile(leafStorage, nodeIndex) {
+  const nodeOffset = int(nodeIndex).mul(int(4));
+  return {
+    level: leafStorage.node.element(nodeOffset).toInt(),
+    x: leafStorage.node.element(nodeOffset.add(int(1))).toFloat(),
+    y: leafStorage.node.element(nodeOffset.add(int(2))).toFloat(),
+    face: leafStorage.node.element(nodeOffset.add(int(3))).toInt()
+  };
+}
+function faceUVFromTileLocal(tile, localU, localV) {
+  const n = pow(float(2), tile.level.toFloat());
+  return vec2(tile.x.add(localU).div(n), tile.y.add(localV).div(n));
+}
+function createTileCompute(leafStorage, uniforms, projection = "flat") {
+  const isSphere = projection === "cubeSphere";
   const tileLevel = Fn(([nodeIndex]) => {
-    const nodeOffset = nodeIndex.mul(int(4));
-    return leafStorage.node.element(nodeOffset).toInt();
+    return decodeLeafTile(leafStorage, nodeIndex).level;
+  });
+  const tileFace = Fn(([nodeIndex]) => {
+    return decodeLeafTile(leafStorage, nodeIndex).face;
   });
   const tileOriginVec2 = Fn(([nodeIndex]) => {
-    const nodeOffset = nodeIndex.mul(int(4));
-    const nodeX = leafStorage.node.element(nodeOffset.add(int(1))).toFloat();
-    const nodeY = leafStorage.node.element(nodeOffset.add(int(2))).toFloat();
-    return vec2(nodeX, nodeY);
+    const tile = decodeLeafTile(leafStorage, nodeIndex);
+    return vec2(tile.x, tile.y);
   });
   const tileSize = Fn(([nodeIndex]) => {
-    const rootSize = uniforms.uRootSize.toVar();
     const level = tileLevel(nodeIndex);
-    return float(rootSize).div(pow(float(2), level.toFloat()));
+    const divisor = pow(float(2), level.toFloat());
+    if (isSphere) {
+      return uniforms.uRadius.toVar().mul(float(HALF_PI)).div(divisor);
+    }
+    const rootSize = uniforms.uRootSize.toVar();
+    return float(rootSize).div(divisor);
+  });
+  const tileFaceUV = Fn(([nodeIndex, ix, iy]) => {
+    const tile = decodeLeafTile(leafStorage, nodeIndex);
+    const fInnerSegments = uniforms.uInnerTileSegments.toVar().toFloat();
+    const localU = int(ix).toFloat().sub(float(1)).div(fInnerSegments);
+    const localV = int(iy).toFloat().sub(float(1)).div(fInnerSegments);
+    return faceUVFromTileLocal(tile, localU, localV);
   });
   const rootUVCompute = Fn(([nodeIndex, ix, iy]) => {
+    if (isSphere) {
+      return tileFaceUV(nodeIndex, ix, iy);
+    }
     const nodeVec2 = tileOriginVec2(nodeIndex);
     const nodeX = nodeVec2.x;
     const nodeY = nodeVec2.y;
@@ -704,6 +775,12 @@ function createTileCompute(leafStorage, uniforms) {
   const tileVertexWorldPositionCompute = Fn(
     ([nodeIndex, ix, iy]) => {
       const rootOrigin = uniforms.uRootOrigin.toVar();
+      if (isSphere) {
+        const faceUV = tileFaceUV(nodeIndex, ix, iy);
+        const basis = cubeFaceBasis(tileFace(nodeIndex));
+        const dir = cubeFaceDirection(basis, faceUV.x, faceUV.y);
+        return rootOrigin.add(dir.mul(uniforms.uRadius.toVar()));
+      }
       const nodeVec2 = tileOriginVec2(nodeIndex);
       const nodeX = nodeVec2.x;
       const nodeY = nodeVec2.y;
@@ -722,36 +799,22 @@ function createTileCompute(leafStorage, uniforms) {
   );
   return {
     tileLevel,
+    tileFace,
     tileOriginVec2,
     tileSize,
+    tileFaceUV,
     rootUVCompute,
     tileVertexWorldPositionCompute
   };
 }
-function tileLocalToFieldUV$1(localCoord, innerSegments) {
-  const edge = float(innerSegments).add(float(3));
-  return float(localCoord).mul(float(innerSegments)).add(float(1.5)).div(edge);
+function tileLocalToFieldUV(localCoord, innerSegments) {
+  const edge = float(innerSegments).add(float(FIELD_EDGE_EXTRA_TEXELS));
+  return float(localCoord).mul(float(innerSegments)).add(float(FIELD_INNER_TEXEL_OFFSET)).div(edge);
+}
+function tileLocalToFieldUVNumber(localCoord, innerSegments) {
+  const edge = innerSegments + FIELD_EDGE_EXTRA_TEXELS;
+  return (localCoord * innerSegments + FIELD_INNER_TEXEL_OFFSET) / edge;
 }
-
-const rootSize = param(256).displayName("rootSize");
-const origin = param({
-  x: 0,
-  y: 0,
-  z: 0
-}).displayName("origin");
-const innerTileSegments = param(13).displayName("innerTileSegments");
-const skirtScale = param(100).displayName("skirtScale");
-const elevationScale = param(1).displayName("elevationScale");
-const maxNodes = param(1024).displayName("maxNodes");
-const maxLevel = param(16).displayName("maxLevel");
-const quadtreeUpdate = param({
-  cameraOrigin: { x: 0, y: 0, z: 0 },
-  mode: "distance",
-  distanceFactor: 1.5
-}).displayName("quadtreeUpdate");
-const surface = param(null).displayName("surface");
-const terrainFieldFilter = param("linear").displayName("terrainFieldFilter");
-const elevationFn = param(() => float(0));
 
 function createLeafStorage(maxNodes) {
   const data = new Int32Array(maxNodes * 4);
@@ -936,10 +999,10 @@ function buildLeafIndex(leaves, out) {
   return index;
 }
 
-function createState(cfg, surface) {
-  const store = createNodeStore(cfg.maxNodes, surface.spaceCount);
+function createState(cfg, topology) {
+  const store = createNodeStore(cfg.maxNodes, topology.spaceCount);
   const scratchRootTiles = [];
-  for (let i = 0; i < surface.maxRootCount; i++) {
+  for (let i = 0; i < topology.maxRootCount; i++) {
     scratchRootTiles.push({ space: 0, level: 0, x: 0, y: 0 });
   }
   return {
@@ -949,7 +1012,7 @@ function createState(cfg, surface) {
     leafNodeIds: new Uint32Array(cfg.maxNodes),
     leafIndex: createSpatialIndex(cfg.maxNodes),
     stack: new Uint32Array(cfg.maxNodes),
-    rootNodeIds: new Uint32Array(surface.maxRootCount),
+    rootNodeIds: new Uint32Array(topology.maxRootCount),
     rootCount: 0,
     splitQueue: new Uint32Array(cfg.maxNodes),
     splitStamp: new Uint16Array(cfg.maxNodes),
@@ -958,25 +1021,25 @@ function createState(cfg, surface) {
     scratchNeighbor: { space: 0, level: 0, x: 0, y: 0 },
     scratchBounds: { cx: 0, cy: 0, cz: 0, r: 0 },
     scratchRootTiles,
-    spaceCount: surface.spaceCount
+    spaceCount: topology.spaceCount
   };
 }
-function beginUpdate(state, surface, params) {
-  if (surface.spaceCount !== state.spaceCount) {
+function beginUpdate(state, topology, params) {
+  if (topology.spaceCount !== state.spaceCount) {
     throw new Error(
-      `Surface spaceCount changed (${state.spaceCount} -> ${surface.spaceCount}). Create a new quadtree state.`
+      `Topology spaceCount changed (${state.spaceCount} -> ${topology.spaceCount}). Create a new quadtree state.`
     );
   }
-  if (surface.maxRootCount !== state.rootNodeIds.length) {
+  if (topology.maxRootCount !== state.rootNodeIds.length) {
     throw new Error(
-      `Surface maxRootCount changed (${state.rootNodeIds.length} -> ${surface.maxRootCount}). Create a new quadtree state.`
+      `Topology maxRootCount changed (${state.rootNodeIds.length} -> ${topology.maxRootCount}). Create a new quadtree state.`
     );
   }
   beginFrame(state.store);
   state.rootCount = 0;
-  const rootCount = surface.rootTiles(params.cameraOrigin, state.scratchRootTiles);
-  if (rootCount < 0 || rootCount > surface.maxRootCount) {
-    throw new Error(`Surface returned invalid root count (${rootCount}).`);
+  const rootCount = topology.rootTiles(params.cameraOrigin, state.scratchRootTiles);
+  if (rootCount < 0 || rootCount > topology.maxRootCount) {
+    throw new Error(`Topology returned invalid root count (${rootCount}).`);
   }
   for (let i = 0; i < rootCount; i++) {
     const rootId = allocNode(state.store, state.scratchRootTiles[i]);
@@ -1013,7 +1076,7 @@ function shouldSplit(bounds, level, maxLevel, params) {
   return safeDistSq < threshold * threshold;
 }
 
-function refineLeaves(state, surface, params, outLeaves) {
+function refineLeaves(state, topology, params, outLeaves) {
   const leaves = outLeaves ?? state.leaves;
   resetLeafSet(leaves);
   const store = state.store;
@@ -1034,7 +1097,7 @@ function refineLeaves(state, surface, params, outLeaves) {
     tile.x = x;
     tile.y = y;
     const bounds = state.scratchBounds;
-    surface.tileBounds(tile, params.cameraOrigin, bounds);
+    topology.tileBounds(tile, params.cameraOrigin, bounds);
     if (hasChildren(store, nodeId)) {
       const base = store.firstChild[nodeId];
       stack[sp++] = base + 3;
@@ -1082,7 +1145,7 @@ function scheduleSplit(state, nodeId, count) {
   state.splitQueue[count] = nodeId;
   return count + 1;
 }
-function balance2to1(state, surface, params, leaves) {
+function balance2to1(state, topology, params, leaves) {
   const maxIters = state.cfg.maxLevel + 1;
   for (let iter = 0; iter < maxIters; iter++) {
     const index = buildLeafIndex(leaves, state.leafIndex);
@@ -1103,7 +1166,7 @@ function balance2to1(state, surface, params, leaves) {
           tile.x = leafX >>> shift;
           tile.y = leafY >>> shift;
           const neighbor = state.scratchNeighbor;
-          if (!surface.neighborSameLevel(tile, dir, neighbor)) break;
+          if (!topology.neighborSameLevel(tile, dir, neighbor)) break;
           const j = lookupSpatialIndexRaw(
             index,
             neighbor.space,
@@ -1127,18 +1190,38 @@ function balance2to1(state, surface, params, leaves) {
       if (base !== U32_EMPTY) anySplit = true;
     }
     if (!anySplit) return leaves;
-    refineLeaves(state, surface, params, leaves);
+    refineLeaves(state, topology, params, leaves);
   }
   return leaves;
 }
 
-function update(state, surface, params, outLeaves) {
-  const origY = params.cameraOrigin.y;
-  params.cameraOrigin.y -= params.elevationAtCameraXZ ?? 0;
-  beginUpdate(state, surface, params);
-  const leaves = refineLeaves(state, surface, params, outLeaves);
-  const result = balance2to1(state, surface, params, leaves);
-  params.cameraOrigin.y = origY;
+function update(state, topology, params, outLeaves) {
+  const cam = params.cameraOrigin;
+  const elevation = params.elevationAtCameraXZ ?? 0;
+  const origX = cam.x;
+  const origY = cam.y;
+  const origZ = cam.z;
+  if (topology.projection === "cubeSphere") {
+    const center = topology.center ?? { x: 0, y: 0, z: 0 };
+    const dx = cam.x - center.x;
+    const dy = cam.y - center.y;
+    const dz = cam.z - center.z;
+    const len = Math.hypot(dx, dy, dz);
+    if (len > 1e-12) {
+      const inv = elevation / len;
+      cam.x -= dx * inv;
+      cam.y -= dy * inv;
+      cam.z -= dz * inv;
+    }
+  } else {
+    cam.y -= elevation;
+  }
+  beginUpdate(state, topology, params);
+  const leaves = refineLeaves(state, topology, params, outLeaves);
+  const result = balance2to1(state, topology, params, leaves);
+  cam.x = origX;
+  cam.y = origY;
+  cam.z = origZ;
   return result;
 }
 
@@ -1146,7 +1229,7 @@ const scratchTile = { space: 0, level: 0, x: 0, y: 0 };
 const scratchNbr = { space: 0, level: 0, x: 0, y: 0 };
 const scratchParentTile = { space: 0, level: 0, x: 0, y: 0 };
 const scratchParentNbr = { space: 0, level: 0, x: 0, y: 0 };
-function buildSeams2to1(surface, leaves, outSeams, outIndex) {
+function buildSeams2to1(topology, leaves, outSeams, outIndex) {
   if (outSeams.capacity < leaves.count) {
     throw new Error("SeamTable capacity is smaller than LeafSet.count.");
   }
@@ -1167,7 +1250,7 @@ function buildSeams2to1(surface, leaves, outSeams, outIndex) {
       scratchTile.level = level;
       scratchTile.x = x;
       scratchTile.y = y;
-      if (!surface.neighborSameLevel(scratchTile, dir, scratchNbr)) continue;
+      if (!topology.neighborSameLevel(scratchTile, dir, scratchNbr)) continue;
       let j = lookupSpatialIndexRaw(index, scratchNbr.space, scratchNbr.level, scratchNbr.x, scratchNbr.y);
       if (j !== U32_EMPTY) {
         neighbors[outOffset + 0] = j;
@@ -1180,7 +1263,7 @@ function buildSeams2to1(surface, leaves, outSeams, outIndex) {
         scratchParentTile.level = level - 1;
         scratchParentTile.x = px;
         scratchParentTile.y = py;
-        if (surface.neighborSameLevel(scratchParentTile, dir, scratchParentNbr)) {
+        if (topology.neighborSameLevel(scratchParentTile, dir, scratchParentNbr)) {
           j = lookupSpatialIndexRaw(
             index,
             scratchParentNbr.space,
@@ -1236,10 +1319,10 @@ function buildSeams2to1(surface, leaves, outSeams, outIndex) {
   return outSeams;
 }
 
-function createFlatSurface(cfg) {
+function createFlatTopology(cfg) {
   const halfRoot = 0.5 * cfg.rootSize;
   const maxHeight = cfg.maxHeight ?? 0;
-  const surface = {
+  const topology = {
     spaceCount: 1,
     maxRootCount: 1,
     neighborSameLevel(tile, dir, out) {
@@ -1294,10 +1377,10 @@ function createFlatSurface(cfg) {
       return 1;
     }
   };
-  return surface;
+  return topology;
 }
 
-function createInfiniteFlatSurface(cfg) {
+function createInfiniteFlatTopology(cfg) {
   const halfRoot = 0.5 * cfg.rootSize;
   const maxHeight = cfg.maxHeight ?? 0;
   const rootGridRadius = Math.max(0, Math.floor(cfg.rootGridRadius ?? 1));
@@ -1361,18 +1444,158 @@ function createInfiniteFlatSurface(cfg) {
   };
 }
 
-function createCubeSphereSurface(_cfg) {
+const DEG_TO_RAD = Math.PI / 180;
+const RAD_TO_DEG = 180 / Math.PI;
+function dot(a, b) {
+  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+function faceUVToCube(face, u, v, out) {
+  const f = CUBE_FACES[face];
+  const s = 2 * u - 1;
+  const t = 2 * v - 1;
+  out[0] = f.forward[0] + s * f.right[0] + t * f.up[0];
+  out[1] = f.forward[1] + s * f.right[1] + t * f.up[1];
+  out[2] = f.forward[2] + s * f.right[2] + t * f.up[2];
+}
+function directionToFace(d) {
+  const ax = Math.abs(d[0]);
+  const ay = Math.abs(d[1]);
+  const az = Math.abs(d[2]);
+  if (ax >= ay && ax >= az) return d[0] >= 0 ? 0 : 1;
+  if (ay >= ax && ay >= az) return d[1] >= 0 ? 2 : 3;
+  return d[2] >= 0 ? 4 : 5;
+}
+function directionToFaceUV(face, d, out) {
+  const f = CUBE_FACES[face];
+  const denom = dot(d, f.forward);
+  const inv = 1 / denom;
+  const px = d[0] * inv;
+  const py = d[1] * inv;
+  const pz = d[2] * inv;
+  const p = [px, py, pz];
+  const s = dot(p, f.right);
+  const t = dot(p, f.up);
+  out[0] = (s + 1) * 0.5;
+  out[1] = (t + 1) * 0.5;
+}
+function latLongToDirection(latDeg, lonDeg, out) {
+  const lat = latDeg * DEG_TO_RAD;
+  const lon = lonDeg * DEG_TO_RAD;
+  const cosLat = Math.cos(lat);
+  out[0] = cosLat * Math.sin(lon);
+  out[1] = Math.sin(lat);
+  out[2] = cosLat * Math.cos(lon);
+}
+function directionToLatLong(d) {
+  const len = Math.hypot(d[0], d[1], d[2]) || 1;
+  const y = Math.max(-1, Math.min(1, d[1] / len));
+  return {
+    latitude: Math.asin(y) * RAD_TO_DEG,
+    longitude: Math.atan2(d[0], d[2]) * RAD_TO_DEG
+  };
+}
+
+function createCubeSphereTopology(cfg) {
+  const radius = cfg.radius;
+  const maxHeight = cfg.maxHeight ?? 0;
+  const center = cfg.center ?? { x: 0, y: 0, z: 0 };
+  const cube = [0, 0, 0];
+  const uv = [0, 0];
+  function crossFaceNeighbor(face, level, nx, ny, out) {
+    const n = 1 << level;
+    const u = (nx + 0.5) / n;
+    const v = (ny + 0.5) / n;
+    faceUVToCube(face, u, v, cube);
+    const len = Math.hypot(cube[0], cube[1], cube[2]);
+    const dir = [cube[0] / len, cube[1] / len, cube[2] / len];
+    const nbrFace = directionToFace(dir);
+    directionToFaceUV(nbrFace, dir, uv);
+    let bx = Math.floor(uv[0] * n);
+    let by = Math.floor(uv[1] * n);
+    if (bx < 0) bx = 0;
+    else if (bx > n - 1) bx = n - 1;
+    if (by < 0) by = 0;
+    else if (by > n - 1) by = n - 1;
+    out.space = nbrFace;
+    out.level = level;
+    out.x = bx;
+    out.y = by;
+  }
   return {
     spaceCount: 6,
     maxRootCount: 6,
-    neighborSameLevel(_tile, _dir, _out) {
-      return false;
+    neighborSameLevel(tile, dir, out) {
+      const level = tile.level;
+      const n = 1 << level;
+      let nx = tile.x;
+      let ny = tile.y;
+      switch (dir) {
+        case 0:
+          nx -= 1;
+          break;
+        case 1:
+          nx += 1;
+          break;
+        case 2:
+          ny -= 1;
+          break;
+        case 3:
+          ny += 1;
+          break;
+      }
+      if (nx >= 0 && ny >= 0 && nx < n && ny < n) {
+        out.space = tile.space;
+        out.level = level;
+        out.x = nx;
+        out.y = ny;
+        return true;
+      }
+      crossFaceNeighbor(tile.space, level, nx, ny, out);
+      return true;
     },
-    tileBounds(_tile, _cameraOrigin, out) {
-      out.cx = 0;
-      out.cy = 0;
-      out.cz = 0;
-      out.r = Number.MAX_VALUE;
+    tileBounds(tile, cameraOrigin, out) {
+      const level = tile.level;
+      const n = 1 << level;
+      const u0 = tile.x / n;
+      const u1 = (tile.x + 1) / n;
+      const v0 = tile.y / n;
+      const v1 = (tile.y + 1) / n;
+      const cornersU = [u0, u1, u0, u1];
+      const cornersV = [v0, v0, v1, v1];
+      let sumX = 0;
+      let sumY = 0;
+      let sumZ = 0;
+      const px = [0, 0, 0, 0];
+      const py = [0, 0, 0, 0];
+      const pz = [0, 0, 0, 0];
+      for (let i = 0; i < 4; i++) {
+        faceUVToCube(tile.space, cornersU[i], cornersV[i], cube);
+        const len = Math.hypot(cube[0], cube[1], cube[2]);
+        const sx = center.x + cube[0] / len * radius;
+        const sy = center.y + cube[1] / len * radius;
+        const sz = center.z + cube[2] / len * radius;
+        px[i] = sx;
+        py[i] = sy;
+        pz[i] = sz;
+        sumX += sx;
+        sumY += sy;
+        sumZ += sz;
+      }
+      const cX = sumX * 0.25;
+      const cY = sumY * 0.25;
+      const cZ = sumZ * 0.25;
+      let maxDistSq = 0;
+      for (let i = 0; i < 4; i++) {
+        const dx = px[i] - cX;
+        const dy = py[i] - cY;
+        const dz = pz[i] - cZ;
+        const dSq = dx * dx + dy * dy + dz * dz;
+        if (dSq > maxDistSq) maxDistSq = dSq;
+      }
+      out.cx = cX - cameraOrigin.x;
+      out.cy = cY - cameraOrigin.y;
+      out.cz = cZ - cameraOrigin.z;
+      out.r = Math.sqrt(maxDistSq) + maxHeight;
     },
     rootTiles(_cameraOrigin, out) {
       for (let s = 0; s < 6; s++) {
@@ -1383,10 +1606,141 @@ function createCubeSphereSurface(_cfg) {
         root.y = 0;
       }
       return 6;
-    }
+    },
+    projection: "cubeSphere",
+    radius,
+    center
   };
 }
 
+function readHeight(elevation, shape, leafIndex, ix, iy) {
+  const base = leafIndex * shape.verticesPerNode;
+  return elevation[base + iy * shape.edgeVertexCount + ix] ?? 0;
+}
+function sampleGridBilinear(elevation, shape, leafIndex, gx, gy) {
+  const max = shape.edgeVertexCount - 1;
+  const x = Math.max(0, Math.min(max, gx));
+  const y = Math.max(0, Math.min(max, gy));
+  const x0 = Math.floor(x);
+  const y0 = Math.floor(y);
+  const x1 = Math.min(max, x0 + 1);
+  const y1 = Math.min(max, y0 + 1);
+  const tx = x - x0;
+  const ty = y - y0;
+  const h00 = readHeight(elevation, shape, leafIndex, x0, y0);
+  const h10 = readHeight(elevation, shape, leafIndex, x1, y0);
+  const h01 = readHeight(elevation, shape, leafIndex, x0, y1);
+  const h11 = readHeight(elevation, shape, leafIndex, x1, y1);
+  const hx0 = h00 + (h10 - h00) * tx;
+  const hx1 = h01 + (h11 - h01) * tx;
+  return hx0 + (hx1 - hx0) * ty;
+}
+function elevationGradientAt(elevation, shape, leafIndex, gx, gy, stepWorld, elevationScale, out) {
+  const hLeft = sampleGridBilinear(elevation, shape, leafIndex, gx - 1, gy);
+  const hRight = sampleGridBilinear(elevation, shape, leafIndex, gx + 1, gy);
+  const hUp = sampleGridBilinear(elevation, shape, leafIndex, gx, gy - 1);
+  const hDown = sampleGridBilinear(elevation, shape, leafIndex, gx, gy + 1);
+  const inv2Step = 0.5 / stepWorld;
+  out.dhdu = (hRight - hLeft) * elevationScale * inv2Step;
+  out.dhdv = (hDown - hUp) * elevationScale * inv2Step;
+  return out;
+}
+
+const MISSED_LOOKUP = Object.freeze({
+  found: false,
+  leafIndex: -1,
+  space: -1,
+  level: -1,
+  tileX: -1,
+  tileY: -1,
+  tileSize: 0,
+  localU: 0,
+  localV: 0
+});
+function lookupTile(index, config, worldX, worldZ) {
+  const halfRoot = config.rootSize * 0.5;
+  for (let level = config.maxLevel; level >= 0; level -= 1) {
+    const scale = 2 ** level;
+    const tileSize = config.rootSize / scale;
+    const tileX = Math.floor((worldX - config.originX + halfRoot) / tileSize);
+    const tileY = Math.floor((worldZ - config.originZ + halfRoot) / tileSize);
+    const leafIndex = lookupSpatialIndexRaw(index, 0, level, tileX, tileY);
+    if (leafIndex !== U32_EMPTY) {
+      const tileMinX = config.originX + tileX * tileSize - halfRoot;
+      const tileMinZ = config.originZ + tileY * tileSize - halfRoot;
+      return {
+        found: true,
+        leafIndex,
+        space: 0,
+        level,
+        tileX,
+        tileY,
+        tileSize,
+        localU: (worldX - tileMinX) / tileSize,
+        localV: (worldZ - tileMinZ) / tileSize
+      };
+    }
+  }
+  return MISSED_LOOKUP;
+}
+function clamp01(value) {
+  return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function lookupTileByFaceUV(index, config, face, u, v) {
+  for (let level = config.maxLevel; level >= 0; level -= 1) {
+    const n = 2 ** level;
+    let tileX = Math.floor(u * n);
+    let tileY = Math.floor(v * n);
+    if (tileX < 0) tileX = 0;
+    else if (tileX > n - 1) tileX = n - 1;
+    if (tileY < 0) tileY = 0;
+    else if (tileY > n - 1) tileY = n - 1;
+    const leafIndex = lookupSpatialIndexRaw(index, face, level, tileX, tileY);
+    if (leafIndex !== U32_EMPTY) {
+      const tileSize = sphereTileArcLength(config.radius, n);
+      return {
+        found: true,
+        leafIndex,
+        space: face,
+        level,
+        tileX,
+        tileY,
+        tileSize,
+        localU: clamp01(u * n - tileX),
+        localV: clamp01(v * n - tileY)
+      };
+    }
+  }
+  return MISSED_LOOKUP;
+}
+function lookupTileForDirection(index, config, dx, dy, dz, dirScratch, uvScratch) {
+  if (config.projection !== "cubeSphere") return MISSED_LOOKUP;
+  const len = Math.hypot(dx, dy, dz);
+  if (len === 0) return MISSED_LOOKUP;
+  dirScratch[0] = dx / len;
+  dirScratch[1] = dy / len;
+  dirScratch[2] = dz / len;
+  const face = directionToFace(dirScratch);
+  directionToFaceUV(face, dirScratch, uvScratch);
+  return lookupTileByFaceUV(index, config, face, uvScratch[0], uvScratch[1]);
+}
+
+function createTerrainSnapshotState(maxNodes, totalElements) {
+  return {
+    frontElevation: new Float32Array(totalElements),
+    backElevation: new Float32Array(totalElements),
+    frontIndex: createSpatialIndex(maxNodes),
+    backIndex: createSpatialIndex(maxNodes),
+    frontTileBounds: new Float32Array(maxNodes * 2),
+    backTileBounds: new Float32Array(maxNodes * 2),
+    frontLeafCount: 0,
+    globalRange: null,
+    hasSnapshot: false,
+    readbackPending: false,
+    generation: 0,
+    lastScheduledStampGen: -1
+  };
+}
 function cloneSpatialIndex(target, source) {
   if (target.size !== source.size) {
     throw new Error(
@@ -1402,218 +1756,278 @@ function cloneSpatialIndex(target, source) {
   target.keysY.set(source.keysY);
   target.values.set(source.values);
 }
-function tileLocalToFieldUV(localCoord, innerSegments) {
-  const edge = innerSegments + 3;
-  return (localCoord * innerSegments + 1.5) / edge;
+function triggerSnapshotReadback(state, renderer, attribute, spatialIndex, boundsAttribute, captured) {
+  if (state.readbackPending) return;
+  const withReadback = renderer;
+  if (!withReadback.getArrayBufferAsync) return;
+  if (spatialIndex.stampGen === state.lastScheduledStampGen) return;
+  cloneSpatialIndex(state.backIndex, spatialIndex);
+  state.lastScheduledStampGen = spatialIndex.stampGen;
+  const { activeLeafCount, totalElements, elevationScale, originY } = captured;
+  state.readbackPending = true;
+  const elevationPromise = withReadback.getArrayBufferAsync(attribute);
+  const boundsPromise = boundsAttribute ? withReadback.getArrayBufferAsync(boundsAttribute) : null;
+  const onComplete = (elevResult, boundsResult) => {
+    const data = new Float32Array(elevResult);
+    state.backElevation.fill(0);
+    state.backElevation.set(data.subarray(0, totalElements));
+    let boundsValid = activeLeafCount === 0;
+    if (boundsResult) {
+      const rawBounds = new Float32Array(boundsResult);
+      state.backTileBounds.fill(0);
+      state.backTileBounds.set(rawBounds.subarray(0, activeLeafCount * 2));
+      for (let i = 0; i < activeLeafCount; i += 1) {
+        if ((rawBounds[i * 2 + 1] ?? 0) !== 0) {
+          boundsValid = true;
+          break;
+        }
+      }
+    }
+    const oldFrontElevation = state.frontElevation;
+    const oldFrontIndex = state.frontIndex;
+    state.frontElevation = state.backElevation;
+    state.frontIndex = state.backIndex;
+    state.frontLeafCount = activeLeafCount;
+    state.backElevation = oldFrontElevation;
+    state.backIndex = oldFrontIndex;
+    if (boundsResult && boundsValid) {
+      const oldFrontBounds = state.frontTileBounds;
+      state.frontTileBounds = state.backTileBounds;
+      state.backTileBounds = oldFrontBounds;
+    }
+    if (boundsResult && boundsValid && activeLeafCount > 0) {
+      let gMin = Infinity;
+      let gMax = -Infinity;
+      for (let i = 0; i < activeLeafCount; i++) {
+        const rawMin = state.frontTileBounds[i * 2];
+        const rawMax = state.frontTileBounds[i * 2 + 1];
+        const a = originY + rawMin * elevationScale;
+        const b = originY + rawMax * elevationScale;
+        gMin = Math.min(gMin, a, b);
+        gMax = Math.max(gMax, a, b);
+      }
+      state.globalRange = { min: gMin, max: gMax };
+    }
+    state.hasSnapshot = true;
+    state.generation += 1;
+  };
+  if (boundsPromise) {
+    Promise.all([elevationPromise, boundsPromise]).then(([elev, bounds]) => onComplete(elev, bounds)).finally(() => {
+      state.readbackPending = false;
+    });
+  } else {
+    elevationPromise.then((elev) => onComplete(elev, null)).finally(() => {
+      state.readbackPending = false;
+    });
+  }
 }
+
 function createCpuTerrainCache(maxNodes, initialConfig) {
   let config = initialConfig;
-  let edgeVertexCount = config.innerTileSegments + 3;
-  let verticesPerNode = edgeVertexCount * edgeVertexCount;
-  let totalElements = maxNodes * verticesPerNode;
-  let frontElevation = new Float32Array(totalElements);
-  let backElevation = new Float32Array(totalElements);
-  let frontIndex = createSpatialIndex(maxNodes);
-  let backIndex = createSpatialIndex(maxNodes);
-  let frontTileBounds = new Float32Array(maxNodes * 2);
-  let backTileBounds = new Float32Array(maxNodes * 2);
-  let frontLeafCount = 0;
-  let globalRange = null;
-  let hasSnapshot = false;
-  let readbackPending = false;
-  let generationCount = 0;
-  let lastScheduledStampGen = -1;
-  const readHeight = (leafIndex, ix, iy) => {
-    const base = leafIndex * verticesPerNode;
-    return frontElevation[base + iy * edgeVertexCount + ix] ?? 0;
+  const shape = {
+    edgeVertexCount: config.innerTileSegments + 3,
+    verticesPerNode: 0
   };
-  const sampleGridBilinear = (leafIndex, gx, gy) => {
-    const max = edgeVertexCount - 1;
-    const x = Math.max(0, Math.min(max, gx));
-    const y = Math.max(0, Math.min(max, gy));
-    const x0 = Math.floor(x);
-    const y0 = Math.floor(y);
-    const x1 = Math.min(max, x0 + 1);
-    const y1 = Math.min(max, y0 + 1);
-    const tx = x - x0;
-    const ty = y - y0;
-    const h00 = readHeight(leafIndex, x0, y0);
-    const h10 = readHeight(leafIndex, x1, y0);
-    const h01 = readHeight(leafIndex, x0, y1);
-    const h11 = readHeight(leafIndex, x1, y1);
-    const hx0 = h00 + (h10 - h00) * tx;
-    const hx1 = h01 + (h11 - h01) * tx;
-    return hx0 + (hx1 - hx0) * ty;
+  shape.verticesPerNode = shape.edgeVertexCount * shape.edgeVertexCount;
+  let totalElements = maxNodes * shape.verticesPerNode;
+  const state = createTerrainSnapshotState(
+    maxNodes,
+    totalElements
+  );
+  const dirScratch = [0, 0, 0];
+  const uvScratch = [0, 0];
+  const llScratch = [0, 0, 0];
+  const gridScratch = { gx: 0, gy: 0 };
+  const gradientScratch = { dhdu: 0, dhdv: 0 };
+  const gridCoordsFromLookup = (lookup) => {
+    const fieldU = tileLocalToFieldUVNumber(lookup.localU, config.innerTileSegments);
+    const fieldV = tileLocalToFieldUVNumber(lookup.localV, config.innerTileSegments);
+    gridScratch.gx = fieldU * (shape.edgeVertexCount - 1);
+    gridScratch.gy = fieldV * (shape.edgeVertexCount - 1);
+    return gridScratch;
+  };
+  const rawHeightFromLookup = (lookup) => {
+    const g = gridCoordsFromLookup(lookup);
+    return sampleGridBilinear(state.frontElevation, shape, lookup.leafIndex, g.gx, g.gy);
   };
   const computeNormal = (leafIndex, gx, gy, tileSize) => {
-    const hLeft = sampleGridBilinear(leafIndex, gx - 1, gy);
-    const hRight = sampleGridBilinear(leafIndex, gx + 1, gy);
-    const hUp = sampleGridBilinear(leafIndex, gx, gy - 1);
-    const hDown = sampleGridBilinear(leafIndex, gx, gy + 1);
     const stepWorld = tileSize / config.innerTileSegments;
-    const inv2Step = 0.5 / stepWorld;
-    const dhdx = (hRight - hLeft) * config.elevationScale * inv2Step;
-    const dhdz = (hDown - hUp) * config.elevationScale * inv2Step;
-    return new Vector3(-dhdx, 1, -dhdz).normalize();
+    const { dhdu, dhdv } = elevationGradientAt(
+      state.frontElevation,
+      shape,
+      leafIndex,
+      gx,
+      gy,
+      stepWorld,
+      config.elevationScale,
+      gradientScratch
+    );
+    return new Vector3(-dhdu, 1, -dhdv).normalize();
   };
-  const lookupTile = (worldX, worldZ) => {
-    const halfRoot = config.rootSize * 0.5;
-    for (let level = config.maxLevel; level >= 0; level -= 1) {
-      const scale = 2 ** level;
-      const tileSize = config.rootSize / scale;
-      const tileX = Math.floor((worldX - config.originX + halfRoot) / tileSize);
-      const tileY = Math.floor((worldZ - config.originZ + halfRoot) / tileSize);
-      const leafIndex = lookupSpatialIndexRaw(
-        frontIndex,
-        0,
-        level,
-        tileX,
-        tileY
-      );
-      if (leafIndex !== U32_EMPTY) {
-        const tileMinX = config.originX + tileX * tileSize - halfRoot;
-        const tileMinZ = config.originZ + tileY * tileSize - halfRoot;
-        return {
-          found: true,
-          leafIndex,
-          level,
-          tileX,
-          tileY,
-          tileSize,
-          localU: (worldX - tileMinX) / tileSize,
-          localV: (worldZ - tileMinZ) / tileSize
-        };
-      }
-    }
-    return {
-      found: false,
-      leafIndex: -1,
-      level: -1,
-      tileX: -1,
-      tileY: -1,
-      tileSize: 0,
-      localU: 0,
-      localV: 0
-    };
+  const computeSphereNormal = (leafIndex, gx, gy, tileSize, face, dirX, dirY, dirZ) => {
+    const stepWorld = tileSize / config.innerTileSegments;
+    const { dhdu, dhdv } = elevationGradientAt(
+      state.frontElevation,
+      shape,
+      leafIndex,
+      gx,
+      gy,
+      stepWorld,
+      config.elevationScale,
+      gradientScratch
+    );
+    const f = CUBE_FACES[face];
+    const dDotR = dirX * f.right[0] + dirY * f.right[1] + dirZ * f.right[2];
+    let tux = f.right[0] - dirX * dDotR;
+    let tuy = f.right[1] - dirY * dDotR;
+    let tuz = f.right[2] - dirZ * dDotR;
+    const tuLen = Math.hypot(tux, tuy, tuz) || 1;
+    tux /= tuLen;
+    tuy /= tuLen;
+    tuz /= tuLen;
+    const dDotU = dirX * f.up[0] + dirY * f.up[1] + dirZ * f.up[2];
+    let tvx = f.up[0] - dirX * dDotU;
+    let tvy = f.up[1] - dirY * dDotU;
+    let tvz = f.up[2] - dirZ * dDotU;
+    const tvLen = Math.hypot(tvx, tvy, tvz) || 1;
+    tvx /= tvLen;
+    tvy /= tvLen;
+    tvz /= tvLen;
+    const nx = -dhdu;
+    const ny = 1;
+    const nz = -dhdv;
+    return new Vector3(
+      tux * nx + dirX * ny + tvx * nz,
+      tuy * nx + dirY * ny + tvy * nz,
+      tuz * nx + dirZ * ny + tvz * nz
+    ).normalize();
   };
   const sampleFromLookup = (lookup) => {
-    const fieldU = tileLocalToFieldUV(lookup.localU, config.innerTileSegments);
-    const fieldV = tileLocalToFieldUV(lookup.localV, config.innerTileSegments);
-    const gx = fieldU * (edgeVertexCount - 1);
-    const gy = fieldV * (edgeVertexCount - 1);
-    const height = sampleGridBilinear(lookup.leafIndex, gx, gy);
+    const height = rawHeightFromLookup(lookup);
     const scaledHeight = config.originY + height * config.elevationScale;
-    const normal = computeNormal(lookup.leafIndex, gx, gy, lookup.tileSize);
+    const normal = computeNormal(
+      lookup.leafIndex,
+      gridScratch.gx,
+      gridScratch.gy,
+      lookup.tileSize
+    );
     return { elevation: scaledHeight, normal, valid: true };
   };
-  const sampleElevationFromLookup = (lookup) => {
-    const fieldU = tileLocalToFieldUV(lookup.localU, config.innerTileSegments);
-    const fieldV = tileLocalToFieldUV(lookup.localV, config.innerTileSegments);
-    const gx = fieldU * (edgeVertexCount - 1);
-    const gy = fieldV * (edgeVertexCount - 1);
-    const height = sampleGridBilinear(lookup.leafIndex, gx, gy);
-    const scaledHeight = config.originY + height * config.elevationScale;
-    return { elevation: scaledHeight, valid: true };
-  };
   const sampleTerrain = (worldX, worldZ) => {
-    if (!hasSnapshot) {
+    if (!state.hasSnapshot) {
       return { elevation: 0, normal: new Vector3(0, 1, 0), valid: false };
     }
-    const lookup = lookupTile(worldX, worldZ);
+    const lookup = lookupTile(state.frontIndex, config, worldX, worldZ);
     if (!lookup.found) {
       return { elevation: 0, normal: new Vector3(0, 1, 0), valid: false };
     }
     return sampleFromLookup(lookup);
   };
   const getElevation = (worldX, worldZ) => {
-    if (!hasSnapshot) {
+    if (!state.hasSnapshot) {
       return { elevation: 0, valid: false };
     }
-    const lookup = lookupTile(worldX, worldZ);
+    const lookup = lookupTile(state.frontIndex, config, worldX, worldZ);
     if (!lookup.found) {
       return { elevation: 0, valid: false };
     }
-    return sampleElevationFromLookup(lookup);
+    const height = rawHeightFromLookup(lookup);
+    return {
+      elevation: config.originY + height * config.elevationScale,
+      valid: true
+    };
+  };
+  const invalidSurfaceSample = (dx, dy, dz) => ({
+    position: new Vector3(),
+    normal: new Vector3(0, 1, 0),
+    direction: new Vector3(dx, dy, dz),
+    elevation: 0,
+    valid: false
+  });
+  const lookupDirection = (dx, dy, dz) => lookupTileForDirection(state.frontIndex, config, dx, dy, dz, dirScratch, uvScratch);
+  const sampleSurfaceByDirection = (dx, dy, dz) => {
+    if (!state.hasSnapshot || config.projection !== "cubeSphere") {
+      return invalidSurfaceSample(dx, dy, dz);
+    }
+    const len = Math.hypot(dx, dy, dz);
+    if (len === 0) return invalidSurfaceSample(0, 0, 0);
+    const nx = dx / len;
+    const ny = dy / len;
+    const nz = dz / len;
+    const lookup = lookupDirection(nx, ny, nz);
+    if (!lookup.found) return invalidSurfaceSample(nx, ny, nz);
+    const height = rawHeightFromLookup(lookup);
+    const elevation = height * config.elevationScale;
+    const r = config.radius + elevation;
+    const position = new Vector3(
+      config.originX + nx * r,
+      config.originY + ny * r,
+      config.originZ + nz * r
+    );
+    const normal = computeSphereNormal(
+      lookup.leafIndex,
+      gridScratch.gx,
+      gridScratch.gy,
+      lookup.tileSize,
+      lookup.space,
+      nx,
+      ny,
+      nz
+    );
+    return {
+      position,
+      normal,
+      direction: new Vector3(nx, ny, nz),
+      elevation,
+      valid: true
+    };
+  };
+  const tileFromLookup = (lookup) => {
+    if (!lookup.found) return null;
+    return {
+      space: lookup.space,
+      level: lookup.level,
+      x: lookup.tileX,
+      y: lookup.tileY,
+      index: lookup.leafIndex
+    };
+  };
+  const tileBoundsFromLookup = (lookup, elevationBase) => {
+    if (!lookup.found || lookup.leafIndex >= state.frontLeafCount) return null;
+    const rawMin = state.frontTileBounds[lookup.leafIndex * 2];
+    const rawMax = state.frontTileBounds[lookup.leafIndex * 2 + 1];
+    const a = elevationBase + rawMin * config.elevationScale;
+    const b = elevationBase + rawMax * config.elevationScale;
+    return {
+      space: lookup.space,
+      level: lookup.level,
+      x: lookup.tileX,
+      y: lookup.tileY,
+      index: lookup.leafIndex,
+      minElevation: Math.min(a, b),
+      maxElevation: Math.max(a, b)
+    };
   };
   const api = {
     get generation() {
-      return generationCount;
+      return state.generation;
     },
     get ready() {
-      return hasSnapshot;
+      return state.hasSnapshot;
     },
     updateConfig(nextConfig) {
       config = nextConfig;
-      edgeVertexCount = config.innerTileSegments + 3;
-      verticesPerNode = edgeVertexCount * edgeVertexCount;
-      totalElements = maxNodes * verticesPerNode;
+      shape.edgeVertexCount = config.innerTileSegments + 3;
+      shape.verticesPerNode = shape.edgeVertexCount * shape.edgeVertexCount;
+      totalElements = maxNodes * shape.verticesPerNode;
     },
     triggerReadback(renderer, attribute, spatialIndex, boundsAttribute, activeLeafCount) {
-      if (readbackPending) return;
-      const withReadback = renderer;
-      if (!withReadback.getArrayBufferAsync) return;
-      if (spatialIndex.stampGen === lastScheduledStampGen) return;
-      cloneSpatialIndex(backIndex, spatialIndex);
-      lastScheduledStampGen = spatialIndex.stampGen;
-      const capturedLeafCount = activeLeafCount ?? 0;
-      const capturedScale = config.elevationScale;
-      const capturedOriginY = config.originY;
-      readbackPending = true;
-      const elevationPromise = withReadback.getArrayBufferAsync(attribute);
-      const boundsPromise = boundsAttribute ? withReadback.getArrayBufferAsync(boundsAttribute) : null;
-      const onComplete = (elevResult, boundsResult) => {
-        const data = new Float32Array(elevResult);
-        backElevation.fill(0);
-        backElevation.set(data.subarray(0, totalElements));
-        let boundsValid = capturedLeafCount === 0;
-        if (boundsResult) {
-          const rawBounds = new Float32Array(boundsResult);
-          backTileBounds.fill(0);
-          backTileBounds.set(rawBounds.subarray(0, capturedLeafCount * 2));
-          for (let i = 0; i < capturedLeafCount; i += 1) {
-            if ((rawBounds[i * 2 + 1] ?? 0) !== 0) {
-              boundsValid = true;
-              break;
-            }
-          }
-        }
-        const oldFrontElevation = frontElevation;
-        const oldFrontIndex = frontIndex;
-        frontElevation = backElevation;
-        frontIndex = backIndex;
-        frontLeafCount = capturedLeafCount;
-        backElevation = oldFrontElevation;
-        backIndex = oldFrontIndex;
-        if (boundsResult && boundsValid) {
-          const oldFrontBounds = frontTileBounds;
-          frontTileBounds = backTileBounds;
-          backTileBounds = oldFrontBounds;
-        }
-        if (boundsResult && boundsValid && capturedLeafCount > 0) {
-          let gMin = Infinity;
-          let gMax = -Infinity;
-          for (let i = 0; i < capturedLeafCount; i++) {
-            const rawMin = frontTileBounds[i * 2];
-            const rawMax = frontTileBounds[i * 2 + 1];
-            const a = capturedOriginY + rawMin * capturedScale;
-            const b = capturedOriginY + rawMax * capturedScale;
-            gMin = Math.min(gMin, a, b);
-            gMax = Math.max(gMax, a, b);
-          }
-          globalRange = { min: gMin, max: gMax };
-        }
-        hasSnapshot = true;
-        generationCount += 1;
-      };
-      if (boundsPromise) {
-        Promise.all([elevationPromise, boundsPromise]).then(([elev, bounds]) => onComplete(elev, bounds)).finally(() => {
-          readbackPending = false;
-        });
-      } else {
-        elevationPromise.then((elev) => onComplete(elev, null)).finally(() => {
-          readbackPending = false;
-        });
-      }
+      triggerSnapshotReadback(state, renderer, attribute, spatialIndex, boundsAttribute, {
+        activeLeafCount: activeLeafCount ?? 0,
+        totalElements,
+        elevationScale: config.elevationScale,
+        originY: config.originY
+      });
     },
     getElevation(worldX, worldZ) {
       const sample = getElevation(worldX, worldZ);
@@ -1623,43 +2037,26 @@ function createCpuTerrainCache(maxNodes, initialConfig) {
       return sampleTerrain(worldX, worldZ).normal;
     },
     getTile(worldX, worldZ) {
-      if (!hasSnapshot) return null;
-      const lookup = lookupTile(worldX, worldZ);
-      if (!lookup.found) return null;
-      return {
-        level: lookup.level,
-        x: lookup.tileX,
-        y: lookup.tileY,
-        index: lookup.leafIndex
-      };
+      if (!state.hasSnapshot) return null;
+      return tileFromLookup(lookupTile(state.frontIndex, config, worldX, worldZ));
     },
     getTileBounds(worldX, worldZ) {
-      if (!hasSnapshot) return null;
-      const lookup = lookupTile(worldX, worldZ);
-      if (!lookup.found || lookup.leafIndex >= frontLeafCount) return null;
-      const rawMin = frontTileBounds[lookup.leafIndex * 2];
-      const rawMax = frontTileBounds[lookup.leafIndex * 2 + 1];
-      const a = config.originY + rawMin * config.elevationScale;
-      const b = config.originY + rawMax * config.elevationScale;
-      return {
-        level: lookup.level,
-        x: lookup.tileX,
-        y: lookup.tileY,
-        index: lookup.leafIndex,
-        minElevation: Math.min(a, b),
-        maxElevation: Math.max(a, b)
-      };
+      if (!state.hasSnapshot) return null;
+      return tileBoundsFromLookup(
+        lookupTile(state.frontIndex, config, worldX, worldZ),
+        config.originY
+      );
     },
     getGlobalElevationRange() {
-      return globalRange;
+      return state.globalRange;
     },
     sampleTerrainBatch(positions) {
       const count = Math.floor(positions.length / 2);
       const elevations = new Float32Array(count);
       const normals = new Float32Array(count * 3);
       const valid = new Uint8Array(count);
-      if (!hasSnapshot) {
-        return { elevations, normals, valid, generation: generationCount };
+      if (!state.hasSnapshot) {
+        return { elevations, normals, valid, generation: state.generation };
       }
       let lastTile;
       for (let i = 0; i < count; i += 1) {
@@ -1670,6 +2067,7 @@ function createCpuTerrainCache(maxNodes, initialConfig) {
           lookup = {
             found: true,
             leafIndex: lastTile.leafIndex,
+            space: 0,
             level: lastTile.level,
             tileX: lastTile.tileX,
             tileY: lastTile.tileY,
@@ -1678,7 +2076,7 @@ function createCpuTerrainCache(maxNodes, initialConfig) {
             localV: (worldZ - lastTile.tileMinZ) / lastTile.tileSize
           };
         } else {
-          lookup = lookupTile(worldX, worldZ);
+          lookup = lookupTile(state.frontIndex, config, worldX, worldZ);
           if (lookup.found) {
             lastTile = {
               leafIndex: lookup.leafIndex,
@@ -1704,9 +2102,133 @@ function createCpuTerrainCache(maxNodes, initialConfig) {
         normals[i * 3 + 2] = sample.normal.z;
         valid[i] = 1;
       }
-      return { elevations, normals, valid, generation: generationCount };
+      return { elevations, normals, valid, generation: state.generation };
+    },
+    sampleTerrain,
+    // --- Cube-sphere queries ---
+    sampleTerrainByDirection(direction) {
+      return sampleSurfaceByDirection(direction.x, direction.y, direction.z);
+    },
+    sampleTerrainByPosition(position) {
+      return sampleSurfaceByDirection(
+        position.x - config.originX,
+        position.y - config.originY,
+        position.z - config.originZ
+      );
+    },
+    sampleTerrainByLatLong(latitudeDeg, longitudeDeg) {
+      latLongToDirection(latitudeDeg, longitudeDeg, llScratch);
+      return sampleSurfaceByDirection(llScratch[0], llScratch[1], llScratch[2]);
     },
-    sampleTerrain
+    getElevationByDirection(direction) {
+      const sample = sampleSurfaceByDirection(direction.x, direction.y, direction.z);
+      return sample.valid ? sample.elevation : null;
+    },
+    getElevationByPosition(position) {
+      const sample = sampleSurfaceByDirection(
+        position.x - config.originX,
+        position.y - config.originY,
+        position.z - config.originZ
+      );
+      return sample.valid ? sample.elevation : null;
+    },
+    getElevationByLatLong(latitudeDeg, longitudeDeg) {
+      latLongToDirection(latitudeDeg, longitudeDeg, llScratch);
+      const sample = sampleSurfaceByDirection(llScratch[0], llScratch[1], llScratch[2]);
+      return sample.valid ? sample.elevation : null;
+    },
+    getNormalByDirection(direction) {
+      const sample = sampleSurfaceByDirection(direction.x, direction.y, direction.z);
+      return sample.valid ? sample.normal : null;
+    },
+    getNormalByPosition(position) {
+      const sample = sampleSurfaceByDirection(
+        position.x - config.originX,
+        position.y - config.originY,
+        position.z - config.originZ
+      );
+      return sample.valid ? sample.normal : null;
+    },
+    getNormalByLatLong(latitudeDeg, longitudeDeg) {
+      latLongToDirection(latitudeDeg, longitudeDeg, llScratch);
+      const sample = sampleSurfaceByDirection(llScratch[0], llScratch[1], llScratch[2]);
+      return sample.valid ? sample.normal : null;
+    },
+    getTileByDirection(direction) {
+      if (!state.hasSnapshot) return null;
+      return tileFromLookup(lookupDirection(direction.x, direction.y, direction.z));
+    },
+    getTileByPosition(position) {
+      if (!state.hasSnapshot) return null;
+      return tileFromLookup(
+        lookupDirection(
+          position.x - config.originX,
+          position.y - config.originY,
+          position.z - config.originZ
+        )
+      );
+    },
+    getTileByLatLong(latitudeDeg, longitudeDeg) {
+      if (!state.hasSnapshot) return null;
+      latLongToDirection(latitudeDeg, longitudeDeg, llScratch);
+      return tileFromLookup(lookupDirection(llScratch[0], llScratch[1], llScratch[2]));
+    },
+    getTileBoundsByDirection(direction) {
+      if (!state.hasSnapshot) return null;
+      return tileBoundsFromLookup(
+        lookupDirection(direction.x, direction.y, direction.z),
+        0
+      );
+    },
+    getTileBoundsByPosition(position) {
+      if (!state.hasSnapshot) return null;
+      return tileBoundsFromLookup(
+        lookupDirection(
+          position.x - config.originX,
+          position.y - config.originY,
+          position.z - config.originZ
+        ),
+        0
+      );
+    },
+    getTileBoundsByLatLong(latitudeDeg, longitudeDeg) {
+      if (!state.hasSnapshot) return null;
+      latLongToDirection(latitudeDeg, longitudeDeg, llScratch);
+      return tileBoundsFromLookup(
+        lookupDirection(llScratch[0], llScratch[1], llScratch[2]),
+        0
+      );
+    },
+    sampleTerrainBatchByDirection(directions) {
+      const count = Math.floor(directions.length / 3);
+      const positions = new Float32Array(count * 3);
+      const normals = new Float32Array(count * 3);
+      const elevations = new Float32Array(count);
+      const valid = new Uint8Array(count);
+      if (!state.hasSnapshot || config.projection !== "cubeSphere") {
+        return { positions, normals, elevations, valid, generation: state.generation };
+      }
+      for (let i = 0; i < count; i += 1) {
+        const sample = sampleSurfaceByDirection(
+          directions[i * 3] ?? 0,
+          directions[i * 3 + 1] ?? 0,
+          directions[i * 3 + 2] ?? 0
+        );
+        if (!sample.valid) {
+          normals[i * 3 + 1] = 1;
+          continue;
+        }
+        positions[i * 3] = sample.position.x;
+        positions[i * 3 + 1] = sample.position.y;
+        positions[i * 3 + 2] = sample.position.z;
+        normals[i * 3] = sample.normal.x;
+        normals[i * 3 + 1] = sample.normal.y;
+        normals[i * 3 + 2] = sample.normal.z;
+        elevations[i] = sample.elevation;
+        valid[i] = 1;
+      }
+      return { positions, normals, elevations, valid, generation: state.generation };
+    }
   };
   return api;
 }
@@ -1739,6 +2261,61 @@ function createTerrainQuery(cache) {
     }
   };
 }
+function createTerrainSphereQuery(cache) {
+  return {
+    get generation() {
+      return cache.generation;
+    },
+    getElevationByDirection(direction) {
+      return cache.getElevationByDirection(direction);
+    },
+    getElevationByPosition(position) {
+      return cache.getElevationByPosition(position);
+    },
+    getElevationByLatLong(latitudeDeg, longitudeDeg) {
+      return cache.getElevationByLatLong(latitudeDeg, longitudeDeg);
+    },
+    getNormalByDirection(direction) {
+      return cache.getNormalByDirection(direction);
+    },
+    getNormalByPosition(position) {
+      return cache.getNormalByPosition(position);
+    },
+    getNormalByLatLong(latitudeDeg, longitudeDeg) {
+      return cache.getNormalByLatLong(latitudeDeg, longitudeDeg);
+    },
+    sampleTerrainByDirection(direction) {
+      return cache.sampleTerrainByDirection(direction);
+    },
+    sampleTerrainByPosition(position) {
+      return cache.sampleTerrainByPosition(position);
+    },
+    sampleTerrainByLatLong(latitudeDeg, longitudeDeg) {
+      return cache.sampleTerrainByLatLong(latitudeDeg, longitudeDeg);
+    },
+    getTileByDirection(direction) {
+      return cache.getTileByDirection(direction);
+    },
+    getTileByPosition(position) {
+      return cache.getTileByPosition(position);
+    },
+    getTileByLatLong(latitudeDeg, longitudeDeg) {
+      return cache.getTileByLatLong(latitudeDeg, longitudeDeg);
+    },
+    getTileBoundsByDirection(direction) {
+      return cache.getTileBoundsByDirection(direction);
+    },
+    getTileBoundsByPosition(position) {
+      return cache.getTileBoundsByPosition(position);
+    },
+    getTileBoundsByLatLong(latitudeDeg, longitudeDeg) {
+      return cache.getTileBoundsByLatLong(latitudeDeg, longitudeDeg);
+    },
+    sampleTerrainBatchByDirection(directions) {
+      return cache.sampleTerrainBatchByDirection(directions);
+    }
+  };
+}
 
 const WGSIZE = 64;
 function buildReductionKernel(elevationFieldNode, boundsNode, verticesPerNode) {
@@ -1808,8 +2385,11 @@ const terrainQueryTask = task((get, work) => {
   const rootSizeValue = get(rootSize);
   const originValue = get(origin);
   const elevationScaleValue = get(elevationScale);
+  const radiusValue = get(radius);
+  const topologyValue = get(topologyTask);
+  const projectionValue = topologyValue.projection ?? "flat";
   return work((prev) => {
-    const shapeKey = `${maxNodesValue}:${innerTileSegmentsValue}`;
+    const shapeKey = `${maxNodesValue}:${innerTileSegmentsValue}:${projectionValue}`;
     const configValues = {
       rootSize: rootSizeValue,
       originX: originValue.x,
@@ -1817,16 +2397,20 @@ const terrainQueryTask = task((get, work) => {
       originZ: originValue.z,
       innerTileSegments: innerTileSegmentsValue,
       elevationScale: elevationScaleValue,
-      maxLevel: maxLevelValue
+      maxLevel: maxLevelValue,
+      projection: projectionValue,
+      radius: topologyValue.radius ?? radiusValue
     };
     let cache = prev?.cache;
     let query = prev?.query;
+    let sphereQuery = prev?.sphereQuery ?? null;
     if (!cache || !query || prev?.shapeKey !== shapeKey) {
       cache = createCpuTerrainCache(maxNodesValue, configValues);
       query = createTerrainQuery(cache);
+      sphereQuery = projectionValue === "cubeSphere" ? createTerrainSphereQuery(cache) : null;
     }
     cache.updateConfig(configValues);
-    return { cache, query, shapeKey };
+    return { cache, query, sphereQuery, shapeKey };
   });
 }).displayName("terrainQueryTask");
 const terrainReadbackTask = task(
@@ -1849,38 +2433,44 @@ const terrainReadbackTask = task(
   }
 ).displayName("terrainReadbackTask").lane("gpu");
 
-const surfaceTask = task((get, work) => {
-  const customSurface = get(surface);
+const topologyTask = task((get, work) => {
+  const customTopology = get(topology);
   const rootSizeVal = get(rootSize);
   const originVal = get(origin);
   return work(() => {
-    if (customSurface) return customSurface;
-    return createFlatSurface({ rootSize: rootSizeVal, origin: originVal });
+    if (customTopology) return customTopology;
+    return createFlatTopology({ rootSize: rootSizeVal, origin: originVal });
   });
-}).displayName("surfaceTask");
+}).displayName("topologyTask");
 const quadtreeConfigTask = task((get, work) => {
-  const surfaceVal = get(surfaceTask);
+  const topologyVal = get(topologyTask);
   const maxNodesVal = get(maxNodes);
   const maxLevelVal = get(maxLevel);
   return work(() => {
-    const state = createState({ maxNodes: maxNodesVal, maxLevel: maxLevelVal }, surfaceVal);
+    const state = createState({ maxNodes: maxNodesVal, maxLevel: maxLevelVal }, topologyVal);
     return {
       state,
-      surface: surfaceVal
+      topology: topologyVal
     };
   });
 }).displayName("quadtreeConfigTask");
 const quadtreeUpdateTask = task((get, work) => {
   const quadtreeConfig = get(quadtreeConfigTask);
   const quadtreeUpdateConfig = get(quadtreeUpdate);
-  const { query: terrainQuery } = get(terrainQueryTask);
+  const { query: terrainQuery, sphereQuery } = get(terrainQueryTask);
   let outLeaves = void 0;
+  const cameraPosition = new Vector3();
   return work(() => {
     const cam = quadtreeUpdateConfig.cameraOrigin;
-    quadtreeUpdateConfig.elevationAtCameraXZ = terrainQuery.getElevation(cam.x, cam.z) ?? 0;
+    if (sphereQuery) {
+      cameraPosition.set(cam.x, cam.y, cam.z);
+      quadtreeUpdateConfig.elevationAtCameraXZ = sphereQuery.getElevationByPosition(cameraPosition) ?? 0;
+    } else {
+      quadtreeUpdateConfig.elevationAtCameraXZ = terrainQuery.getElevation(cam.x, cam.z) ?? 0;
+    }
     outLeaves = update(
       quadtreeConfig.state,
-      quadtreeConfig.surface,
+      quadtreeConfig.topology,
       quadtreeUpdateConfig,
       outLeaves
     );
@@ -1902,7 +2492,7 @@ const leafGpuBufferTask = task((get, work) => {
       leafStorage.data[offset] = leafSet.level[i] ?? 0;
       leafStorage.data[offset + 1] = leafSet.x[i] ?? 0;
       leafStorage.data[offset + 2] = leafSet.y[i] ?? 0;
-      leafStorage.data[offset + 3] = 1;
+      leafStorage.data[offset + 3] = leafSet.space[i] ?? 0;
     }
     leafStorage.attribute.needsUpdate = true;
     leafStorage.node.needsUpdate = true;
@@ -1944,12 +2534,14 @@ function createTerrainUniforms(params) {
   );
   const uSkirtScale = uniform(float(params.skirtScale)).setName(`uSkirtScale${suffix}`);
   const uElevationScale = uniform(float(params.elevationScale)).setName(`uElevationScale${suffix}`);
+  const uRadius = uniform(float(params.radius)).setName(`uRadius${suffix}`);
   return {
     uRootOrigin,
     uRootSize,
     uInnerTileSegments,
     uSkirtScale,
-    uElevationScale
+    uElevationScale,
+    uRadius
   };
 }
 
@@ -1963,6 +2555,7 @@ const createUniformsTask = task((get, work) => {
     innerTileSegments: get(innerTileSegments),
     skirtScale: get(skirtScale),
     elevationScale: get(elevationScale),
+    radius: get(radius),
     instanceId: get(instanceIdTask)
   };
   return work(() => createTerrainUniforms(uniformParams));
@@ -1974,6 +2567,7 @@ const updateUniformsTask = task((get, work) => {
   const innerTileSegmentsVal = get(innerTileSegments);
   const skirtScaleVal = get(skirtScale);
   const elevationScaleVal = get(elevationScale);
+  const radiusVal = get(radius);
   return work(() => {
     terrainUniformsContext.uRootSize.value = rootSizeVal;
     terrainUniformsContext.uRootOrigin.value = scratchVector3.set(
@@ -1984,6 +2578,7 @@ const updateUniformsTask = task((get, work) => {
     terrainUniformsContext.uInnerTileSegments.value = innerTileSegmentsVal;
     terrainUniformsContext.uSkirtScale.value = skirtScaleVal;
     terrainUniformsContext.uElevationScale.value = elevationScaleVal;
+    terrainUniformsContext.uRadius.value = radiusVal;
     return terrainUniformsContext;
   });
 }).displayName("updateUniformsTask");
@@ -2006,8 +2601,9 @@ const createElevationFieldContextTask = task((get, work) => {
 const tileNodesTask = task((get, work) => {
   const leafStorage = get(leafStorageTask);
   const uniforms = get(updateUniformsTask);
+  const topology = get(topologyTask);
   return work(() => {
-    return createTileCompute(leafStorage, uniforms);
+    return createTileCompute(leafStorage, uniforms, topology.projection ?? "flat");
   });
 }).displayName("tileNodesTask");
 const elevationFieldStageTask = task((get, work) => {
@@ -2104,33 +2700,14 @@ const terrainFieldStageTask = task((get, work) => {
   });
 }).displayName("terrainFieldStageTask");
 
-const compileComputeTask = task((get, work) => {
-  const pipeline = get(terrainFieldStageTask);
-  const edgeVertexCount = get(innerTileSegments) + 3;
-  return work(
-    () => compileComputePipeline(pipeline, edgeVertexCount, {
-      preferSingleKernelWhenPossible: false
-    })
-  );
-}).displayName("compileComputeTask");
-const executeComputeTask = task(
-  (get, work, { resources }) => {
-    const { execute } = get(compileComputeTask);
-    const leafState = get(leafGpuBufferTask);
-    return work(
-      () => resources?.renderer ? execute(resources.renderer, leafState.count) : () => {
-      }
-    );
-  }
-).displayName("executeComputeTask").lane("gpu");
+const { compile: compileComputeTask, execute: executeComputeTask } = createComputePipelineTasks(terrainFieldStageTask);
 function createComputePipelineTasks(leafStageTask) {
   const compile = task((get, work) => {
     const pipeline = get(leafStageTask);
     const edgeVertexCount = get(innerTileSegments) + 3;
     return work(
       () => compileComputePipeline(pipeline, edgeVertexCount, {
-        preferSingleKernelWhenPossible: false
-      })
+        })
     );
   }).displayName("compileComputeTask");
   const execute = task(
@@ -2271,6 +2848,38 @@ const createTileIndexFromWorldPosition = (spatialIndex, uniforms, maxLevel) => {
     return vec3(tileIndex.toFloat(), tileU, tileV);
   });
 };
+const createTileIndexFromDirection = (spatialIndex, maxLevel) => {
+  const lookup = createGpuSpatialLookup(spatialIndex);
+  const levelCount = Math.max(1, maxLevel + 1);
+  return Fn(([direction]) => {
+    const dir = vec3(direction).normalize().toVar();
+    const face = cubeFaceFromDirection(dir).toVar();
+    const basis = cubeFaceBasis(face);
+    const faceUV = cubeFaceUVFromDirection(basis, dir).toVar();
+    const u = faceUV.x.toVar();
+    const v = faceUV.y.toVar();
+    const tileIndex = int(-1).toVar();
+    const tileU = float(0).toVar();
+    const tileV = float(0).toVar();
+    const i = int(0).toVar();
+    Loop(levelCount, () => {
+      const level = int(maxLevel).sub(i).toVar();
+      const n = pow(float(2), level.toFloat()).toVar();
+      const nInt = int(n).toVar();
+      const tileX = u.mul(n).floor().toInt().max(int(0)).min(nInt.sub(int(1))).toVar();
+      const tileY = v.mul(n).floor().toInt().max(int(0)).min(nInt.sub(int(1))).toVar();
+      const maybeIndex = lookup(face, level, tileX, tileY).toVar();
+      If(maybeIndex.greaterThanEqual(int(0)), () => {
+        tileIndex.assign(maybeIndex);
+        tileU.assign(u.mul(n).sub(tileX.toFloat()));
+        tileV.assign(v.mul(n).sub(tileY.toFloat()));
+        Break();
+      });
+      i.addAssign(1);
+    });
+    return vec3(tileIndex.toFloat(), tileU, tileV);
+  });
+};
 
 const gpuSpatialIndexStorageTask = task((get, work) => {
   const maxNodesValue = get(maxNodes);
@@ -2286,43 +2895,44 @@ const gpuSpatialIndexUploadTask = task((get, work) => {
   });
 }).displayName("gpuSpatialIndexUploadTask");
 
+function packedSampleFromTileResult(params, tileResult) {
+  const tileIndex = int(tileResult.x).toVar();
+  const safeTileIndex = tileIndex.max(int(0)).toVar();
+  const fieldU = tileLocalToFieldUV(
+    tileResult.y,
+    params.uniforms.uInnerTileSegments
+  ).toVar();
+  const fieldV = tileLocalToFieldUV(
+    tileResult.z,
+    params.uniforms.uInnerTileSegments
+  ).toVar();
+  const found = tileIndex.greaterThanEqual(int(0)).toVar();
+  const sampled = sampleTerrainField(
+    params.terrainFieldStorage,
+    fieldU,
+    fieldV,
+    safeTileIndex
+  ).toVar();
+  const normal = unpackTangentNormal(sampled.g, sampled.b);
+  const valid = found.select(float(1), float(0)).toVar();
+  return vec4(sampled.r, normal.x, normal.y, normal.z).mul(valid);
+}
 function createTerrainSampleNode(params) {
   const tileLookup = createTileIndexFromWorldPosition(
     params.spatialIndex,
     params.uniforms,
-    maxLevel.get()
+    params.maxLevel
   );
   return Fn(([worldX, worldZ]) => {
     const tileResult = tileLookup(worldX, worldZ).toVar();
-    const tileIndex = int(tileResult.x).toVar();
-    const safeTileIndex = tileIndex.max(int(0)).toVar();
-    const u = tileResult.y.toVar();
-    const v = tileResult.z.toVar();
-    const fieldU = tileLocalToFieldUV$1(
-      u,
-      params.uniforms.uInnerTileSegments
-    ).toVar();
-    const fieldV = tileLocalToFieldUV$1(
-      v,
-      params.uniforms.uInnerTileSegments
-    ).toVar();
-    const found = tileIndex.greaterThanEqual(int(0)).toVar();
-    const sampled = sampleTerrainField(
-      params.terrainFieldStorage,
-      fieldU,
-      fieldV,
-      safeTileIndex
-    ).toVar();
-    const nx = sampled.g.toVar();
-    const nz = sampled.b.toVar();
-    const ny = float(1).sub(nx.mul(nx)).sub(nz.mul(nz)).max(0).sqrt();
-    const valid = found.select(float(1), float(0)).toVar();
-    return vec4(
-      sampled.r.mul(valid),
-      nx.mul(valid),
-      ny.mul(valid),
-      nz.mul(valid)
-    );
+    return packedSampleFromTileResult(params, tileResult);
+  });
+}
+function createTerrainSampleNodeByDirection(params) {
+  const tileLookup = createTileIndexFromDirection(params.spatialIndex, params.maxLevel);
+  return Fn(([direction]) => {
+    const tileResult = tileLookup(direction).toVar();
+    return packedSampleFromTileResult(params, tileResult);
   });
 }
 function createTerrainSampler(params) {
@@ -2354,16 +2964,14 @@ function createTerrainSampler(params) {
   const sampleElevation = Fn(
     ([worldX, worldZ]) => terrainSampleAt(worldX, worldZ).x
   );
-  const sampleNormal = Fn(
-    ([worldX, worldZ]) => vec3(
-      terrainSampleAt(worldX, worldZ).y,
-      terrainSampleAt(worldX, worldZ).z,
-      terrainSampleAt(worldX, worldZ).w
-    )
-  );
-  const sampleValidity = Fn(
-    ([worldX, worldZ]) => terrainSampleAt(worldX, worldZ).y.abs().add(terrainSampleAt(worldX, worldZ).z.abs()).add(terrainSampleAt(worldX, worldZ).w.abs()).greaterThan(float(0)).select(float(1), float(0))
-  );
+  const sampleNormal = Fn(([worldX, worldZ]) => {
+    const sample = terrainSampleAt(worldX, worldZ).toVar();
+    return vec3(sample.y, sample.z, sample.w);
+  });
+  const sampleValidity = Fn(([worldX, worldZ]) => {
+    const sample = terrainSampleAt(worldX, worldZ).toVar();
+    return sample.y.abs().add(sample.z.abs()).add(sample.w.abs()).greaterThan(float(0)).select(float(1), float(0));
+  });
   const evaluateElevation = Fn(
     ([worldX, worldZ]) => evaluateElevationAt(worldX, worldZ)
   );
@@ -2390,7 +2998,7 @@ function createTerrainSampler(params) {
     }
   );
   const evaluateNormal = (worldX, worldZ, epsilon) => evaluateNormalNode(worldX, worldZ, epsilon ?? float(0.1));
-  return {
+  const sampler = {
     sampleElevation,
     sampleNormal,
     sampleTerrain,
@@ -2398,6 +3006,26 @@ function createTerrainSampler(params) {
     evaluateElevation,
     evaluateNormal
   };
+  if (params.projection === "cubeSphere") {
+    const terrainSampleByDir = createTerrainSampleNodeByDirection(params);
+    sampler.sampleTerrainByDirection = Fn(
+      ([direction]) => terrainSampleByDir(direction)
+    );
+    sampler.sampleElevationByDirection = Fn(
+      ([direction]) => terrainSampleByDir(direction).x
+    );
+    sampler.sampleValidityByDirection = Fn(([direction]) => {
+      const sample = terrainSampleByDir(direction).toVar();
+      return sample.y.abs().add(sample.z.abs()).add(sample.w.abs()).greaterThan(float(0)).select(float(1), float(0));
+    });
+    sampler.sampleNormalByDirection = Fn(([direction]) => {
+      const dir = vec3(direction).normalize().toVar();
+      const packed = terrainSampleByDir(direction).toVar();
+      const basis = cubeFaceBasis(cubeFaceFromDirection(dir));
+      return sphereTangentFrameNormal(dir, basis, vec3(packed.y, packed.z, packed.w));
+    });
+  }
+  return sampler;
 }
 
 const createTerrainSamplerTask = task((get, work) => {
@@ -2405,12 +3033,16 @@ const createTerrainSamplerTask = task((get, work) => {
   const spatialIndex = get(gpuSpatialIndexStorageTask);
   const uniforms = get(updateUniformsTask);
   const elevationCallback = get(elevationFn);
+  const maxLevelValue = get(maxLevel);
+  const projection = get(topologyTask).projection ?? "flat";
   return work(
     () => createTerrainSampler({
       terrainFieldStorage,
       spatialIndex,
       uniforms,
-      elevationCallback
+      elevationCallback,
+      maxLevel: maxLevelValue,
+      projection
     })
   );
 }).displayName("createTerrainSamplerTask");
@@ -2437,18 +3069,14 @@ const isSkirtUV = Fn(([segments]) => {
 
 function createTileBaseWorldPosition(leafStorage, terrainUniforms) {
   return Fn(() => {
-    const nodeIndex = int(instanceIndex);
-    const nodeOffset = nodeIndex.mul(int(4));
-    const nodeLevel = leafStorage.node.element(nodeOffset).toInt();
-    const nodeX = leafStorage.node.element(nodeOffset.add(int(1))).toFloat();
-    const nodeY = leafStorage.node.element(nodeOffset.add(int(2))).toFloat();
+    const tile = decodeLeafTile(leafStorage, int(instanceIndex));
     const rootSize = terrainUniforms.uRootSize.toVar();
     const rootOrigin = terrainUniforms.uRootOrigin.toVar();
     const half = float(0.5);
-    const size = rootSize.div(pow(float(2), nodeLevel.toFloat()));
+    const size = rootSize.div(pow(float(2), tile.level.toFloat()));
     const halfRoot = rootSize.mul(half);
-    const centerX = rootOrigin.x.add(nodeX.add(half).mul(size)).sub(halfRoot);
-    const centerZ = rootOrigin.z.add(nodeY.add(half).mul(size)).sub(halfRoot);
+    const centerX = rootOrigin.x.add(tile.x.add(half).mul(size)).sub(halfRoot);
+    const centerZ = rootOrigin.z.add(tile.y.add(half).mul(size)).sub(halfRoot);
     const clampedX = positionLocal.x.max(half.negate()).min(half);
     const clampedZ = positionLocal.z.max(half.negate()).min(half);
     const worldX = centerX.add(clampedX.mul(size));
@@ -2459,49 +3087,78 @@ function createTileBaseWorldPosition(leafStorage, terrainUniforms) {
 function createTileElevation(terrainUniforms, terrainFieldStorage) {
   if (!terrainFieldStorage) return float(0);
   const innerSegs = terrainUniforms.uInnerTileSegments;
-  const u = tileLocalToFieldUV$1(positionLocal.x.add(float(0.5)), innerSegs);
-  const v = tileLocalToFieldUV$1(positionLocal.z.add(float(0.5)), innerSegs);
-  return sampleTerrainFieldElevation(
-    terrainFieldStorage,
-    u,
-    v,
-    int(instanceIndex)
-  ).mul(terrainUniforms.uElevationScale);
-}
-function createNormalAssignment(terrainUniforms, terrainFieldStorage) {
+  const u = tileLocalToFieldUV(positionLocal.x.add(float(0.5)), innerSegs);
+  const v = tileLocalToFieldUV(positionLocal.z.add(float(0.5)), innerSegs);
+  return sampleTerrainFieldElevation(terrainFieldStorage, u, v, int(instanceIndex)).mul(
+    terrainUniforms.uElevationScale
+  );
+}
+function createNormalAssignment(leafStorage, terrainUniforms, terrainFieldStorage, projection = "flat") {
   if (!terrainFieldStorage) return;
+  normalLocal.assign(
+    createTileLocalNormal(leafStorage, terrainUniforms, terrainFieldStorage, projection)
+  );
+}
+function loadTangentNormal(terrainUniforms, terrainFieldStorage) {
   const nodeIndex = int(instanceIndex);
   const edgeVertexCount = int(terrainUniforms.uInnerTileSegments.add(3));
   const localVertexIndex = int(vertexIndex);
   const ix = localVertexIndex.mod(edgeVertexCount);
   const iy = localVertexIndex.div(edgeVertexCount);
-  const normalXZ = loadTerrainFieldNormal(
-    terrainFieldStorage,
-    ix,
-    iy,
-    nodeIndex
-  );
-  const nx = normalXZ.x;
-  const nz = normalXZ.y;
-  const nySq = float(1).sub(nx.mul(nx)).sub(nz.mul(nz)).max(float(0));
-  const ny = nySq.sqrt();
-  normalLocal.assign(vec3(nx, ny, nz));
-}
-function createTileWorldPosition(leafStorage, terrainUniforms, terrainFieldStorage) {
-  const baseWorldPosition = createTileBaseWorldPosition(
-    leafStorage,
-    terrainUniforms
-  );
+  const normalXZ = loadTerrainFieldNormal(terrainFieldStorage, ix, iy, nodeIndex);
+  const normal = unpackTangentNormal(normalXZ.x, normalXZ.y);
+  return { ix, iy, normal };
+}
+function createTileLocalNormal(leafStorage, terrainUniforms, terrainFieldStorage, projection = "flat") {
+  if (!terrainFieldStorage) return vec3(0, 1, 0);
+  if (projection === "cubeSphere") {
+    return Fn(() => {
+      const { ix, iy, normal } = loadTangentNormal(terrainUniforms, terrainFieldStorage);
+      const tile = decodeLeafTile(leafStorage, int(instanceIndex));
+      const innerSeg = terrainUniforms.uInnerTileSegments.toVar().toFloat();
+      const localU = ix.toFloat().sub(float(1)).div(innerSeg).max(float(0)).min(float(1));
+      const localV = iy.toFloat().sub(float(1)).div(innerSeg).max(float(0)).min(float(1));
+      const faceUV = faceUVFromTileLocal(tile, localU, localV);
+      const basis = cubeFaceBasis(tile.face);
+      const dir = cubeFaceDirection(basis, faceUV.x, faceUV.y);
+      return sphereTangentFrameNormal(dir, basis, normal);
+    })();
+  }
+  return Fn(() => {
+    const { normal } = loadTangentNormal(terrainUniforms, terrainFieldStorage);
+    return normal;
+  })();
+}
+function createCubeSphereWorldPosition(leafStorage, terrainUniforms, terrainFieldStorage) {
+  return Fn(() => {
+    const tile = decodeLeafTile(leafStorage, int(instanceIndex));
+    const half = float(0.5);
+    const localU = positionLocal.x.max(half.negate()).min(half).add(half);
+    const localV = positionLocal.z.max(half.negate()).min(half).add(half);
+    const faceUV = faceUVFromTileLocal(tile, localU, localV);
+    const basis = cubeFaceBasis(tile.face);
+    const dir = cubeFaceDirection(basis, faceUV.x, faceUV.y);
+    const yElevation = createTileElevation(terrainUniforms, terrainFieldStorage);
+    const baseRadius = terrainUniforms.uRadius.toVar().add(yElevation);
+    const skirtVertex = isSkirtVertex(terrainUniforms.uInnerTileSegments);
+    const r = select(skirtVertex, baseRadius.sub(terrainUniforms.uSkirtScale.toVar()), baseRadius);
+    createNormalAssignment(leafStorage, terrainUniforms, terrainFieldStorage, "cubeSphere");
+    const origin = terrainUniforms.uRootOrigin.toVar();
+    return origin.add(dir.mul(r));
+  })();
+}
+function createTileWorldPosition(leafStorage, terrainUniforms, terrainFieldStorage, projection = "flat") {
+  if (projection === "cubeSphere") {
+    return createCubeSphereWorldPosition(leafStorage, terrainUniforms, terrainFieldStorage);
+  }
+  const baseWorldPosition = createTileBaseWorldPosition(leafStorage, terrainUniforms);
   return Fn(() => {
     const base = baseWorldPosition();
-    const yElevation = createTileElevation(
-      terrainUniforms,
-      terrainFieldStorage
-    );
+    const yElevation = createTileElevation(terrainUniforms, terrainFieldStorage);
     const skirtVertex = isSkirtVertex(terrainUniforms.uInnerTileSegments);
     const skirtY = base.y.add(yElevation).sub(terrainUniforms.uSkirtScale.toVar());
     const worldY = select(skirtVertex, skirtY, base.y.add(yElevation));
-    createNormalAssignment(terrainUniforms, terrainFieldStorage);
+    createNormalAssignment(leafStorage, terrainUniforms, terrainFieldStorage, "flat");
     return vec3(base.x, worldY, base.z);
   })();
 }
@@ -2510,11 +3167,13 @@ const positionNodeTask = task((get, work) => {
   const leafStorage = get(leafStorageTask);
   const terrainUniforms = get(updateUniformsTask);
   const terrainFieldStorage = get(createTerrainFieldTextureTask);
+  const topology = get(topologyTask);
   return work(
     () => createTileWorldPosition(
       leafStorage,
       terrainUniforms,
-      terrainFieldStorage
+      terrainFieldStorage,
+      topology.projection ?? "flat"
     )
   );
 }).displayName("positionNodeTask");
@@ -2555,71 +3214,33 @@ function getTerrainBounds(config) {
     maxZ: config.originZ + halfRoot
   };
 }
-function terrainSignedDistanceFromBounds(query, worldX, worldY, worldZ) {
-  const tileBounds = query.getTileBounds(worldX, worldZ);
-  if (tileBounds) {
-    if (worldY > tileBounds.maxElevation) {
-      return worldY - tileBounds.maxElevation;
-    }
-    if (worldY < tileBounds.minElevation) {
-      return worldY - tileBounds.minElevation;
+function terrainSignedDistance(query, worldX, worldY, worldZ, skipBoundsFastPath) {
+  if (!skipBoundsFastPath) {
+    const tileBounds = query.getTileBounds(worldX, worldZ);
+    if (tileBounds) {
+      if (worldY > tileBounds.maxElevation) {
+        return worldY - tileBounds.maxElevation;
+      }
+      if (worldY < tileBounds.minElevation) {
+        return worldY - tileBounds.minElevation;
+      }
     }
   }
   const elevation = query.getElevation(worldX, worldZ);
   if (!Number.isFinite(elevation)) return void 0;
   return worldY - elevation;
 }
-function terrainSignedDistancePrecise(query, worldX, worldY, worldZ) {
-  const elevation = query.getElevation(worldX, worldZ);
-  if (!Number.isFinite(elevation)) return void 0;
-  return worldY - elevation;
-}
-function cpuRaycast(query, ray, config, options) {
-  const bounds = getTerrainBounds(config);
-  const segment = intersectRayAabb(
-    ray,
-    bounds.minX,
-    config.minY,
-    bounds.minZ,
-    bounds.maxX,
-    config.maxY,
-    bounds.maxZ
-  );
-  if (!segment) return null;
-  const maxDistance = options?.maxDistance ?? Number.POSITIVE_INFINITY;
-  let startT = Math.max(0, segment.tMin);
-  const endT = Math.min(segment.tMax, maxDistance);
-  if (endT < startT) return null;
-  const maxSteps = Math.max(8, options?.maxSteps ?? 128);
-  const refinementSteps = Math.max(1, options?.refinementSteps ?? 8);
-  const point = new Vector3();
+function marchSignedDistance(ray, startT, endT, stepSignedDistanceAt, refineSignedDistanceAt, options, point) {
   let prevT = startT;
   ray.at(prevT, point);
-  let prevSignedDistance = terrainSignedDistanceFromBounds(
-    query,
-    point.x,
-    point.y,
-    point.z
-  );
+  let prevSignedDistance = stepSignedDistanceAt(point.x, point.y, point.z);
   if (prevSignedDistance !== void 0 && prevSignedDistance <= 0) {
-    const sample = query.sampleTerrain(point.x, point.z);
-    if (!sample.valid) return null;
-    point.y = sample.elevation;
-    return {
-      position: point.clone(),
-      normal: sample.normal.clone(),
-      distance: ray.origin.distanceTo(point)
-    };
+    return startT;
   }
-  for (let i = 1; i <= maxSteps; i += 1) {
-    const t = startT + (endT - startT) * i / maxSteps;
+  for (let i = 1; i <= options.maxSteps; i += 1) {
+    const t = startT + (endT - startT) * i / options.maxSteps;
     ray.at(t, point);
-    const signedDistance = terrainSignedDistanceFromBounds(
-      query,
-      point.x,
-      point.y,
-      point.z
-    );
+    const signedDistance = stepSignedDistanceAt(point.x, point.y, point.z);
     if (signedDistance === void 0) {
       prevSignedDistance = void 0;
       prevT = t;
@@ -2628,15 +3249,10 @@ function cpuRaycast(query, ray, config, options) {
     if (prevSignedDistance !== void 0 && prevSignedDistance > 0 && signedDistance <= 0) {
       let lo = prevT;
       let hi = t;
-      for (let r = 0; r < refinementSteps; r += 1) {
+      for (let r = 0; r < options.refinementSteps; r += 1) {
         const mid = (lo + hi) * 0.5;
         ray.at(mid, point);
-        const midDistance = terrainSignedDistancePrecise(
-          query,
-          point.x,
-          point.y,
-          point.z
-        );
+        const midDistance = refineSignedDistanceAt(point.x, point.y, point.z);
         if (midDistance === void 0) {
           lo = mid;
           continue;
@@ -2644,22 +3260,53 @@ function cpuRaycast(query, ray, config, options) {
         if (midDistance > 0) lo = mid;
         else hi = mid;
       }
-      const hitT = hi;
-      ray.at(hitT, point);
-      const sample = query.sampleTerrain(point.x, point.z);
-      if (!sample.valid) return null;
-      point.y = sample.elevation;
-      return {
-        position: point.clone(),
-        normal: sample.normal.clone(),
-        distance: ray.origin.distanceTo(point)
-      };
+      return hi;
     }
     prevSignedDistance = signedDistance;
     prevT = t;
   }
   return null;
 }
+function cpuRaycast(query, ray, config, options) {
+  const bounds = getTerrainBounds(config);
+  const segment = intersectRayAabb(
+    ray,
+    bounds.minX,
+    config.minY,
+    bounds.minZ,
+    bounds.maxX,
+    config.maxY,
+    bounds.maxZ
+  );
+  if (!segment) return null;
+  const maxDistance = options?.maxDistance ?? Number.POSITIVE_INFINITY;
+  const startT = Math.max(0, segment.tMin);
+  const endT = Math.min(segment.tMax, maxDistance);
+  if (endT < startT) return null;
+  const point = new Vector3();
+  const hitT = marchSignedDistance(
+    ray,
+    startT,
+    endT,
+    (px, py, pz) => terrainSignedDistance(query, px, py, pz, false),
+    (px, py, pz) => terrainSignedDistance(query, px, py, pz, true),
+    {
+      maxSteps: Math.max(8, options?.maxSteps ?? 128),
+      refinementSteps: Math.max(1, options?.refinementSteps ?? 8)
+    },
+    point
+  );
+  if (hitT === null) return null;
+  ray.at(hitT, point);
+  const sample = query.sampleTerrain(point.x, point.z);
+  if (!sample.valid) return null;
+  point.y = sample.elevation;
+  return {
+    position: point.clone(),
+    normal: sample.normal.clone(),
+    distance: ray.origin.distanceTo(point)
+  };
+}
 function cpuRaycastBoundsOnly(ray, config, options) {
   const bounds = getTerrainBounds(config);
   const planeY = (config.minY + config.maxY) * 0.5;
@@ -2680,12 +3327,102 @@ function cpuRaycastBoundsOnly(ray, config, options) {
     distance: ray.origin.distanceTo(point)
   };
 }
+function intersectRaySphere(ray, cx, cy, cz, radius) {
+  const ox = ray.origin.x - cx;
+  const oy = ray.origin.y - cy;
+  const oz = ray.origin.z - cz;
+  const dx = ray.direction.x;
+  const dy = ray.direction.y;
+  const dz = ray.direction.z;
+  const a = dx * dx + dy * dy + dz * dz;
+  const b = 2 * (ox * dx + oy * dy + oz * dz);
+  const c = ox * ox + oy * oy + oz * oz - radius * radius;
+  const disc = b * b - 4 * a * c;
+  if (disc < 0) return null;
+  const sqrtDisc = Math.sqrt(disc);
+  const inv2a = 1 / (2 * a);
+  return { t0: (-b - sqrtDisc) * inv2a, t1: (-b + sqrtDisc) * inv2a };
+}
+function sphereSignedDistance(query, config, px, py, pz, scratchDir) {
+  const cx = config.centerX ?? 0;
+  const cy = config.centerY ?? 0;
+  const cz = config.centerZ ?? 0;
+  const radius = config.radius ?? 0;
+  const dx = px - cx;
+  const dy = py - cy;
+  const dz = pz - cz;
+  const dist = Math.hypot(dx, dy, dz);
+  scratchDir.set(dx, dy, dz);
+  const elevation = query.getElevationByDirection(scratchDir);
+  if (elevation === null) return void 0;
+  return dist - (radius + elevation);
+}
+function cubeSphereRaycast(query, ray, config, options) {
+  const cx = config.centerX ?? 0;
+  const cy = config.centerY ?? 0;
+  const cz = config.centerZ ?? 0;
+  const radius = config.radius ?? 0;
+  const outerRadius = config.maxRadius ?? radius;
+  const shell = intersectRaySphere(ray, cx, cy, cz, outerRadius);
+  if (!shell) return null;
+  const maxDistance = options?.maxDistance ?? Number.POSITIVE_INFINITY;
+  const startT = Math.max(0, shell.t0);
+  const endT = Math.min(shell.t1, maxDistance);
+  if (endT < startT) return null;
+  const scratchDir = new Vector3();
+  const point = new Vector3();
+  const signedDistanceAt = (px, py, pz) => sphereSignedDistance(query, config, px, py, pz, scratchDir);
+  const hitT = marchSignedDistance(
+    ray,
+    startT,
+    endT,
+    signedDistanceAt,
+    signedDistanceAt,
+    {
+      maxSteps: Math.max(8, options?.maxSteps ?? 256),
+      refinementSteps: Math.max(1, options?.refinementSteps ?? 12)
+    },
+    point
+  );
+  if (hitT === null) return null;
+  ray.at(hitT, point);
+  const sample = query.sampleTerrainByPosition(point);
+  if (!sample.valid) return null;
+  return {
+    position: sample.position.clone(),
+    normal: sample.normal.clone(),
+    distance: ray.origin.distanceTo(sample.position)
+  };
+}
+function cubeSphereRaycastBoundsOnly(ray, config, options) {
+  const cx = config.centerX ?? 0;
+  const cy = config.centerY ?? 0;
+  const cz = config.centerZ ?? 0;
+  const radius = config.radius ?? 0;
+  const shell = intersectRaySphere(ray, cx, cy, cz, radius);
+  if (!shell) return null;
+  const maxDistance = options?.maxDistance ?? Number.POSITIVE_INFINITY;
+  const t = shell.t0 >= 0 ? shell.t0 : shell.t1;
+  if (t < 0 || t > maxDistance) return null;
+  const point = new Vector3();
+  ray.at(t, point);
+  const normal = new Vector3(point.x - cx, point.y - cy, point.z - cz).normalize();
+  return { position: point, normal, distance: ray.origin.distanceTo(point) };
+}
 
 function createTerrainRaycast(params) {
   return {
     pick(ray, options) {
       const config = params.getConfig();
       const terrainQuery = params.getTerrainQuery();
+      if (config.projection === "cubeSphere") {
+        const sphereQuery = params.getSphereQuery();
+        if (sphereQuery) {
+          const precise = cubeSphereRaycast(sphereQuery, ray, config, options);
+          if (precise) return precise;
+        }
+        return cubeSphereRaycastBoundsOnly(ray, config, options);
+      }
       if (terrainQuery) {
         const precise = cpuRaycast(terrainQuery, ray, config, options);
         if (precise) return precise;
@@ -2710,29 +3447,47 @@ const BOUNDS_PADDING = 1;
 const RAYCAST_STATE = Symbol("terrainRaycastTaskState");
 const terrainRaycastTask = task(
   (get, work) => {
-    const { query: terrainQuery } = get(terrainQueryTask);
+    const { query: terrainQuery, sphereQuery } = get(terrainQueryTask);
     const rootSizeValue = get(rootSize);
     const originValue = get(origin);
     const elevationScaleValue = get(elevationScale);
+    const radiusValue = get(radius);
+    const topologyValue = get(topologyTask);
+    const projection = topologyValue.projection ?? "flat";
+    const sphereRadius = topologyValue.radius ?? radiusValue;
     return work((prev) => {
       let raycast = prev;
       let state = raycast?.[RAYCAST_STATE];
       if (!state) {
         state = {
           terrainQuery: null,
+          sphereQuery: null,
           bounds: {
             rootSize: 0,
             originX: 0,
             originZ: 0,
             minY: 0,
-            maxY: 0
+            maxY: 0,
+            projection: "flat",
+            centerX: 0,
+            centerY: 0,
+            centerZ: 0,
+            radius: 0,
+            minRadius: 0,
+            maxRadius: 0
           }
         };
       }
       state.terrainQuery = terrainQuery;
+      state.sphereQuery = sphereQuery;
       state.bounds.rootSize = rootSizeValue;
       state.bounds.originX = originValue.x;
       state.bounds.originZ = originValue.z;
+      state.bounds.projection = projection;
+      state.bounds.centerX = originValue.x;
+      state.bounds.centerY = originValue.y;
+      state.bounds.centerZ = originValue.z;
+      state.bounds.radius = sphereRadius;
       const range = terrainQuery.getGlobalElevationRange();
       if (range) {
         state.bounds.minY = range.min - BOUNDS_PADDING;
@@ -2742,9 +3497,19 @@ const terrainRaycastTask = task(
         state.bounds.minY = originValue.y - verticalExtent;
         state.bounds.maxY = originValue.y + verticalExtent;
       }
+      const elevationExtent = Math.max(1, Math.abs(elevationScaleValue));
+      let dispMin = -elevationExtent;
+      let dispMax = elevationExtent;
+      if (range) {
+        dispMin = range.min - originValue.y;
+        dispMax = range.max - originValue.y;
+      }
+      state.bounds.minRadius = Math.max(0, sphereRadius + dispMin - BOUNDS_PADDING);
+      state.bounds.maxRadius = sphereRadius + dispMax + BOUNDS_PADDING;
       if (!raycast) {
         raycast = createTerrainRaycast({
           getTerrainQuery: () => state.terrainQuery,
+          getSphereQuery: () => state.sphereQuery,
           getConfig: () => state.bounds
         });
       }
@@ -2754,15 +3519,12 @@ const terrainRaycastTask = task(
   }
 ).displayName("terrainRaycastTask");
 
-function terrainGraph() {
-  return graph().add(instanceIdTask).add(quadtreeConfigTask).add(quadtreeUpdateTask).add(leafStorageTask).add(surfaceTask).add(leafGpuBufferTask).add(gpuSpatialIndexStorageTask).add(gpuSpatialIndexUploadTask).add(createUniformsTask).add(updateUniformsTask).add(positionNodeTask).add(createElevationFieldContextTask).add(tileNodesTask).add(createTerrainFieldTextureTask).add(createTerrainSamplerTask).add(elevationFieldStageTask).add(terrainFieldStageTask).add(compileComputeTask).add(executeComputeTask).add(tileBoundsContextTask).add(tileBoundsReductionTask).add(terrainQueryTask).add(terrainReadbackTask).add(terrainRaycastTask);
-}
 const terrainTasks = {
   instanceId: instanceIdTask,
   quadtreeConfig: quadtreeConfigTask,
   quadtreeUpdate: quadtreeUpdateTask,
   leafStorage: leafStorageTask,
-  surface: surfaceTask,
+  topology: topologyTask,
   leafGpuBuffer: leafGpuBufferTask,
   gpuSpatialIndexStorage: gpuSpatialIndexStorageTask,
   gpuSpatialIndexUpload: gpuSpatialIndexUploadTask,
@@ -2783,6 +3545,13 @@ const terrainTasks = {
   terrainReadback: terrainReadbackTask,
   terrainRaycast: terrainRaycastTask
 };
+function terrainGraph() {
+  const g = graph();
+  for (const t of Object.values(terrainTasks)) {
+    g.add(t);
+  }
+  return g;
+}
 
 const textureSpaceToVectorSpace = Fn(([value]) => {
   return remap(value, float(0), float(1), float(-1), float(1));
@@ -2793,7 +3562,7 @@ const vectorSpaceToTextureSpace = Fn(([value]) => {
 const blendAngleCorrectedNormals = Fn(([n1, n2]) => {
   const t = vec3(n1.x, n1.y, n1.z.add(1));
   const u = vec3(n2.x.negate(), n2.y.negate(), n2.z);
-  const r = t.mul(dot(t, u)).sub(u.mul(t.z)).normalize();
+  const r = t.mul(dot$1(t, u)).sub(u.mul(t.z)).normalize();
   return r;
 });
 const deriveNormalZ = Fn(([normalXY]) => {
@@ -2836,4 +3605,4 @@ const voronoiCells = Fn((params) => {
   return k;
 });
 
-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 { ArrayTextureBackend, AtlasBackend, CUBE_FACES, CUBE_FACE_COUNT, Dir, TerrainGeometry, TerrainMesh, U32_EMPTY, allocLeafSet, allocSeamTable, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, compileComputeTask, createComputePipelineTasks, createCubeSphereTopology, createElevationFieldContextTask, createFlatTopology, createInfiniteFlatTopology, createSpatialIndex, createState, createTerrainFieldStorage, createTerrainFieldTextureTask, createTerrainQuery, createTerrainRaycast, createTerrainSampler, createTerrainSamplerTask, createTerrainSphereQuery, createTerrainUniforms, 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, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, radius, resetLeafSet, resetSeamTable, rootSize, sampleTerrainField, sampleTerrainFieldElevation, skirtScale, sphereTangentFrameNormal, storeTerrainField, tangentFromAxis, terrainFieldFilter, terrainFieldStageTask, terrainGraph, terrainQueryTask, terrainRaycastTask, terrainReadbackTask, terrainTasks, textureSpaceToVectorSpace, tileNodesTask, topology, topologyTask, unpackTangentNormal, update, updateUniformsTask, vElevation, vGlobalVertexIndex, vectorSpaceToTextureSpace, voronoiCells };