s3m-three 0.3.7 → 0.3.9

package/src/render/StyleMaterial.ts

@@ -115,8 +115,23 @@ export interface S3MStyle {
   roofThreshold?: number;
   /** 是否与模型原色贴图叠加混合（0 = 纯色覆盖，1 = 叠乘原色贴图） */
   texMix?: number;
+  /**
+   * 基础漫反射底色增益 / 直通自发光微调（0~1，默认 0.0，建议开启 TOP_SIDE 时可设 0.15~0.3）。
+   * 绕过光照夹角直接补偿表面暗部底色，让 TOP_SIDE / 自定义等模式下的背光阴影面保持通透、不至于过黑。
+   */
+  ambientGain?: number;
   /** 半透明时是否保持深度写入（默认 true，保持写入可彻底遮挡背面与内部棱线，避免背面透出） */
   depthWrite?: boolean;
+  /**
+   * 新瓦片首次出现时的淡入时长（毫秒，0 = 关闭）。
+   *
+   * 只影响「刚加载进来」的瓦片，已经显示的不会被重播。LOD 细化换瓦片时也会淡入，
+   * 视觉上比「啪」一下换掉柔和得多。
+   *
+   * 注意代价：淡入期间该瓦片会进透明渲染队列（混合 + 前后排序），首次加载
+   * 几百块瓦片同时淡入时会有一小段额外开销，所以默认关闭、按需开启。
+   */
+  fadeIn?: number;
 }
 
 export const DEFAULT_STYLE: S3MStyle = {
@@ -147,7 +162,9 @@ export const DEFAULT_STYLE: S3MStyle = {
   edgeThreshold: 55,
   roofThreshold: 0.65,
   texMix: 0,
+  ambientGain: 0,
   depthWrite: true,
+  fadeIn: 0,
 };
 
 export interface StyledMaterial extends THREE.MeshStandardMaterial {
@@ -155,15 +172,24 @@ export interface StyledMaterial extends THREE.MeshStandardMaterial {
     uSelBatch: { value: number };
     uSelWhole: { value: number };
     uBatchTex: { value: THREE.Texture };
+    uBatchTex2: { value: THREE.Texture };
     uBatchTexWidth: { value: number };
     uBatchTexActive: { value: number };
+    /** 单块瓦片的淡入系数（1 = 完全显示） */
+    uTileFade: { value: number };
     isStyled: true;
     [key: string]: unknown;
   };
 }
 
-const DUMMY_DATA = new Float32Array([-1, -1, -1, 0, 0, 0, 0, 0]);
-export const DUMMY_BATCH_TEX = new THREE.DataTexture(DUMMY_DATA, 1, 2, THREE.RGBAFormat, THREE.FloatType);
+const DUMMY_DATA = new Float32Array([
+  -1, -1, -1, 0, // Row 0: color rgb, elevation/hidden
+  0, 0, 0, 0,    // Row 1: translation xyz, opacity
+  1, 0, 0, 0,    // Row 2: rot row 0, pivot.x
+  0, 1, 0, 0,    // Row 3: rot row 1, pivot.y
+  0, 0, 1, 0,    // Row 4: rot row 2, pivot.z
+]);
+export const DUMMY_BATCH_TEX = new THREE.DataTexture(DUMMY_DATA, 1, 5, THREE.RGBAFormat, THREE.FloatType);
 DUMMY_BATCH_TEX.minFilter = THREE.NearestFilter;
 DUMMY_BATCH_TEX.magFilter = THREE.NearestFilter;
 DUMMY_BATCH_TEX.needsUpdate = true;
@@ -205,9 +231,27 @@ export function createSharedUniforms(): StyleUniforms {
     uRoofThreshold: { value: 0.65 },
     /** 与模型原色贴图混合强度：0 = 纯色覆盖，1 = 叠乘原色贴图 */
     uTexMix: { value: 0 },
+    /** 基础底色增益 / 暗部补偿（0~1，默认 0.0） */
+    uAmbientGain: { value: 0 },
+    /** 双纹理交叉淡化插值系数（0 = 纯 uBatchTex, 1 = 纯 uBatchTex2） */
+    uBatchMix: { value: 0 },
+    /**
+     * 图层整体透明度：在片元里乘进 diffuseColor.a。
+     *
+     * 为什么不做成 `material.opacity`：那是逐材质写入，几百块瓦片就是 O(meshes)，
+     * 而且跨 0.999 改 `material.transparent` 会换 program（`opaque` 参与缓存键）。
+     * 放到共享 uniform 里，透明度动画就退化成一次 float 赋值。
+     */
+    uOpacity: { value: 1 },
+    /** 棱线淡入淡出乘子：setEdges 过渡期间 0→1，新插入的瓦片自动继承 */
+    uEdgeFade: { value: 1 },
+    /**
+     * 整体压暗乘子：`mode` 这类不可插值的切换用它做 fade-through
+     * （压暗 → 换模式 → 亮回来），比硬切自然得多。
+     */
+    uFade: { value: 1 },
   };
 }
