mapspinner 0.1.38 → 0.1.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mapspinner",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "description": "WebGL2 Earth-scale terrain rendering SDK for interactive globe applications",
   "main": "src/index.js",
   "exports": {

package/src/gl-render.js

@@ -272,6 +272,140 @@ export async function initMapspinnerRender(gl, opts = {}) {
     return out[0];
   }
 
+  // ===== THC HEIGHT-CACHE BAKE (2026-06-14, NON-DESTRUCTIVE) =====
+  // A separate program renders composeHeight for one tile into an R32F grid (a fullscreen tri; each
+  // fragment = one tile parametric texel). Used FIRST as a readback witness (bake vs procedural
+  // sampleGroundM) to prove the bake matches the geometry; the pool/LRU + the VS-sample switch are
+  // later DAG nodes. _faceFrames mirror terrain.glsl faceFrame() columns (column-major mat3).
+  const THC_BAKE_RES = 130;
+  const _faceFrames = [
+    [0,0,-1, 0,1,0, 1,0,0], [0,0,1, 0,1,0, -1,0,0],
+    [1,0,0, 0,0,-1, 0,1,0], [1,0,0, 0,0,1, 0,-1,0],
+    [1,0,0, 0,1,0, 0,0,1], [-1,0,0, 0,1,0, 0,0,-1],
+  ];
+  let bakeProg=null, bakeTex=null, bakeFbo=null, _bakeBuilding=null; const _bakeUloc=new Map();
+  const BU = n => { let l=_bakeUloc.get(n); if(l===undefined){ l=gl.getUniformLocation(bakeProg,n); _bakeUloc.set(n,l);} return l; };
+  function ensureBake(){
+    if (bakeProg || _bakeBuilding) return;
+    _bakeBuilding = (async () => {
+      try {
+        const bvs = hdr + 'void main(){ vec2 p=vec2((gl_VertexID==1)?3.0:-1.0,(gl_VertexID==2)?3.0:-1.0); gl_Position=vec4(p,0.0,1.0); }';
+        const bfs = hdr + '\n#define _HEIGHTBAKE_\n' + src;
+        const bv=gl.createShader(gl.VERTEX_SHADER); gl.shaderSource(bv,bvs); gl.compileShader(bv);
+        const bf=gl.createShader(gl.FRAGMENT_SHADER); gl.shaderSource(bf,bfs); gl.compileShader(bf);
+        const bp=gl.createProgram(); gl.attachShader(bp,bv); gl.attachShader(bp,bf); gl.linkProgram(bp);
+        await awaitProgramLink(bp, bv, bf, 'bake');
+        const tex=gl.createTexture(); gl.bindTexture(gl.TEXTURE_2D, tex);
+        gl.texStorage2D(gl.TEXTURE_2D, 1, gl.R32F, THC_BAKE_RES, THC_BAKE_RES);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST); gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+        const fbo=gl.createFramebuffer(); gl.bindFramebuffer(gl.FRAMEBUFFER, fbo);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, tex, 0);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        _bakeUloc.clear(); bakeTex=tex; bakeFbo=fbo; bakeProg=bp;
+      } catch(e){ bakeProg=null; try{ if(typeof window!=='undefined') window.__bakeErr=String(e.message||e); }catch(_){} }
+      finally { _bakeBuilding=null; }
+    })();
+  }
+  const bakeVao = gl.createVertexArray();
+  // bake ONE tile into bakeTex + read it back (Float32Array of THC_BAKE_RES^2 heights). Returns null
+  // until the program is built (lazy). NON-DESTRUCTIVE: does not touch the live render path.
+  function bakeTileReadback(face, ox, oy, l, level){
+    if (!bakeProg){ ensureBake(); return null; }
+    gl.bindFramebuffer(gl.FRAMEBUFFER, bakeFbo);
+    gl.viewport(0,0,THC_BAKE_RES,THC_BAKE_RES);
+    gl.useProgram(bakeProg);
+    gl.bindVertexArray(bakeVao);
+    if (_hpfTex){ gl.activeTexture(gl.TEXTURE3); gl.bindTexture(gl.TEXTURE_2D_ARRAY,_hpfTex); gl.uniform1i(BU('hpfPool'),3); }
+    if (_hpfTex2){ gl.activeTexture(gl.TEXTURE5); gl.bindTexture(gl.TEXTURE_2D_ARRAY,_hpfTex2); gl.uniform1i(BU('hpfPool2'),5); }
+    gl.uniform1i(BU('hasHpf'), _hpfTex?1:0);
+    setComposeHeightUniforms(BU);
+    gl.uniform1f(BU('defRadius'), R);
+    gl.uniformMatrix3fv(BU('uBakeFrame'), false, new Float32Array(_faceFrames[face|0]));
+    gl.uniform4f(BU('uBakeOffset'), ox, oy, l, level);
+    gl.uniform1f(BU('uBakeRes'), THC_BAKE_RES);
+    gl.disable(gl.DEPTH_TEST);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+    const buf = new Float32Array(THC_BAKE_RES*THC_BAKE_RES*4);
+    gl.readPixels(0,0,THC_BAKE_RES,THC_BAKE_RES, gl.RGBA, gl.FLOAT, buf);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.bindVertexArray(null);
+    const out = new Float32Array(THC_BAKE_RES*THC_BAKE_RES);
+    for (let i=0;i<out.length;i++) out[i]=buf[i*4];
+    let dbg=null; try{ dbg={ offLoc: BU('uBakeOffset')!=null, resLoc: BU('uBakeRes')!=null, frameLoc: BU('uBakeFrame')!=null,
+      offRead: BU('uBakeOffset')?Array.from(gl.getUniform(bakeProg, BU('uBakeOffset'))):null,
+      resRead: BU('uBakeRes')?gl.getUniform(bakeProg, BU('uBakeRes')):null }; }catch(e){ dbg={err:String(e)}; }
+    return { heights: out, res: THC_BAKE_RES, dbg };
+  }
+  if (typeof window !== 'undefined') { window.__thcBakeReadback = bakeTileReadback; window.__thcEnsureBake = ensureBake; }
+
+  // ===== THC HEIGHT POOL + LRU (the VS-sample consumer; the FPS win) =====
+  // The VS samples a baked per-tile height (O(1) texture fetch) instead of composeHeight 5x/vertex,
+  // when window.__thc is on. A 2D-array pool holds one BAKE_RES^2 R32F layer per live tile; a leaf
+  // gets a layer (baked once) on first sight, LRU-evicted when the pool is full. Default OFF -> the
+  // live render is unchanged (composeHeight), so this is safe to ship behind the toggle.
+  const THC_POOL_LAYERS = 512;
+  let heightPool=null, poolFbo=null;
+  const _tcMap = new Map();                                   // tileKey -> layer
+  const _tcLayerKey = new Array(THC_POOL_LAYERS).fill(null);  // layer -> tileKey (evict bookkeeping)
+  const _tcUsed = new Int32Array(THC_POOL_LAYERS);            // layer -> last-used frame
+  let _tcFrame = 0, _tcNextFree = 0, _tcBakesThisFrame = 0;
+  // BAKE-ON-EDIT: terraform/HPF changes make every baked layer stale -> drop the whole map so each
+  // visible tile re-bakes on next sight (synchronously, before its draw -> no black/stale frame).
+  function invalidatePool(){ _tcMap.clear(); _tcLayerKey.fill(null); _tcNextFree = 0; }
+  function ensurePool(){
+    if (heightPool) return;
+    heightPool = gl.createTexture(); gl.bindTexture(gl.TEXTURE_2D_ARRAY, heightPool);
+    gl.texStorage3D(gl.TEXTURE_2D_ARRAY, 1, gl.R32F, THC_BAKE_RES, THC_BAKE_RES, THC_POOL_LAYERS);
+    const lin = _halfFloatLinearOK ? gl.LINEAR : gl.NEAREST;   // R32F LINEAR needs OES_texture_float_linear; else VS does manual bilinear
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MIN_FILTER, lin); gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, lin);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE); gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    poolFbo = gl.createFramebuffer();
+  }
+  function bakeTileToLayer(face,ox,oy,l,level,layer){
+    gl.bindFramebuffer(gl.FRAMEBUFFER, poolFbo);
+    gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, heightPool, 0, layer);
+    gl.viewport(0,0,THC_BAKE_RES,THC_BAKE_RES);
+    gl.useProgram(bakeProg); gl.bindVertexArray(bakeVao);
+    if (_hpfTex){ gl.activeTexture(gl.TEXTURE3); gl.bindTexture(gl.TEXTURE_2D_ARRAY,_hpfTex); gl.uniform1i(BU('hpfPool'),3); }
+    if (_hpfTex2){ gl.activeTexture(gl.TEXTURE5); gl.bindTexture(gl.TEXTURE_2D_ARRAY,_hpfTex2); gl.uniform1i(BU('hpfPool2'),5); }
+    gl.uniform1i(BU('hasHpf'), _hpfTex?1:0);
+    setComposeHeightUniforms(BU);
+    gl.uniform1f(BU('defRadius'), R);
+    gl.uniformMatrix3fv(BU('uBakeFrame'), false, new Float32Array(_faceFrames[face|0]));
+    gl.uniform4f(BU('uBakeOffset'), ox, oy, l, level);
+    gl.uniform1f(BU('uBakeRes'), THC_BAKE_RES);
+    gl.disable(gl.DEPTH_TEST);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+    _tcBakesThisFrame++;
+  }
+  // pool layer for a tile, baked on first sight; LRU-evicts when full. Returns -1 if not yet bakeable.
+  function ensureTileLayer(face,ox,oy,l,level){
+    const key = face+':'+ox+':'+oy+':'+l;
+    let layer = _tcMap.get(key);
+    if (layer === undefined){
+      if (_tcNextFree < THC_POOL_LAYERS){ layer = _tcNextFree++; }
+      else { let lru=0, lruF=_tcUsed[0]; for(let k=1;k<THC_POOL_LAYERS;k++) if(_tcUsed[k]<lruF){lruF=_tcUsed[k];lru=k;} layer=lru; const old=_tcLayerKey[lru]; if(old!=null) _tcMap.delete(old); }
+      _tcMap.set(key, layer); _tcLayerKey[layer]=key;
+      bakeTileToLayer(face,ox,oy,l,level,layer);
+    }
+    _tcUsed[layer]=_tcFrame;
+    return layer;
+  }
+  // THC active = toggle on AND both programs/pool ready. Builds them lazily; returns false until ready
+  // so the first frames fall back to composeHeight (uThc=0) with no garbage.
+  let _tcInvSeen = 0;
+  function thcActive(){
+    if (typeof window==='undefined' || !window.__thc) return false;
+    if (!bakeProg){ ensureBake(); return false; }
+    ensurePool();
+    // live re-bake hook: window.__thcInvalidate() bumps __thcInval; any composeHeight-shaping edit
+    // (e.g. __gen biome/relief dials) should call it so the baked pool refreshes.
+    const inv = (window.__thcInval|0);
+    if (inv !== _tcInvSeen){ _tcInvSeen = inv; invalidatePool(); }
+    return !!heightPool;
+  }
+  if (typeof window !== 'undefined') window.__thcInvalidate = () => { window.__thcInval = (window.__thcInval|0) + 1; };
+
   // FLOAT-LINEAR FORMAT PROBE (NOT a quality tier): OES_texture_float_linear lets the HPF atlas pools
   // filter LINEAR in hardware -> hpfSample collapses to one texture() call. 0 = manual 4-tap fallback.
   const _halfFloatLinearOK = !!gl.getExtension('OES_texture_float_linear') || !!gl.getExtension('OES_texture_half_float_linear');
