@navaramap/three 0.0.1 → 0.0.2

package/src/mesh/sprite/instancedSprite.ts

@@ -10,14 +10,22 @@ import {
   Object3D,
   ShaderMaterial,
   BufferAttribute,
+  type BufferGeometry,
   Color,
+  type Material,
   PerspectiveCamera,
   Vector2,
 } from "three";
 import invariant from "tiny-invariant";
 
+import {
+  DECLUTTER_FADE_MS,
+  type DeclutterCandidate,
+  type DeclutterParticipant,
+} from "../../declutter/types";
 import type { EventContext } from "../../event/context";
 import { createInstancedSpriteMaterialEnhancer } from "../../material/enhancer";
+import type { CustomObject3DEventMap } from "../../object3DEvent";
 import { PickableMesh } from "../pickableMesh";
 
 import { BillboardAtlas, type AtlasRect } from "./billboardAtlas";
@@ -46,7 +54,10 @@ type PositionsInfo = {
 const _tmpSize = new Vector2();
 
 // Coupled with crates/navara_feature/src/geometry/point.rs::pixel_to_world
-export class InstancedSpriteMesh extends Mesh implements PickableMesh {
+export class InstancedSpriteMesh
+  extends Mesh<BufferGeometry, Material | Material[], CustomObject3DEventMap>
+  implements PickableMesh, DeclutterParticipant
+{
   private _batchIdToInstance = new Map<number, number>();
   private _initialColor: Color = new Color(0xffffff);
   private _initialHeight = 0.0;
@@ -72,15 +83,182 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
   private _enhancedMaterial?: ReturnType<
     typeof createInstancedSpriteMaterialEnhancer
   >;
+  /** Per-instance world anchors in ECEF meters (f64, 3 per instance), kept in
+   *  sync with the position attributes for the declutter pass. */
+  private _anchors: Float64Array | null = null;
+  /** Whether this mesh's instances participate in screen-space decluttering. */
+  private _declutter = false;
+  /** Layer-level placement priority from the material. */
+  private _declutterPriority = 0;
+  /** Per-instance priorities set through the evaluator (NaN = no override,
+   *  fall back to the layer value). Lazily allocated on first use. */
+  private _declutterPriorityOverrides: Float32Array | null = null;
+  /** Per-instance fade targets for `instanceDeclutterHide` (0 = shown,
+   *  1 = hidden); the attribute animates toward these in stepDeclutterFade. */
+  private _declutterTargets: Float32Array | null = null;
+  /** True while any instance's hide factor may differ from its target. */
+  private _declutterAnimating = false;
+
   constructor(options: InstancedSpriteOptions) {
     super();
     this.renderOrder = options.renderOrder ?? this.renderOrder;
     this.ctx = options.ctx;
+    this.ctx.declutter?.register(this);
+    // `processObjectRemoved` dispatches this for every removed mesh; it is the
+    // reliable teardown signal (this class's dispose() is not called there).
+    this.addEventListener("removedFromWorld", () => {
+      this.ctx.declutter?.unregister(this);
+    });
   }
 
   setActive(active: boolean) {
     this._active = active;
     this.updateVisibility();
+    this.ctx.declutter?.markDirty();
+  }
+
+  // --- DeclutterParticipant ---
+
+  collectDeclutterCandidates(out: DeclutterCandidate[]): void {
+    if (!this.visible || !this._declutter || !this._anchors) return;
+    const enhancer = this._enhancedMaterial;
+    const params = this.geometry?.getAttribute("instanceParams") as
+      InstancedBufferAttribute | undefined;
+    if (!enhancer || !params) return;
+
+    const state = enhancer.states();
+    const cx = Math.min(Math.max(state.center[0], -0.5), 0.5);
+    const cy = Math.min(Math.max(state.center[1], -0.5), 0.5);
+    // Mirror of instancedSprite.vert.glsl:100-104 — aspect is per-instance
+    // (from the atlas rect), not a material-level uniform; there is no
+    // material-wide "aspect" state to read.
+    const uvRect = state.billboard
+      ? (this.geometry?.getAttribute("instanceUvRect") as
+          InstancedBufferAttribute | undefined)
+      : undefined;
+    const anchors = this._anchors;
+    const overrides = this._declutterPriorityOverrides;
+    const targets = this._declutterTargets;
+    const count = Math.min(params.count, anchors.length / 3);
+
+    for (let i = 0; i < count; i++) {
+      if (params.getZ(i) <= 0.5) continue; // hidden by user `show`
+      const instanceSize = params.getY(i);
+      const size = instanceSize >= 0.0 ? instanceSize : state.scale;
+      if (size <= 0.0) continue;
+
+      const override = overrides ? overrides[i] : Number.NaN;
+      const rectH = uvRect ? uvRect.getW(i) : 0;
+      const aspect = uvRect && rectH > 0.0 ? uvRect.getZ(i) / rectH : 1.0;
+
+      // Mirror of instancedSprite.vert.glsl:95-97 — the quad spans
+      // (position.xy - center) * vec2(aspect, 1) * size around the anchor.
+      out.push({
+        anchorX: anchors[i * 3],
+        anchorY: anchors[i * 3 + 1],
+        anchorZ: anchors[i * 3 + 2],
+        addHeight: params.getX(i),
+        minX: (-0.5 - cx) * aspect * size,
+        maxX: (0.5 - cx) * aspect * size,
+        minY: (-0.5 - cy) * size,
+        maxY: (0.5 - cy) * size,
+        sizeInMeters: state.sizeInMeters,
+        // NaN-safe: an unset override falls back to the layer priority.
+        priority: Number.isNaN(override) ? this._declutterPriority : override,
+        isShown: targets ? targets[i] === 0 : true,
+        owner: this,
+        handle: i,
+      });
+    }
+  }
+
+  applyDeclutter(handle: number, hidden: boolean): void {
+    this.setDeclutterHiddenByInstance(handle, hidden);
+  }
+
+  stepDeclutterFade(deltaMs: number): boolean {
+    if (!this._declutterAnimating) return false;
+    const attr = this.geometry?.getAttribute("instanceDeclutterHide") as
+      InstancedBufferAttribute | undefined;
+    const targets = this._declutterTargets;
+    if (!attr || !targets) {
+      this._declutterAnimating = false;
+      return false;
+    }
+
+    const step = deltaMs / DECLUTTER_FADE_MS;
+    const count = Math.min(attr.count, targets.length);
+    let stillAnimating = false;
+    let changed = false;
+    for (let i = 0; i < count; i++) {
+      let value = attr.getX(i);
+      const target = targets[i];
+      if (value === target) continue;
+      value =
+        value < target
+          ? Math.min(value + step, target)
+          : Math.max(value - step, target);
+      attr.setX(i, value);
+      changed = true;
+      if (value !== target) stillAnimating = true;
+    }
+    if (changed) attr.needsUpdate = true;
+    this._declutterAnimating = stillAnimating;
+    return stillAnimating;
+  }
+
+  private _cacheDeclutterState(m: NavaraPointMesh | NavaraBillboardMesh) {
+    const nextDeclutter = m.material.declutter ?? true;
+    if (this._declutter && !nextDeclutter) {
+      // Leaving declutter mode: clear hides the pass applied — the mesh stops
+      // producing candidates, so nothing else would ever re-show them.
+      this._clearDeclutterHidden();
+    }
+    this._declutter = nextDeclutter;
+    this._declutterPriority = m.material.declutterPriority ?? 0;
+  }
+
+  private _clearDeclutterHidden(): void {
+    const targets = this._declutterTargets;
+    if (!targets) return;
+    targets.fill(0.0);
+    // Everything fades back in from wherever its hide factor currently is.
+    this._declutterAnimating = true;
+  }
+
+  /** Reconstruct absolute ECEF anchors from the same arrays the position
+   *  attributes receive (RTE high+low split, or RTC-relative + center). */
+  private _cacheAnchors(
+    positionsInfo: PositionsInfo,
+    transform: { tx: number; ty: number; tz: number },
+  ): void {
+    const { nPositions, positionSize, RTE } = positionsInfo;
+    const anchors =
+      this._anchors && this._anchors.length === nPositions * 3
+        ? this._anchors
+        : new Float64Array(nPositions * 3);
+
+    if (RTE) {
+      const pos = positionsInfo.position as {
+        high: Float32Array<ArrayBufferLike>;
+        low: Float32Array<ArrayBufferLike>;
+      };
+      for (let i = 0; i < nPositions; i++) {
+        const s = i * positionSize;
+        anchors[i * 3] = pos.high[s] + pos.low[s];
+        anchors[i * 3 + 1] = pos.high[s + 1] + pos.low[s + 1];
+        anchors[i * 3 + 2] = (pos.high[s + 2] ?? 0.0) + (pos.low[s + 2] ?? 0.0);
+      }
+    } else {
+      const pos = positionsInfo.position as Float32Array<ArrayBufferLike>;
+      for (let i = 0; i < nPositions; i++) {
+        const s = i * positionSize;
+        anchors[i * 3] = pos[s] + transform.tx;
+        anchors[i * 3 + 1] = pos[s + 1] + transform.ty;
+        anchors[i * 3 + 2] = (pos[s + 2] ?? 0.0) + transform.tz;
+      }
+    }
+    this._anchors = anchors;
   }
 
   async _init(m: NavaraPointMesh | NavaraBillboardMesh) {
@@ -90,6 +268,9 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
       return;
     }
 
+    this._cacheDeclutterState(m);
+    this._cacheAnchors(positionsInfo, m.transform);
+
     // Create Geometry
     this.geometry = this._initGeometry(positionsInfo, m);
 
@@ -97,12 +278,15 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
     this.material = await this._initMaterial(positionsInfo, m);
 
     this.frustumCulled = false; // Disable since bounding box doesn't account for instance positions
+    this.ctx.declutter?.markDirty();
   }
 
   async _update(m: NavaraPointMesh | NavaraBillboardMesh) {
     const enhancer = this.getEnhancer();
     const material = this.material as ShaderMaterial;
 
+    this._cacheDeclutterState(m);
+
     if (material.visible !== m.material.show) {
       material.visible = m.material.show ?? true;
       this.updateVisibility();
@@ -162,6 +346,7 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
       const positionsInfo = this.extractPositions(m);
 
       if (positionsInfo) {
+        this._cacheAnchors(positionsInfo, m.transform);
         if (positionsInfo.RTE) {
           const pos = positionsInfo.position as {
             high: Float32Array<ArrayBufferLike>;
@@ -198,6 +383,8 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
         await this._setDefaultImage(m.material.url);
       }
     }
+
+    this.ctx.declutter?.markDirty();
   }
 
   private _initGeometry(
@@ -307,6 +494,16 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
       "instanceColor",
       new InstancedBufferAttribute(colorBuffer, 3),
     );
+    // Declutter hide factors (0 = shown … 1 = hidden). Decluttered instances
+    // start hidden and fade in once the placement pass grants them space, so
+    // dense tiles don't flash their full clutter before the first pass runs.
+    const initialHide = this._declutter ? 1.0 : 0.0;
+    const declutterBuffer = new Float32Array(instanceCount).fill(initialHide);
+    this._declutterTargets = new Float32Array(instanceCount).fill(initialHide);
+    instancedGeometry.setAttribute(
+      "instanceDeclutterHide",
+      new InstancedBufferAttribute(declutterBuffer, 1),
+    );
     instancedGeometry.setAttribute(
       "instanceBatchID",
       new InstancedBufferAttribute(
@@ -572,6 +769,7 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
     ) as InstancedBufferAttribute;
     paramsAttr.setZ(instanceId, rawVisible ? 1.0 : 0.0);
     paramsAttr.needsUpdate = true;
+    this.ctx.declutter?.markDirty();
   }
 
   setFeatureOpacityByBatchId(batchId: number, opacity: number) {
@@ -599,6 +797,46 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
     const sanitizedHeight = Number.isFinite(height) ? height : 0.0;
     paramsAttr.setX(instanceId, sanitizedHeight);
     paramsAttr.needsUpdate = true;
+    this.ctx.declutter?.markDirty();
+  }
+
+  /**
+   * Set one instance's declutter fade target; the attribute animates toward
+   * it in {@link stepDeclutterFade}. Deliberately separate from the `show`
+   * component of `instanceParams` so user-driven visibility and declutter
+   * results compose instead of clobbering each other.
+   */
+  setDeclutterHiddenByInstance(instanceIndex: number, hidden: boolean) {
+    const targets = this._declutterTargets;
+    if (!targets || instanceIndex < 0 || instanceIndex >= targets.length) {
+      return;
+    }
+    targets[instanceIndex] = hidden ? 1.0 : 0.0;
+    // Cheap over-approximation; stepDeclutterFade clears it when everything
+    // has reached its target.
+    this._declutterAnimating = true;
+  }
+
+  /**
+   * Set a per-feature placement priority (higher wins), overriding the
+   * layer-level `declutterPriority` for this instance. Driven by the feature
+   * evaluator.
+   */
+  setFeatureDeclutterPriorityByBatchId(batchId: number, priority: number) {
+    const instanceId = this._batchIdToInstance.get(batchId);
+    if (instanceId === undefined) return;
+
+    if (!this._declutterPriorityOverrides) {
+      const count = this._anchors ? this._anchors.length / 3 : 0;
+      if (count === 0) return;
+      this._declutterPriorityOverrides = new Float32Array(count).fill(
+        Number.NaN,
+      );
+    }
+    if (instanceId >= this._declutterPriorityOverrides.length) return;
+    if (this._declutterPriorityOverrides[instanceId] === priority) return;
+    this._declutterPriorityOverrides[instanceId] = priority;
+    this.ctx.declutter?.markDirty();
   }
 
   setFeatureSizeByBatchId(batchId: number, size: number) {
@@ -616,6 +854,7 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
       : -1.0;
     paramsAttr.setY(instanceId, sanitizedSize);
     paramsAttr.needsUpdate = true;
+    this.ctx.declutter?.markDirty();
   }
 
   /**
@@ -634,8 +873,7 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
     if (instanceId === undefined) return;
 
     const rectAttr = this.geometry.getAttribute("instanceUvRect") as
-      | InstancedBufferAttribute
-      | undefined;
+      InstancedBufferAttribute | undefined;
     if (!rectAttr) return;
 
     if (url == null) {
@@ -669,6 +907,7 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
   }
 
   dispose(): void {
+    this.ctx.declutter?.unregister(this);
     this.geometry?.dispose();
 
     // The material's uTexture points at the atlas texture; the atlas owns it.
@@ -688,6 +927,9 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
 
     // Clear internal collections to release references
     this._batchIdToInstance.clear();
+    this._anchors = null;
+    this._declutterTargets = null;
+    this._declutterPriorityOverrides = null;
     this._imageOverrides.clear();
     this._requestedImageUrls.clear();
   }

package/src/orchestrators/RenderPassOrchestrator.ts

@@ -2,6 +2,8 @@ import { NamedIndexMap } from "@navaramap/core";
 import { EffectComposer, Pass as PostProcessingPass } from "postprocessing";
 import { HalfFloatType, Scene, WebGLRenderer, Group } from "three";
 
+import { estimateFixedGpuBytes } from "../utils/fixedGpuFootprint";
+
 export type RenderPassOrchestratorOptions = {
   halfFloat?: boolean;
   multisampling?: number;
@@ -34,6 +36,12 @@ export class RenderPassOrchestrator {
   };
   effectComposer: EffectComposer;
 
+  /**
+   * Invoked whenever the pass list changes (add/insert/remove/clear), so the
+   * owner can re-report the fixed GPU footprint to the memory ledger.
+   */
+  onPassesChanged?: () => void;
+
   private passMap = new NamedIndexMap<NamedPass>();
 
   constructor(renderer: WebGLRenderer, options: RenderPassOrchestratorOptions) {
@@ -60,6 +68,7 @@ export class RenderPassOrchestrator {
     const namedPass: NamedPass = { name, pass };
     this.passMap.add(namedPass);
     this.effectComposer.addPass(pass);
+    this.onPassesChanged?.();
   }
 
   /**
@@ -73,6 +82,7 @@ export class RenderPassOrchestrator {
     const namedPass: NamedPass = { name, pass };
     const targetIndex = this.passMap.insertBefore(targetName, namedPass);
     this.effectComposer.addPass(pass, targetIndex);
+    this.onPassesChanged?.();
   }
 
   /**
@@ -86,6 +96,7 @@ export class RenderPassOrchestrator {
     const namedPass: NamedPass = { name, pass };
     const targetIndex = this.passMap.insertAfter(targetName, namedPass);
     this.effectComposer.addPass(pass, targetIndex);
+    this.onPassesChanged?.();
   }
 
   /**
@@ -100,6 +111,7 @@ export class RenderPassOrchestrator {
     this.effectComposer.removePass(targetPass.pass);
     this.passMap.list = this.passMap.list.filter((p) => p.name !== name);
     this.rebuildIndexMap();
+    this.onPassesChanged?.();
   }
 
   /**
@@ -125,6 +137,19 @@ export class RenderPassOrchestrator {
     }
     this.passMap.list = [];
     this.passMap.indexMap = {};
+    this.onPassesChanged?.();
+  }
+
+  /**
+   * Estimates the resident GPU bytes of the fixed, screen-sized render-target
+   * stack (composer buffers + every target reachable from the passes), for
+   * reporting into the memory ledger's `fixed_gpu_bytes` term.
+   */
+  estimateFixedGpuBytes(): number {
+    return estimateFixedGpuBytes(
+      this.effectComposer,
+      this.passMap.list.map((p) => p.pass),
+    );
   }
 
   /**

package/src/passes/CustomRenderPass.ts

@@ -2,11 +2,13 @@ import { Globe } from "@navaramap/core";
 import { DepthCopyPass } from "postprocessing";
 import {
   Color,
+  DepthStencilFormat,
   DepthTexture,
   HalfFloatType,
   NearestFilter,
   RGBADepthPacking,
   Scene,
+  UnsignedInt248Type,
   WebGLRenderTarget,
   type PerspectiveCamera,
   type WebGLRenderer,
@@ -90,7 +92,20 @@ export class CustomRenderPass extends RenderPass {
     emissiveTexture.type = HalfFloatType;
     this.gbufferRenderTarget.textures.push(emissiveTexture);
 
+    // The gbuffer owns its depth texture instead of sharing the composer's one
+    // (postprocessing >= 6.39 no longer exposes a writable shared depth
+    // texture). Depth is propagated to the composer's input buffer explicitly
+    // by the copy pass below. Stencil is required for draped-mesh rendering.
+    const gbufferDepthTexture = new DepthTexture(
+      this.gbufferRenderTarget.width,
+      this.gbufferRenderTarget.height,
+      UnsignedInt248Type,
+    );
+    gbufferDepthTexture.format = DepthStencilFormat;
+    this.gbufferRenderTarget.depthTexture = gbufferDepthTexture;
+
     this.copyPass = new RenderTargetCopyPass(this.gbufferRenderTarget);
+    this.copyPass.setDepthTexture(gbufferDepthTexture);
 
     this.globeDepthCopyPass = new DepthCopyPass({
       depthPacking: RGBADepthPacking,
@@ -240,11 +255,12 @@ export class CustomRenderPass extends RenderPass {
     this.allDepthCopyPass.render(renderer, null, null);
   }
 
-  setDepthTexture(depthTexture: DepthTexture): void {
-    this.gbufferRenderTarget.depthTexture = depthTexture;
-    this.globeDepthCopyPass.setDepthTexture(depthTexture.clone());
-    this.copyPass.setDepthTexture(depthTexture);
-  }
+  // The composer-provided depth texture is intentionally ignored: the gbuffer
+  // owns its depth texture and depth is copied into the input buffer by the
+  // copy pass. `needsDepthTexture` stays true so the composer still attaches a
+  // depth texture to the input buffer, which `allDepthCopyPass` reads after
+  // the opaque scene has been rendered.
+  setDepthTexture(): void {}
 
   setSize(width: number, height: number) {
     this.gbufferRenderTarget.setSize(width, height);

package/src/passes/RenderTargetCopyPass.ts

@@ -1,6 +1,7 @@
 import PostProcessingCommon from "@shaders/glsl/postprocessingCommon.vert.glsl";
 import { Pass } from "postprocessing";
 import {
+  AlwaysDepth,
   NoBlending,
   ShaderMaterial,
   Texture,
@@ -10,13 +11,18 @@ import {
 
 const fragmentShader = `
 uniform sampler2D color;
+
+#ifdef COPY_DEPTH
 uniform sampler2D depth;
+#endif
 
 varying vec2 vUv;
 
 void main() {
   gl_FragColor = texture2D(color, vUv);
-  gl_FragDepth = texture2D(color, vUv).r;
+  #ifdef COPY_DEPTH
+  gl_FragDepth = texture2D(depth, vUv).r;
+  #endif
 }
 `;
 
@@ -71,8 +77,24 @@ export class RenderTargetCopyPass extends Pass {
     this._material.uniforms.color.value = texture;
   }
 
-  setDepthTexture(texture: Texture): void {
+  /**
+   * When a depth texture is set, the pass copies its depth into the target's
+   * depth buffer via gl_FragDepth. Depth test must be enabled (with AlwaysDepth)
+   * because GL discards depth writes while the depth test is disabled.
+   */
+  setDepthTexture(texture: Texture | null): void {
     this._material.uniforms.depth.value = texture;
+    const copyDepth = texture !== null;
+    if ("COPY_DEPTH" in this._material.defines === copyDepth) return;
+    if (copyDepth) {
+      this._material.defines.COPY_DEPTH = "";
+    } else {
+      delete this._material.defines.COPY_DEPTH;
+    }
+    this._material.depthWrite = copyDepth;
+    this._material.depthTest = copyDepth;
+    this._material.depthFunc = AlwaysDepth;
+    this._material.needsUpdate = true;
   }
 
   render(

package/src/test-utils/engine.ts

@@ -0,0 +1,53 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+
+import { Core, initSync } from "@navaramap/engine";
+
+import type { TileHandler } from "../event/context";
+import { createTileHandler } from "../event/tileHandler";
+
+let engineInitialized = false;
+
+/**
+ * Initialize the engine WASM once per vitest worker. The web-target module
+ * normally streams the binary over `fetch` (`initCore`), which Node cannot do
+ * for workspace files — so the bytes are read from the `@navaramap/engine`
+ * package and compiled synchronously. Repeat calls are no-ops; every test
+ * file that touches Rust-backed functions can call this without coordination.
+ */
+export function initTestEngine(): void {
+  if (engineInitialized) return;
+  const require = createRequire(import.meta.url);
+  const wasmPath = require.resolve("@navaramap/engine/navara_wasm_bg.wasm");
+  initSync({ module: readFileSync(wasmPath) });
+  engineInitialized = true;
+}
+
+let sharedCore: Core | undefined;
+
+/**
+ * Lazily created `Core` shared across a vitest worker's test files.
+ * `Core::new` only builds the Bevy app (no DOM access), so it is safe in the
+ * Node test environment. Shared deliberately: tests exercise Rust-backed
+ * queries against one engine instead of paying a per-file world setup.
+ */
+export function getTestCore(): Core {
+  initTestEngine();
+  sharedCore ??= new Core("navara-test");
+  return sharedCore;
+}
+
+/**
+ * The production {@link TileHandler} assembled over the shared test engine —
+ * tests reach the same Rust functions (e.g. `mercatorY`) the app wires through
+ * the event context, instead of stubbing them. The `Core` is created lazily on
+ * first Core-backed call, so pure-function consumers never construct it.
+ */
+export function createTestTileHandler(): TileHandler {
+  initTestEngine();
+  return createTileHandler({
+    getCore: () => getTestCore(),
+    getVectorRevision: () => 0,
+    getRasterRevision: () => 0,
+  });
+}

package/src/tileTexture/TileTextureCompositor.test.ts

@@ -2,6 +2,7 @@ import { Mesh, BoxGeometry, MeshBasicMaterial } from "three";
 import { describe, expect, it, vi } from "vitest";
 
 import { TexturizedSceneByTileCoordinates } from "../scene";
+import { createTestTileHandler } from "../test-utils/engine";
 
 import { TileTextureCompositor } from "./TileTextureCompositor";
 import type { AtlasFactory, CompositeAtlas } from "./types";
@@ -47,6 +48,7 @@ function setup() {
       typeof TileTextureCompositor
     >[0]["renderer"],
     texturizedSceneByTileCoordinates: texturizedScenes,
+    mercatorY: createTestTileHandler().mercatorY,
     atlasFactory: fakeFactory,
   });
   return { compositor, renderer, texturizedScenes };

package/src/tileTexture/TileTextureCompositor.ts

@@ -77,6 +77,10 @@ export const defaultAtlasFactory =
 export type TileTextureCompositorOptions = {
   renderer: WebGLRenderer;
   texturizedSceneByTileCoordinates: TexturizedSceneByTileCoordinates;
+  /** Rust's clamped WebMercator northing (`TileHandler.mercatorY`), handed to
+   * the core uniform mutates so the paste-side reprojection constants come
+   * from the same implementation as the Rust bake affine. */
+  mercatorY: (lat: number) => number;
   /** Atlas RT side length (defaults to 512). */
   size?: number;
   /** Test seam: replace MRT RT creation. */
@@ -142,6 +146,7 @@ export class TileTextureCompositor {
    * per-tile GPU byte cost it reports to the memory ledger. */
   readonly size: number;
   private readonly texturizedScenes: TexturizedSceneByTileCoordinates;
+  private readonly mercatorY: (lat: number) => number;
   // Single camera shared by every drape bake (vector and raster), re-framed
   // per source by `frameBakeCamera`. Ancestor fallback is resolved in Rust,
   // so no per-tile camera transform is needed.
@@ -189,6 +194,7 @@ export class TileTextureCompositor {
   constructor(opts: TileTextureCompositorOptions) {
     this.renderer = opts.renderer;
     this.texturizedScenes = opts.texturizedSceneByTileCoordinates;
+    this.mercatorY = opts.mercatorY;
     this.size = opts.size ?? 512;
     this.cache = new TileTextureCache({
       size: this.size,
@@ -560,7 +566,7 @@ export class TileTextureCompositor {
     // uniform ownership: each active enhancer attaches its own uniform refs and
     // contributes the matching GLSL, so a new expression touches only its module.
     const chain = createCompositeLayerEnhancers(features);
-    const core = createCoreUniformMutates();
+    const core = createCoreUniformMutates(this.mercatorY);
 
     const uniforms: CompositeUniformTarget = {};
     core.attachUniforms(uniforms, numTextures, placeholderTexture);