-
 const VERT_PARS = /* glsl */ `
   attribute float aBatchId;
   attribute vec3 aColor;
@@ -229,6 +273,8 @@ const VERT_PARS = /* glsl */ `
   uniform float uSelWhole;
   uniform float uSelElevation;
   uniform sampler2D uBatchTex;
+  uniform sampler2D uBatchTex2;
+  uniform float uBatchMix;
   uniform float uBatchTexWidth;
   uniform int uBatchTexActive;
   varying float vBatchId;
@@ -237,6 +283,11 @@ const VERT_PARS = /* glsl */ `
   varying vec3 vWorldNormal;
   varying vec3 vWorldPos;
 
+  // 跨 chunk 共享的顶点姿态变量（在 beginnormal_vertex 建立，begin_vertex / worldpos 使用）
+  vec3 s3mCustomOffset;
+  mat3 s3mRot;
+  vec3 s3mPivot;
+
   /** 当前图元所属单体的控制位：实例化取实例属性，其余取逐顶点属性 */
   float s3mBatchRaw() {
     #ifdef USE_INSTANCING
@@ -245,27 +296,85 @@ const VERT_PARS = /* glsl */ `
       return aBatchId;
     #endif
   }
+
+  vec4 s3mSampleBatch( sampler2D texA, sampler2D texB, vec2 uv, float mixVal ) {
+    vec4 vA = texture2D( texA, uv );
+    if ( mixVal <= 0.0001 ) return vA;
+    vec4 vB = texture2D( texB, uv );
+    return mix( vA, vB, mixVal );
+  }
+
+  vec4 s3mSampleBatchRow0( sampler2D texA, sampler2D texB, vec2 uv, float mixVal ) {
+    vec4 vA = texture2D( texA, uv );
+    if ( mixVal <= 0.0001 ) return vA;
+    vec4 vB = texture2D( texB, uv );
+    vec4 res = mix( vA, vB, mixVal );
+    if ( vA.r < 0.0 && vB.r >= 0.0 ) {
+      res.rgb = vB.rgb;
+    } else if ( vA.r >= 0.0 && vB.r < 0.0 ) {
+      res.rgb = vA.rgb;
+    }
+    if ( vA.a < -0.5 || vB.a < -0.5 ) {
+      res.a = ( mixVal >= 0.5 ) ? vB.a : vA.a;
+    }
+    return res;
+  }
+
+  vec4 s3mSampleBatchRow1( sampler2D texA, sampler2D texB, vec2 uv, float mixVal ) {
+    vec4 vA = texture2D( texA, uv );
+    if ( mixVal <= 0.0001 ) return vA;
+    vec4 vB = texture2D( texB, uv );
+    vec4 res = mix( vA, vB, mixVal );
+    if ( vA.a == 0.0 && vB.a > 0.0 ) {
+      res.a = mix( 1.0, vB.a, mixVal );
+    } else if ( vA.a > 0.0 && vB.a == 0.0 ) {
+      res.a = mix( vA.a, 1.0, mixVal );
+    }
+    return res;
+  }
 `;
 
-const VERT_ELEVATION = /* glsl */ `
-  float s3mBatch = s3mBatchRaw();
-  vec3 s3mCustomOffset = vec3( 0.0 );
-  if ( uBatchTexActive > 0 && s3mBatch >= 0.0 ) {
-    vec4 bState = texture2D( uBatchTex, vec2( ( s3mBatch + 0.5 ) / uBatchTexWidth, 0.25 ) );
-    if ( bState.a < -0.5 ) {
-      transformed = vec3( 0.0 );
-    } else {
-      vec4 bOffset = texture2D( uBatchTex, vec2( ( s3mBatch + 0.5 ) / uBatchTexWidth, 0.75 ) );
+const VERT_SETUP = /* glsl */ `
+  s3mCustomOffset = vec3( 0.0 );
+  s3mRot = mat3( 1.0 );
+  s3mPivot = vec3( 0.0 );
+  float s3mBatchSetup = s3mBatchRaw();
+  if ( uBatchTexActive > 0 && s3mBatchSetup >= 0.0 ) {
+    float s3mU = ( s3mBatchSetup + 0.5 ) / uBatchTexWidth;
+    vec4 bState = s3mSampleBatchRow0( uBatchTex, uBatchTex2, vec2( s3mU, 0.1 ), uBatchMix );
+    if ( bState.a >= -0.5 ) {
+      vec4 bOffset = s3mSampleBatchRow1( uBatchTex, uBatchTex2, vec2( s3mU, 0.3 ), uBatchMix );
       s3mCustomOffset = bOffset.xyz;
       if ( s3mCustomOffset.z == 0.0 && bState.a > 0.0 ) {
         s3mCustomOffset.z = bState.a;
       }
+      vec4 r2 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.5 ), uBatchMix );
+      vec4 r3 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.7 ), uBatchMix );
+      vec4 r4 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.9 ), uBatchMix );
+      s3mRot = mat3(
+        vec3( r2.x, r3.x, r4.x ),
+        vec3( r2.y, r3.y, r4.y ),
+        vec3( r2.z, r3.z, r4.z )
+      );
+      s3mPivot = vec3( r2.w, r3.w, r4.w );
+    }
+  }
+  objectNormal = normalize( s3mRot * objectNormal );
+`;
+
+const VERT_ELEVATION = /* glsl */ `
+  float s3mBatchElev = s3mBatchRaw();
+  if ( uBatchTexActive > 0 && s3mBatchElev >= 0.0 ) {
+    float s3mU = ( s3mBatchElev + 0.5 ) / uBatchTexWidth;
+    vec4 bState = s3mSampleBatchRow0( uBatchTex, uBatchTex2, vec2( s3mU, 0.1 ), uBatchMix );
+    if ( bState.a < -0.5 ) {
+      transformed = vec3( 0.0 );
     }
   }
 
-  float s3mSelElev = max( step( 0.0, uSelBatch ) * step( abs( s3mBatch - uSelBatch ), 0.5 ), uSelWhole );
-  // 实例化时这是局部坐标，实例矩阵只含平移 + 绕 z 旋转（白模摆位），所以偏移仍沿局部轴生效
-  transformed += s3mCustomOffset;
+  float s3mSelElev = max( step( 0.0, uSelBatch ) * step( abs( s3mBatchElev - uSelBatch ), 0.5 ), uSelWhole );
+  // 刚体旋转以 s3mPivot 为中心，再叠加自定义平移与选中拔高
+  transformed = s3mRot * ( transformed - s3mPivot ) + s3mPivot + s3mCustomOffset;
   transformed.z += s3mSelElev * uSelElevation;
 `;
 
@@ -293,7 +402,7 @@ const VERT_WORLD = /* glsl */ `
   #else
     mat3 s3mNormMat = mat3( modelMatrix );
   #endif
-  vWorldNormal = normalize( s3mNormMat * normal );
+  vWorldNormal = normalize( s3mNormMat * ( s3mRot * normal ) );
 `;
 
 const FRAG_PARS = /* glsl */ `
@@ -376,6 +485,8 @@ const FRAG_PARS = /* glsl */ `
   uniform float uSelEmissive;
   uniform float uDimFactor;
   uniform sampler2D uBatchTex;
+  uniform sampler2D uBatchTex2;
+  uniform float uBatchMix;
   uniform float uBatchTexWidth;
   uniform int uBatchTexActive;
   uniform float uFilterMinZ;
@@ -391,12 +502,45 @@ const FRAG_PARS = /* glsl */ `
   uniform float uSelWhole;
   uniform float uRoofThreshold;
   uniform float uTexMix;
+  uniform float uAmbientGain;
+  uniform float uOpacity;
+  uniform float uTileFade;
+  uniform float uFade;
   varying float vBatchId;
   varying vec3 vVertColor;
   varying float vWorldZ;
   varying vec3 vWorldNormal;
   varying vec3 vWorldPos;
 
+  vec4 s3mSampleBatchRow0( sampler2D texA, sampler2D texB, vec2 uv, float mixVal ) {
+    vec4 vA = texture2D( texA, uv );
+    if ( mixVal <= 0.0001 ) return vA;
+    vec4 vB = texture2D( texB, uv );
+    vec4 res = mix( vA, vB, mixVal );
+    if ( vA.r < 0.0 && vB.r >= 0.0 ) {
+      res.rgb = vB.rgb;
+    } else if ( vA.r >= 0.0 && vB.r < 0.0 ) {
+      res.rgb = vA.rgb;
+    }
+    if ( vA.a < -0.5 || vB.a < -0.5 ) {
+      res.a = ( mixVal >= 0.5 ) ? vB.a : vA.a;
+    }
+    return res;
+  }
+
+  vec4 s3mSampleBatchRow1( sampler2D texA, sampler2D texB, vec2 uv, float mixVal ) {
+    vec4 vA = texture2D( texA, uv );
+    if ( mixVal <= 0.0001 ) return vA;
+    vec4 vB = texture2D( texB, uv );
+    vec4 res = mix( vA, vB, mixVal );
+    if ( vA.a == 0.0 && vB.a > 0.0 ) {
+      res.a = mix( 1.0, vB.a, mixVal );
+    } else if ( vA.a > 0.0 && vB.a == 0.0 ) {
+      res.a = mix( vA.a, 1.0, mixVal );
+    }
+    return res;
+  }
+
   float s3mHash( float p ) {
     p = fract( p * 0.1031 );
     p *= p + 33.33;
@@ -430,6 +574,8 @@ const FRAG_PARS = /* glsl */ `
 const FRAG_COLOR = /* glsl */ `
   float s3mH = clamp( ( vWorldZ - uHeightMin ) / max( uHeightMax - uHeightMin, 0.001 ), 0.0, 1.0 );
   vec3 s3mBase = diffuseColor.rgb;   // 已含 diffuse × map
+  // 图层整体透明度（共享 uniform）+ 单瓦片淡入系数（逐材质），逐帧改都不产生重编译
+  diffuseColor.a *= uOpacity * uTileFade;
   // 所有按单体取值（配色 / 状态纹理 / 选中判定）都走取整后的 id，避免插值噪声
   float s3mBid = s3mBatchId();
 
@@ -490,7 +636,8 @@ const FRAG_COLOR = /* glsl */ `
   bool hasCustomColor = false;
   if ( uBatchTexActive > 0 && s3mBid >= 0.0 ) {
     // 用取整后的 id 采样：否则逐像素的插值误差会让纹素在边界上来回跳，同样出彩色噪点
-    vec4 bState = texture2D( uBatchTex, vec2( ( s3mBid + 0.5 ) / uBatchTexWidth, 0.25 ) );
+    float s3mU = ( s3mBid + 0.5 ) / uBatchTexWidth;
+    vec4 bState = s3mSampleBatchRow0( uBatchTex, uBatchTex2, vec2( s3mU, 0.1 ), uBatchMix );
     if ( bState.a < -0.5 ) {
       discard; // 属于被过滤隐藏的单体
     }
@@ -501,7 +648,7 @@ const FRAG_COLOR = /* glsl */ `
     }
     // 单体独立透明度（状态纹理第 2 行 alpha，0 = 无覆盖）。
     // 与全局 uOpacity（diffuseColor.a 初值）和图集贴图自带 alpha 逐级叠乘
-    vec4 bOffset = texture2D( uBatchTex, vec2( ( s3mBid + 0.5 ) / uBatchTexWidth, 0.75 ) );
+    vec4 bOffset = s3mSampleBatchRow1( uBatchTex, uBatchTex2, vec2( s3mU, 0.3 ), uBatchMix );
     if ( bOffset.a > 0.0 ) {
       diffuseColor.a *= bOffset.a;
     }
@@ -531,6 +678,10 @@ const FRAG_COLOR = /* glsl */ `
   } else {
     diffuseColor.rgb *= mix( 1.0, uDimFactor, uDim );
   }
+
+  // 压暗乘子放在最后：mode 分支会整体覆写 diffuseColor.rgb，
+  // 放在前面会被覆盖掉。setMode 的 fade-through 就靠它。
+  diffuseColor.rgb *= uFade;
 `;
 
 const FRAG_EMISSIVE = /* glsl */ `
@@ -539,6 +690,10 @@ const FRAG_EMISSIVE = /* glsl */ `
   if ( uSelMode != 3 ) {
     totalEmissiveRadiance += uSelColor * s3mSelE * uSelMix * ( uSelEmissive * 0.4 );
   }
+  // 直通自发光微调 / 环境光底色提升：补偿背光阴影面（尤其 TOP_SIDE 立面），避免光照阴影面过暗
+  if ( uAmbientGain > 0.001 ) {
+    totalEmissiveRadiance += diffuseColor.rgb * uAmbientGain;
+  }
 `;
 
 const FRAG_BAKE = /* glsl */ `
@@ -594,8 +749,11 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
   // 没有单体化信息的几何（batchId = -1）只能整块选中
   const uSelWhole = { value: 0 };
   const uBatchTex = { value: DUMMY_BATCH_TEX };
+  const uBatchTex2 = { value: DUMMY_BATCH_TEX };
   const uBatchTexWidth = { value: 1.0 };
   const uBatchTexActive = { value: 0 };
+  /** 单块瓦片的淡入系数：逐材质独享（每块网格一份材质），默认 1 = 完全显示 */
+  const uTileFade = { value: 1 };
 
   // 图集材质：只有几何确实带了 aAtlasRect 才开这个宏，否则缺属性会采到 (0,0) 的默认值
   const atlas = !!opts.atlas && !!opts.map;
@@ -611,8 +769,10 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
       uSelBatch,
       uSelWhole,
       uBatchTex,
+      uBatchTex2,
       uBatchTexWidth,
       uBatchTexActive,
+      uTileFade,
       uSecMap: { value: secMap },
       uAtlasDim,
       uAtlasDim1,
@@ -620,6 +780,7 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
 
     shader.vertexShader = shader.vertexShader
       .replace('#include <common>', `#include <common>\n${VERT_PARS}`)
+      .replace('#include <beginnormal_vertex>', `#include <beginnormal_vertex>\n${VERT_SETUP}`)
       .replace('#include <begin_vertex>', `#include <begin_vertex>\n${VERT_ELEVATION}`)
       .replace('#include <worldpos_vertex>', VERT_WORLD);
 
@@ -654,8 +815,10 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
   mat.userData.uSelBatch = uSelBatch;
   mat.userData.uSelWhole = uSelWhole;
   mat.userData.uBatchTex = uBatchTex;
+  mat.userData.uBatchTex2 = uBatchTex2;
   mat.userData.uBatchTexWidth = uBatchTexWidth;
   mat.userData.uBatchTexActive = uBatchTexActive;
+  mat.userData.uTileFade = uTileFade;
   mat.userData.isStyled = true;
   return mat;
 }
@@ -669,26 +832,48 @@ const OUTLINE_VERT = /* glsl */ `
   uniform float uWidth;
   uniform float uElevation;
   uniform sampler2D uBatchTex;
+  uniform sampler2D uBatchTex2;
+  uniform float uBatchMix;
   uniform float uBatchTexWidth;
   uniform int uBatchTexActive;
   varying float vSel;
+
+  vec4 s3mSampleBatch( sampler2D texA, sampler2D texB, vec2 uv, float mixVal ) {
+    vec4 vA = texture2D( texA, uv );
+    if ( mixVal <= 0.0001 ) return vA;
+    vec4 vB = texture2D( texB, uv );
+    return mix( vA, vB, mixVal );
+  }
+
   void main() {
     vSel = max( step( 0.0, uSelBatch ) * step( abs( aBatchId - uSelBatch ), 0.5 ), uSelWhole );
     vec3 s3mCustomOffset = vec3( 0.0 );
+    mat3 s3mRot = mat3( 1.0 );
+    vec3 s3mPivot = vec3( 0.0 );
     if ( uBatchTexActive > 0 && aBatchId >= 0.0 ) {
-      vec4 bState = texture2D( uBatchTex, vec2( ( aBatchId + 0.5 ) / uBatchTexWidth, 0.25 ) );
+      float s3mU = ( aBatchId + 0.5 ) / uBatchTexWidth;
+      vec4 bState = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.1 ), uBatchMix );
       if ( bState.a < -0.5 ) {
         vSel = 0.0; // 过滤隐藏的单体不显示描边
       } else {
-        vec4 bOffset = texture2D( uBatchTex, vec2( ( aBatchId + 0.5 ) / uBatchTexWidth, 0.75 ) );
+        vec4 bOffset = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.3 ), uBatchMix );
         s3mCustomOffset = bOffset.xyz;
         if ( s3mCustomOffset.z == 0.0 && bState.a > 0.0 ) {
           s3mCustomOffset.z = bState.a;
         }
+        vec4 r2 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.5 ), uBatchMix );
+        vec4 r3 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.7 ), uBatchMix );
+        vec4 r4 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.9 ), uBatchMix );
+        s3mRot = mat3(
+          vec3( r2.x, r3.x, r4.x ),
+          vec3( r2.y, r3.y, r4.y ),
+          vec3( r2.z, r3.z, r4.z )
+        );
+        s3mPivot = vec3( r2.w, r3.w, r4.w );
       }
     }
-    vec3 p = position + normal * uWidth * vSel;
-    p += s3mCustomOffset;
+    vec3 p = position + ( s3mRot * normal ) * uWidth * vSel;
+    p = s3mRot * ( p - s3mPivot ) + s3mPivot + s3mCustomOffset;
     p.z += vSel * uElevation;
     gl_Position = projectionMatrix * modelViewMatrix * vec4( p, 1.0 );
   }
@@ -710,6 +895,8 @@ export interface OutlineMaterial extends THREE.ShaderMaterial {
     uWidth: { value: number };
     uElevation: { value: number };
     uBatchTex: { value: THREE.Texture };
+    uBatchTex2: { value: THREE.Texture };
+    uBatchMix: { value: number };
     uBatchTexWidth: { value: number };
     uBatchTexActive: { value: number };
     uColor: { value: THREE.Color };
@@ -725,6 +912,8 @@ export function createOutlineMaterial(shared: StyleUniforms, initialWidth = 0.9)
       uWidth: { value: initialWidth },
       uElevation: { value: 0 },
       uBatchTex: { value: DUMMY_BATCH_TEX },
+      uBatchTex2: { value: DUMMY_BATCH_TEX },
+      uBatchMix: shared.uBatchMix ?? { value: 0 },
       uBatchTexWidth: { value: 1.0 },
       uBatchTexActive: { value: 0 },
       uColor: { value: shared.uSelColor.value.clone() },

package/src/tileset/S3MTileset.ts

@@ -1178,7 +1178,9 @@ export class S3MTileset {
       if (inRange) node.lastSeen = this._frame;
 
       const childUrls = node.childUrls ?? (node.childUrl ? [node.childUrl] : []);
-      const needRefine = childUrls.length > 0 && (byDistance ? metric < threshold : metric > threshold);
+      // 加入 8% 迟滞区间（Hysteresis Band），防止相机在 LOD 临界距离处发生父子瓦片逐帧来回横跳闪烁
+      const hFactor = node.needRefine ? (byDistance ? 1.08 : 0.92) : 1.0;
+      const needRefine = childUrls.length > 0 && (byDistance ? metric < threshold * hFactor : metric > threshold * hFactor);
       node.needRefine = needRefine;
 
       const dbgSeen = ((globalThis as { __S3M_LOD_SEEN?: Set<string> }).__S3M_LOD_SEEN ??= new Set<string>());