@@ -576,7 +710,7 @@ export async function initMapspinnerRender(gl, opts = {}) {
   // the instance data is identical -> skip the Float32Array build + bufferData + water dedup Set-loop
   // and just rebind+draw. Pure CPU/GC win (GPU is vertex-bound, the upload is off the critical path).
   const instBufWater=gl.createBuffer();
-  let _instQuadsRef=null, _instWaterRef=null, _instWaterN=0;
+  let _instQuadsRef=null, _instWaterRef=null, _instWaterN=0, _lastThc=false;
 
   // per-face local->world (cube face -> sphere local frame). Column-major mat3 packed
   // into a Float32Array(9). Matches localToWorld3 convention:
@@ -896,14 +1030,27 @@ export async function initMapspinnerRender(gl, opts = {}) {
     gl.uniformMatrix4fv(U('defViewProjRel'), false, viewProjRel);
     gl.uniform1f(U('defRadius'), R);
     const n = quads.length;
-    // SINGLE-SOURCE HEIGHT: every leaf is the pure per-vertex composeHeight() function, evaluated every
-    // frame -- no bake cache. The instance buffer carries [ox,oy,l,level,face] (5 floats); the VS computes
-    // h = composeHeight(dir) for each vertex.
-    const FLOATS = 5;   // [ox,oy,l,level,face]
+    // Instance buffer: [ox,oy,l,level,face, iLayer] (6 floats). iLayer = the THC pool layer for this
+    // tile (when __thc on); the VS samples the baked height there instead of composeHeight.
+    const FLOATS = 6;   // [ox,oy,l,level,face, iLayer]
     if (n > 0) {
-      // STATIC-FRAME SKIP: only rebuild + re-upload the instance data when the quad SET changed (the
-      // orchestrator passes the SAME quads array object on a static camera, a fresh array on rebuild).
-      const _dirty = (quads !== _instQuadsRef);
+      // THC: when active, ensure every visible tile has a baked pool layer (bake on first sight). The
+      // bakes clobber the FBO/program/viewport -> restore the canvas render state afterward.
+      const _thc = thcActive();
+      let _layers = null;
+      if (_thc) {
+        _tcFrame++; _tcBakesThisFrame = 0;
+        _layers = new Float32Array(n);
+        for (let i = 0; i < n; i++) { const q = quads[i].quad; _layers[i] = ensureTileLayer(quads[i].face, q.ox, q.oy, q.l, q.level); }
+        gl.bindVertexArray(null);   // bakeTileToLayer left bakeVao bound; the main path uses the default VAO
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        gl.viewport(0, 0, gl.drawingBufferWidth, gl.drawingBufferHeight);
+        gl.enable(gl.DEPTH_TEST);   // bakeTileToLayer disabled depth
+        gl.useProgram(_activeProg);
+        if (typeof window !== 'undefined') window.__thcBakes = _tcBakesThisFrame;
+      }
+      // STATIC-FRAME SKIP: rebuild only when the quad set changed OR the toggle flipped (iLayer needs writing).
+      const _dirty = (quads !== _instQuadsRef) || (_thc !== _lastThc);
       gl.bindBuffer(gl.ARRAY_BUFFER, instBuf);
       if (_dirty) {
         const inst = new Float32Array(n * FLOATS);
@@ -911,12 +1058,17 @@ export async function initMapspinnerRender(gl, opts = {}) {
           const q = quads[i].quad;
           inst[i*FLOATS+0] = q.ox; inst[i*FLOATS+1] = q.oy; inst[i*FLOATS+2] = q.l; inst[i*FLOATS+3] = q.level;
           inst[i*FLOATS+4] = quads[i].face;
+          inst[i*FLOATS+5] = _layers ? _layers[i] : 0.0;
         }
         gl.bufferData(gl.ARRAY_BUFFER, inst, gl.DYNAMIC_DRAW);
       }
+      _lastThc = _thc;
       const STRIDE = FLOATS * 4;
       gl.enableVertexAttribArray(1); gl.vertexAttribPointer(1, 4, gl.FLOAT, false, STRIDE, 0);          gl.vertexAttribDivisor(1, 1);  // iOffset
       gl.enableVertexAttribArray(2); gl.vertexAttribPointer(2, 1, gl.FLOAT, false, STRIDE, 4 * 4);      gl.vertexAttribDivisor(2, 1);  // iFace
+      gl.enableVertexAttribArray(3); gl.vertexAttribPointer(3, 1, gl.FLOAT, false, STRIDE, 5 * 4);      gl.vertexAttribDivisor(3, 1);  // iLayer (THC pool layer)
+      gl.uniform1f(U('uThc'), _thc ? 1.0 : 0.0);
+      if (_thc) { gl.activeTexture(gl.TEXTURE8); gl.bindTexture(gl.TEXTURE_2D_ARRAY, heightPool); gl.uniform1i(U('uHeightPool'), 8); gl.uniform1f(U('uPoolRes'), THC_BAKE_RES); gl.uniform1f(U('uPoolLinear'), _halfFloatLinearOK ? 1.0 : 0.0); }
       gl.uniform1f(U('uIsWater'), 0.0);
       // UNDERWATER DETECTION: camera below sea level enables underwater shading + water surface
       // rendering from below. Set before the terrain draw so the FS can apply underwater fog.
@@ -951,7 +1103,7 @@ export async function initMapspinnerRender(gl, opts = {}) {
             if (lv > WCAP) { const A = l * Math.pow(2, lv - WCAP); ox = Math.floor(ox / A) * A; oy = Math.floor(oy / A) * A; l = A; lv = WCAP; }
             const key = quads[i].face + ':' + ox + ':' + oy + ':' + l;
             if (seen.has(key)) continue; seen.add(key);
-            wl.push(ox, oy, l, lv, quads[i].face);
+            wl.push(ox, oy, l, lv, quads[i].face, 0);   // iLayer unused for water (VS pins sea level)
           }
           _instWaterN = wl.length / FLOATS;
           gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(wl), gl.DYNAMIC_DRAW);
@@ -1014,6 +1166,6 @@ export async function initMapspinnerRender(gl, opts = {}) {
     }
     return out;
   }
-  function setHpf(tex, res, tex2) { _hpfTex = tex; _hpfRes = res|0; _hpfTex2 = tex2 || null; }   // tex2 = RG8(temp,humid) pack (W12)
+  function setHpf(tex, res, tex2) { _hpfTex = tex; _hpfRes = res|0; _hpfTex2 = tex2 || null; invalidatePool(); }   // tex2 = RG8(temp,humid) pack (W12); HPF change -> re-bake THC tiles
   return { get prog(){ return prog; }, render, checkGlError, probe, sampleGroundM, cullMatrix, recompile, setHpf, GRID, indexCount: indices.length, M4 };
 }

package/src/shaders/terrain.glsl

@@ -390,7 +390,7 @@ highp vec2 faceWarp(highp vec2 p){ return defRadius * tan((p / defRadius) * 0.78
 uniform float uDetailOverlay;   // amplitude lever (user-tuned 6; 0 = off; __detailOverlay)
 uniform float uGrid;             // interior cells per tile edge (GRID=16); for mesh-based vertex normals
 uniform float uNrmStepM;        // lit-normal FD step in metres (150); uniform-fed to defeat FXC constant folding
-#if defined(_VERTEX_) || defined(_PROBE_)
+#if defined(_VERTEX_) || defined(_PROBE_) || defined(_HEIGHTBAKE_)
 highp float broadShapeM(vec3 dir, float reliefMul, float ridgeMul){   // W7: returns metres (~13000) -> highp
   if (hasHpf == 0) return 0.0;
   float mtnAmp = 1.0;   // mountain-amplitude (was a window.__mtnAmp uniform; inlined at neutral 1.0)
@@ -693,6 +693,25 @@ highp float composeHeight(vec3 dir0, highp vec2 faceLocal, float tileM){   // W7
 layout(location=0) in vec3 vertex;   // vertex.xy in [0,1] parametric quad coord
 layout(location=1) in highp vec4 iOffset;  // W7: PER-INSTANCE (ox, oy, l, level) face-local metres ~6.4e6 -> highp
 layout(location=2) in float iFace;   // PER-INSTANCE cube face index 0..5
+layout(location=3) in float iLayer;  // THC: PER-INSTANCE height-pool array layer for this tile (uThc on)
+// THC (Tile Heightmap Cache): when uThc>0.5 the VS reads the baked composeHeight from uHeightPool
+// (a 2D-array, one layer per visible tile, parametric uv = vertex.xy) instead of re-evaluating
+// composeHeight 5x/vertex. uPoolLinear=0 -> manual bilinear (R32F not linear-filterable).
+uniform float uThc;
+uniform sampler2DArray uHeightPool;
+uniform float uPoolRes;
+uniform float uPoolLinear;
+highp float thcSample(highp vec2 uv, float layer){
+    highp vec2 t = clamp(uv, 0.0, 1.0) * (uPoolRes - 1.0);
+    if (uPoolLinear > 0.5) return texture(uHeightPool, vec3((t + 0.5) / uPoolRes, layer)).r;
+    highp vec2 f = floor(t); highp vec2 fr = t - f;
+    highp vec2 b0 = (f + 0.5) / uPoolRes, b1 = (f + 1.5) / uPoolRes;
+    highp float h00 = texture(uHeightPool, vec3(b0.x, b0.y, layer)).r;
+    highp float h10 = texture(uHeightPool, vec3(b1.x, b0.y, layer)).r;
+    highp float h01 = texture(uHeightPool, vec3(b0.x, b1.y, layer)).r;
+    highp float h11 = texture(uHeightPool, vec3(b1.x, b1.y, layer)).r;
+    return mix(mix(h00, h10, fr.x), mix(h01, h11, fr.x), fr.y);
+}
 out highp vec3 vWorld;   // W7 highp ISLAND: absolute world pos ~6.4e6 m (FS lighting/atmosphere) -- fp16 would jitter it
 out highp float vH;      // W7: signed elevation (metres, ~13000) -- highp for the material ramp / strata / ocean depth
 out highp vec3 vNrm;     // W8: world-space per-vertex analytic normal (fixed-step central diff of the FULL composeHeight). The SOLE FS lit normal -- replaces the jittery cross(dFdx,dFdy). highp to match vWorld on the ~6.4e6 m planet.
@@ -949,7 +968,26 @@ void main() {
     // sides of a seam share the same dir0/tangent frame -> consistent normals, no row artifact.
     highp float hN0 = 0.0;
     highp vec3 vN = dir0;
-    if (uIsWater < 0.5) {
+    if (uIsWater < 0.5 && uThc > 0.5) {
+        // THC FAST PATH: height + symmetric central-diff normal from the baked pool. 5 bilinear texture
+        // taps replace 5 full composeHeight evals (the VS-bound cost). The 4 normal taps use the SAME
+        // parametric step as the composeHeight path; the dir at each tap is a cheap faceWarp+normalize
+        // (no field eval). uNrmStepM-scaled step => the same smoothed (low-pass) normal as the slow path.
+        hN0 = thcSample(vertex.xy, iLayer);
+        highp float nStepM = (uNrmStepM > 0.0) ? uNrmStepM : 300.0;
+        highp float duP = clamp(nStepM / max(defOffset.z, 1.0), 1.0 / ((uGrid > 0.0) ? uGrid : 16.0), 0.34);
+        highp float hPU = thcSample(vertex.xy + vec2(duP, 0.0), iLayer);
+        highp float hMU = thcSample(vertex.xy + vec2(-duP, 0.0), iLayer);
+        highp float hPV = thcSample(vertex.xy + vec2(0.0, duP), iLayer);
+        highp float hMV = thcSample(vertex.xy + vec2(0.0, -duP), iLayer);
+        highp vec3 dPU = normalize(defLocalToWorld * vec3(faceWarp((vertex.xy + vec2(duP,0.0)) * defOffset.z + defOffset.xy), defRadius));
+        highp vec3 dMU = normalize(defLocalToWorld * vec3(faceWarp((vertex.xy + vec2(-duP,0.0)) * defOffset.z + defOffset.xy), defRadius));
+        highp vec3 dPV = normalize(defLocalToWorld * vec3(faceWarp((vertex.xy + vec2(0.0,duP)) * defOffset.z + defOffset.xy), defRadius));
+        highp vec3 dMV = normalize(defLocalToWorld * vec3(faceWarp((vertex.xy + vec2(0.0,-duP)) * defOffset.z + defOffset.xy), defRadius));
+        vN = normalize(cross(dPU * (defRadius + hPU) - dMU * (defRadius + hMU),
+                             dPV * (defRadius + hPV) - dMV * (defRadius + hMV)));
+        if (dot(vN, dir0) < 0.0) vN = -vN;
+    } else if (uIsWater < 0.5) {
         hN0 = composeHeight(dir0, faceLocal, defOffset.z);   // center = the geometry height h
         // VERTEX NORMAL = CENTRAL DIFFERENCE in PARAMETRIC MESH SPACE over the FULL composeHeight (2026-06-14
         // jagged-normal fix). Two earlier methods both jagged: (a) interior FORWARD mesh-cell cross product
@@ -2229,3 +2267,22 @@ void main(){
     probeOut = vec4(h, 0.0, 0.0, 1.0);
 }
 #endif
+
+#ifdef _HEIGHTBAKE_
+// THC HEIGHT-CACHE BAKE (2026-06-14): render ONE tile's composeHeight into a height-pool texel grid.
+// Each fragment = one parametric (u,v) of the tile; the dir + faceLocal mapping is IDENTICAL to the
+// mesh VS (faceWarp(vertex.xy*defOffset.z+defOffset.xy), normalize(frame*vec3(faceLocal,defRadius)))
+// so the baked height matches the procedural geometry exactly. NON-DESTRUCTIVE: this is a separate
+// program; the live VS still computes composeHeight until thc-vs-sample switches it to a pool sample.
+uniform mat3 uBakeFrame;    // face-local -> world for this tile's face (== faceFrame(face))
+uniform vec4 uBakeOffset;   // tile (ox, oy, l, level) face-local metres (== iOffset)
+uniform float uBakeRes;     // bake grid resolution (texels per edge)
+out vec4 bakeOut;
+void main(){
+    highp vec2 uv = (gl_FragCoord.xy - 0.5) / max(uBakeRes - 1.0, 1.0);   // texel -> parametric [0,1]
+    highp vec2 faceLocal = faceWarp(uv * uBakeOffset.z + uBakeOffset.xy);
+    highp vec3 dir0 = normalize(uBakeFrame * vec3(faceLocal, defRadius));
+    highp float h = composeHeight(dir0, faceLocal, uBakeOffset.z);
+    bakeOut = vec4(h, 0.0, 0.0, 1.0);
+}
+#endif