@navaramap/three 0.0.0

package/src/material/enhancer/shadowMap/shadowMapDepthEnhancer/mutates.ts

@@ -0,0 +1,8 @@
+import type { ShadowMapDepthMutates } from "./types";
+
+export const createShadowMapDepthMutates = (): ShadowMapDepthMutates => {
+  return {
+    update: () => {},
+    updateUniforms: (_uniforms) => {},
+  };
+};

package/src/material/enhancer/shadowMap/shadowMapDepthEnhancer/shader.test.ts

@@ -0,0 +1,17 @@
+import { testShaderCompatibility } from "../../test-utils/shaderCompatibility";
+
+import { SHADOW_MAP_DEPTH_SHADER_MARKERS } from "./markers";
+
+import { createShadowMapDepthEnhancer, type SupportedMaterial } from ".";
+
+testShaderCompatibility(
+  "shadowMapDepthEnhancer",
+  (material) => createShadowMapDepthEnhancer(material as SupportedMaterial),
+  [
+    {
+      name: "Default props",
+      props: {},
+    },
+  ],
+  SHADOW_MAP_DEPTH_SHADER_MARKERS,
+);

package/src/material/enhancer/shadowMap/shadowMapDepthEnhancer/shader.ts

@@ -0,0 +1,53 @@
+import ShadowMapDepthFragment from "@shaders/glsl/chunks/shadowmap_depth_fragment.glsl";
+import ShadowMapDepthParsFragment from "@shaders/glsl/chunks/shadowmap_depth_pars_fragment.glsl";
+import ShadowMapDepthParsVertex from "@shaders/glsl/chunks/shadowmap_depth_pars_vertex.glsl";
+import ShadowMapDepthVertex from "@shaders/glsl/chunks/shadowmap_depth_vertex.glsl";
+import type { WebGLProgramParametersWithUniforms } from "three";
+
+import { createReplacer } from "../../../../utils";
+
+import type { ShadowMapDepthMutates, ShadowMapDepthState } from "./types";
+
+export const transformShader = (
+  shader: WebGLProgramParametersWithUniforms,
+  _state: ShadowMapDepthState,
+  mutates: ShadowMapDepthMutates,
+): void => {
+  mutates.updateUniforms(shader.uniforms, _state);
+
+  shader.vertexShader = createReplacer(shader.vertexShader)
+    .replace(
+      "#include <common>",
+      `
+#include <common>
+#include <packing>
+${ShadowMapDepthParsVertex}
+`,
+    )
+    .replace(
+      "#include <clipping_planes_vertex>",
+      `
+#include <clipping_planes_vertex>
+${ShadowMapDepthVertex}
+`,
+    ).source;
+
+  // Transform fragment shader - add shadow map depth output
+  shader.fragmentShader = createReplacer(shader.fragmentShader)
+    .replace(
+      "#include <common>",
+      `
+#include <common>
+#include <packing>
+`,
+    )
+    .replace(
+      "void main() {",
+      `
+${ShadowMapDepthParsFragment}
+
+void main() {
+  ${ShadowMapDepthFragment}
+`,
+    ).source;
+};

package/src/material/enhancer/shadowMap/shadowMapDepthEnhancer/state.ts

@@ -0,0 +1,17 @@
+import type { ShadowMapDepthProps, ShadowMapDepthState } from "./types";
+
+export const DEFAULT_SHADOW_MAP_DEPTH_PROPS: Required<ShadowMapDepthProps> = {};
+
+export const DEFAULT_SHADOW_MAP_DEPTH_STATE: ShadowMapDepthState = {};
+
+/**
+ * Update immutable state from props.
+ * This enhancer has minimal state since it primarily holds external refs.
+ *
+ * @param _props - The props to apply (currently unused)
+ * @param currentState - The current state to use as fallback
+ */
+export const updateState = (
+  _props: ShadowMapDepthProps,
+  _currentState: ShadowMapDepthState,
+): ShadowMapDepthState => ({});

package/src/material/enhancer/shadowMap/shadowMapDepthEnhancer/types.ts

@@ -0,0 +1,26 @@
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+import type { Mutates } from "../../MaterialEnhancer";
+
+export type ShadowMapDepthProps = {};
+
+/**
+ * Immutable state for the shadow map depth enhancer.
+ * This enhancer has no internal state that changes - it just holds external refs.
+ */
+export type ShadowMapDepthState = Readonly<{}>;
+
+/**
+ * Mutable references (uniforms) for the shadow map depth enhancer.
+ * These are external refs passed via props.
+ */
+export type ShadowMapDepthRefs = {};
+
+export type ShadowMapDepthUniforms = Partial<ShadowMapDepthRefs>;
+
+/**
+ * Mutation functions for the shadow map depth enhancer.
+ */
+export type ShadowMapDepthMutates = Mutates<
+  ShadowMapDepthState,
+  ShadowMapDepthUniforms
+>;

package/src/material/enhancer/test-utils/shaderCompatibility.ts

@@ -0,0 +1,124 @@
+import type { Material, WebGLProgramParametersWithUniforms } from "three";
+import {
+  MeshBasicMaterial,
+  MeshLambertMaterial,
+  MeshPhongMaterial,
+  MeshPhysicalMaterial,
+  MeshStandardMaterial,
+  PointsMaterial,
+  ShaderLib,
+  ShaderMaterial,
+} from "three";
+import { beforeAll, describe, expect, it } from "vitest";
+
+import { overrideMaterialsForMRT } from "../../overrideMaterialsForMRT";
+import type { MaterialEnhancer, ShaderName } from "../MaterialEnhancer";
+import type { ShaderMarkers } from "../ShaderReplacer";
+
+type InferProps<E> =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  E extends MaterialEnhancer<any, infer P, any, any, any> ? P : never;
+
+const SHADER_MATERIAL_MAP: Record<ShaderName, new () => Material> = {
+  basic: MeshBasicMaterial,
+  lambert: MeshLambertMaterial,
+  phong: MeshPhongMaterial,
+  standard: MeshStandardMaterial,
+  physical: MeshPhysicalMaterial,
+  points: PointsMaterial,
+  shader: ShaderMaterial, // Custom ShaderMaterial
+};
+
+const ALL_SHADER_TYPES = Object.keys(SHADER_MATERIAL_MAP) as ShaderName[];
+
+function createMockShader(
+  shaderType: ShaderName,
+): WebGLProgramParametersWithUniforms {
+  // Custom ShaderMaterial ("shader") is not in Three.js ShaderLib
+  // ShaderLib only contains built-in materials: basic, lambert, phong, standard, physical, points
+  // For custom ShaderMaterial, we provide a minimal shader for testing enhancer transformShader()
+  if (shaderType === "shader") {
+    throw new Error(
+      "This test checks if the shader replacement works without any error. ShaderMaterial doesn't need this check.",
+    );
+  }
+
+  // For standard Three.js materials, use ShaderLib
+  const shaderDef = ShaderLib[shaderType];
+  return {
+    vertexShader: shaderDef.vertexShader,
+    fragmentShader: shaderDef.fragmentShader,
+    uniforms: { ...shaderDef.uniforms },
+    defines: {},
+  } as WebGLProgramParametersWithUniforms;
+}
+
+/**
+ * Test helper to verify that an enhancer correctly works with its declared shaders.
+ *
+ * This function creates a test suite that:
+ * 1. Tests that all declared shaders and props pairs in availableShaders work without throwing
+ * 2. Documents which shaders are intentionally unsupported
+ * 3. Verifies all markers exist in their respective transformed shaders
+ *
+ * @param enhancerName - Name of the enhancer for test description
+ * @param createEnhancer - Factory function that takes a material and returns an enhancer
+ * @param propsTests - Test cases with props that trigger different shader paths
+ * @param markers - Marker constants to verify in the transformed shaders
+ */
+export function testShaderCompatibility<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  E extends MaterialEnhancer<Material, any, any, any, ShaderName[]>,
+>(
+  enhancerName: string,
+  createEnhancer: (material: Material) => E,
+  propsTests: {
+    name: string;
+    props: InferProps<E>;
+  }[],
+  markers: ShaderMarkers,
+): void {
+  describe(`${enhancerName} - ShaderLib Compatibility`, () => {
+    beforeAll(() => {
+      overrideMaterialsForMRT();
+    });
+
+    describe("supported shaders", () => {
+      describe.each(ALL_SHADER_TYPES)(
+        "should transform %s shader without errors",
+        (shaderType) => {
+          const testMaterial = new SHADER_MATERIAL_MAP[shaderType]();
+          const testEnhancer = createEnhancer(testMaterial);
+
+          if (!testEnhancer.availableShaders.includes(shaderType)) return;
+
+          it.each(propsTests)("$name", ({ props }) => {
+            const mockShader = createMockShader(shaderType);
+
+            // Mount
+            testEnhancer.mount(props);
+            const mountShader = structuredClone(mockShader);
+            expect(() => {
+              testEnhancer.transformShader(mountShader);
+            }).not.toThrow();
+
+            // Update
+            testEnhancer.update(props);
+            const updateShader = structuredClone(mockShader);
+            expect(() => {
+              testEnhancer.transformShader(updateShader);
+            }).not.toThrow();
+
+            // Verify markers exist in transformed shaders
+            for (const markerValue of Object.values(markers.vertex)) {
+              expect(updateShader.vertexShader).toContain(markerValue);
+            }
+            for (const markerValue of Object.values(markers.fragment)) {
+              expect(updateShader.fragmentShader).toContain(markerValue);
+            }
+          });
+        },
+      );
+    });
+  });
+}

package/src/material/enhancer/tileComposite/compose.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+
+import type { CompositeFeatures } from "../../../tileTexture/types";
+
+import {
+  composeCompositeContributions,
+  compositeFeatureKey,
+  createCompositeLayerEnhancers,
+} from "./compose";
+
+const OFF: CompositeFeatures = {
+  hasHillshade: false,
+  hasWater: false,
+  hasElevationHeatmap: false,
+  hasWatermask: false,
+};
+
+const compose = (features: CompositeFeatures, numTextures: number) =>
+  composeCompositeContributions(
+    createCompositeLayerEnhancers(features),
+    numTextures,
+  );
+
+describe("compositeFeatureKey", () => {
+  it("is unique per feature combination", () => {
+    const keys = new Set<string>();
+    for (let mask = 0; mask < 16; mask++) {
+      keys.add(
+        compositeFeatureKey({
+          hasHillshade: !!(mask & 1),
+          hasElevationHeatmap: !!(mask & 2),
+          hasWater: !!(mask & 4),
+          hasWatermask: !!(mask & 8),
+        }),
+      );
+    }
+    expect(keys.size).toBe(16);
+  });
+});
+
+describe("composeCompositeContributions", () => {
+  it("emits no feature GLSL when everything is off", () => {
+    const c = compose(OFF, 2);
+    expect(c.slotUniformDecls).not.toContain("uniform");
+    expect(c.globalUniformDecls).toBe("");
+    expect(c.includes).toBe("");
+    expect(c.sampleProducer).toBeUndefined();
+    expect(c.perSlotPostSample({ k: 0, absSlot: 0, isVector: false })).toBe("");
+    expect(c.perSlotOnWinner({ k: 0, absSlot: 0, isVector: false })).toBe("");
+  });
+
+  it("orders slot uniform declarations hillshade → elevation → water", () => {
+    const c = compose(
+      {
+        hasHillshade: true,
+        hasElevationHeatmap: true,
+        hasWater: true,
+        hasWatermask: false,
+      },
+      2,
+    );
+    const hill = c.slotUniformDecls.indexOf("uIsHillshades");
+    const elev = c.slotUniformDecls.indexOf("uIsElevationHeatmaps");
+    const water = c.slotUniformDecls.indexOf("uWaters");
+    expect(hill).toBeGreaterThanOrEqual(0);
+    expect(hill).toBeLessThan(elev);
+    expect(elev).toBeLessThan(water);
+  });
+
+  it("orders the post-loop blocks hillshade before watermask", () => {
+    const c = compose({ ...OFF, hasHillshade: true, hasWatermask: true }, 1);
+    const hill = c.postLoop.indexOf("hillshadeNormal");
+    const mask = c.postLoop.indexOf("uWatermask");
+    expect(hill).toBeGreaterThanOrEqual(0);
+    expect(hill).toBeLessThan(mask);
+  });
+
+  it("only the elevation heatmap overrides the per-slot sampler", () => {
+    expect(compose(OFF, 1).sampleProducer).toBeUndefined();
+    const c = compose({ ...OFF, hasElevationHeatmap: true }, 1);
+    expect(c.sampleProducer).toBeDefined();
+    expect(c.sampleProducer?.({ k: 0, absSlot: 0, isVector: false })).toContain(
+      "sampleElevationBilinear",
+    );
+    expect(c.includes).toContain("sampleElevationBilinear");
+  });
+
+  it("writes the per-slot water flag only when water is on", () => {
+    const ctx = { k: 1, absSlot: 1, isVector: false };
+    expect(compose(OFF, 2).perSlotOnWinner(ctx)).toBe("");
+    expect(
+      compose({ ...OFF, hasWater: true }, 2).perSlotOnWinner(ctx),
+    ).toContain("isWater = uWaters[1]");
+  });
+});

package/src/material/enhancer/tileComposite/compose.ts

@@ -0,0 +1,112 @@
+import type {
+  CompositeFeatures,
+  CompositeGlobals,
+  CompositeLayer,
+} from "../../../tileTexture/types";
+
+import type { CompositeShaderContributions } from "./tileCompositeBaseEnhancer";
+import { createTileElevationHeatmapEnhancer } from "./tileElevationHeatmapEnhancer";
+import { createTileHillshadeEnhancer } from "./tileHillshadeEnhancer";
+import { createTileWaterEnhancer } from "./tileWaterEnhancer";
+import { createTileWatermaskEnhancer } from "./tileWatermaskEnhancer";
+import type { CompositeLayerEnhancer } from "./types";
+
+/**
+ * Build the ordered composite layer enhancer chain for a feature set —
+ * inactive expressions return undefined and drop out. Order is significant: it
+ * fixes how per-slot uniform declarations and post-loop blocks concatenate
+ * (hillshade, elevation, water for slot uniforms; hillshade then watermask for
+ * the post-loop). A new expression is added by writing an enhancer and slotting
+ * it in here.
+ */
+export function createCompositeLayerEnhancers(
+  features: CompositeFeatures,
+): CompositeLayerEnhancer[] {
+  return [
+    createTileHillshadeEnhancer(features.hasHillshade),
+    createTileElevationHeatmapEnhancer(features.hasElevationHeatmap),
+    createTileWaterEnhancer(features.hasWater),
+    createTileWatermaskEnhancer(features.hasWatermask),
+  ].filter((e): e is CompositeLayerEnhancer => e !== undefined);
+}
+
+/**
+ * Derive the active feature set from the planned layers and tile globals. Each
+ * per-slot expression is active iff a layer of that kind is present; watermask
+ * is a global. Driving the feature set off the active layers means the shader
+ * never declares uniforms or runs code for a flag that no compact slot uses.
+ */
+export function deriveCompositeFeatures(
+  layers: readonly CompositeLayer[],
+  globals: CompositeGlobals,
+): CompositeFeatures {
+  return {
+    hasHillshade: layers.some((l) => l.kind === "hillshade"),
+    hasElevationHeatmap: layers.some((l) => l.kind === "elevationHeatmap"),
+    hasWater: layers.some((l) => l.kind === "raster" && l.water),
+    hasWatermask: globals.watermask != null,
+  };
+}
+
+/**
+ * Material cache key for a feature set. Stringifying the whole CompositeFeatures
+ * object keeps the key unambiguous as flags are added — no hand-maintained
+ * per-flag encoding to collide.
+ */
+export function compositeFeatureKey(features: CompositeFeatures): string {
+  return JSON.stringify(features);
+}
+
+/**
+ * Fold the enhancer chain into the base enhancer's contribution bundle. Each
+ * hook is collected from every enhancer that defines it, in chain order:
+ *   - decl/include/postLoop blocks join with "\n" (an enhancer that leaves the
+ *     hook undefined simply drops out of that block),
+ *   - per-slot transforms concatenate (they target the same texColor / attr),
+ *   - sampleProducer takes the last active overrider (only the heatmap sets it).
+ */
+/** Collect the defined values of one hook across the chain, in chain order. */
+function collect<T>(
+  enhancers: readonly CompositeLayerEnhancer[],
+  pick: (e: CompositeLayerEnhancer) => T | undefined,
+): T[] {
+  const out: T[] = [];
+  for (const e of enhancers) {
+    const v = pick(e);
+    if (v !== undefined) out.push(v);
+  }
+  return out;
+}
+
+export function composeCompositeContributions(
+  enhancers: readonly CompositeLayerEnhancer[],
+  numTextures: number,
+): CompositeShaderContributions {
+  // Last active overrider wins (only the heatmap sets one).
+  const sampleProducers = collect(enhancers, (e) => e.sampleProducer);
+  const sampleProducer = sampleProducers[sampleProducers.length - 1];
+
+  return {
+    slotUniformDecls: collect(enhancers, (e) => e.slotUniformDecls)
+      .map((fn) => fn(numTextures))
+      .join("\n"),
+    globalUniformDecls: collect(enhancers, (e) => e.globalUniformDecls)
+      .map((fn) => fn())
+      .join("\n"),
+    includes: collect(enhancers, (e) => e.includes)
+      .map((fn) => fn())
+      .join("\n"),
+    sampleProducer,
+    perSlotPostSample: (ctx) =>
+      collect(enhancers, (e) => e.perSlotPostSample)
+        .map((fn) => fn(ctx))
+        .join(""),
+    perSlotOnWinner: (ctx) =>
+      collect(enhancers, (e) => e.perSlotOnWinner)
+        .map((fn) => fn(ctx))
+        .join(""),
+    postLoop: collect(enhancers, (e) => e.postLoop)
+      .map((fn) => fn(numTextures))
+      .join("\n"),
+  };
+}

package/src/material/enhancer/tileComposite/index.ts

@@ -0,0 +1,23 @@
+export {
+  buildCompositeFragmentShader,
+  compositeSlotMarker,
+  createCoreUniformMutates,
+  COMPOSITE_VERTEX_SHADER,
+} from "./tileCompositeBaseEnhancer";
+export type {
+  CompositeShaderContributions,
+  CompositeSlotContext,
+  CompositeUniformTarget,
+  CoreUniformMutates,
+} from "./tileCompositeBaseEnhancer";
+export type { CompositeLayerEnhancer } from "./types";
+export {
+  composeCompositeContributions,
+  compositeFeatureKey,
+  createCompositeLayerEnhancers,
+  deriveCompositeFeatures,
+} from "./compose";
+export { createTileHillshadeEnhancer } from "./tileHillshadeEnhancer";
+export { createTileElevationHeatmapEnhancer } from "./tileElevationHeatmapEnhancer";
+export { createTileWaterEnhancer } from "./tileWaterEnhancer";
+export { createTileWatermaskEnhancer } from "./tileWatermaskEnhancer";

package/src/material/enhancer/tileComposite/tileCompositeBaseEnhancer/index.ts

@@ -0,0 +1,11 @@
+export {
+  buildCompositeFragmentShader,
+  compositeSlotMarker,
+  COMPOSITE_VERTEX_SHADER,
+} from "./shader";
+export { createCoreUniformMutates } from "./mutates";
+export type { CompositeUniformTarget, CoreUniformMutates } from "./mutates";
+export type {
+  CompositeShaderContributions,
+  CompositeSlotContext,
+} from "./types";

package/src/material/enhancer/tileComposite/tileCompositeBaseEnhancer/mutates.ts

@@ -0,0 +1,132 @@
+import { Color, Uniform, Vector2, Vector4, type Texture } from "three";
+
+import type { CompositeLayer } from "../../../../tileTexture/types";
+
+/** Shader uniform dictionary the composite ShaderMaterial is built from. */
+export type CompositeUniformTarget = Record<string, Uniform>;
+
+const WHITE = new Color(1, 1, 1);
+
+/** atan(sinh(PI)) — the WebMercator max latitude (~85.051°). */
+const WM_MAX_LAT = Math.atan(Math.sinh(Math.PI));
+
+/**
+ * Owns the core per-slot uniforms (shows/colors/opacities/textures/uv) of the
+ * composite material. Refs live in this closure so binds mutate the same
+ * objects three.js holds. Mirrors the MaterialEnhancer mutates pattern: create
+ * + attach once, then sync per compact slot from the planned layers.
+ */
+export type CoreUniformMutates = {
+  attachUniforms: (
+    target: CompositeUniformTarget,
+    numTextures: number,
+    placeholder: Texture,
+  ) => void;
+  /** Sync slot `compactSlot` from the layer occupying it (or clear it). */
+  bindSlot: (compactSlot: number, layer: CompositeLayer | undefined) => void;
+};
+
+export function createCoreUniformMutates(): CoreUniformMutates {
+  const refs = {
+    uShows: new Uniform<number[]>([]),
+    uOpacities: new Uniform<number[]>([]),
+    uColors: new Uniform<Color[]>([]),
+    uTextures: new Uniform<Texture[]>([]),
+    uLayerUvOffset: new Uniform<Vector2[]>([]),
+    uLayerUvScale: new Uniform<Vector2[]>([]),
+    // Per-slot Mercator reprojection: uReproject[k] = 1 means sample this slot's
+    // texture using the latitude reprojection driven by uReprojectTerrainLat[k]
+    // (the terrain tile's [south, north] latitude in radians).
+    uReproject: new Uniform<number[]>([]),
+    uReprojectTerrainLat: new Uniform<Vector2[]>([]),
+    // CPU-precomputed per-slot reprojection constants consumed by the shader:
+    //   (mRs, mDen, clampTopEdge, clampBottomEdge). See bindSlot for the math.
+    uReprojectMerc: new Uniform<Vector4[]>([]),
+  };
+  let placeholderTexture: Texture | null = null;
+
+  return {
+    attachUniforms: (target, numTextures, placeholder) => {
+      placeholderTexture = placeholder;
+      refs.uShows.value = new Array<number>(numTextures).fill(0);
+      refs.uOpacities.value = new Array<number>(numTextures).fill(1);
+      refs.uColors.value = Array.from(
+        { length: numTextures },
+        () => new Color(),
+      );
+      refs.uTextures.value = new Array<Texture>(numTextures).fill(placeholder);
+      refs.uLayerUvOffset.value = Array.from(
+        { length: numTextures },
+        () => new Vector2(0, 0),
+      );
+      refs.uLayerUvScale.value = Array.from(
+        { length: numTextures },
+        () => new Vector2(1, 1),
+      );
+      refs.uReproject.value = new Array<number>(numTextures).fill(0);
+      refs.uReprojectTerrainLat.value = Array.from(
+        { length: numTextures },
+        () => new Vector2(0, 0),
+      );
+      refs.uReprojectMerc.value = Array.from(
+        { length: numTextures },
+        () => new Vector4(0, 0, 0, 0),
+      );
+      target.uShows = refs.uShows;
+      target.uOpacities = refs.uOpacities;
+      target.uColors = refs.uColors;
+      target.uTextures = refs.uTextures;
+      target.uLayerUvOffset = refs.uLayerUvOffset;
+      target.uLayerUvScale = refs.uLayerUvScale;
+      target.uReproject = refs.uReproject;
+      target.uReprojectTerrainLat = refs.uReprojectTerrainLat;
+      target.uReprojectMerc = refs.uReprojectMerc;
+    },
+
+    bindSlot: (k, layer) => {
+      refs.uShows.value[k] = layer ? 1 : 0;
+      refs.uTextures.value[k] =
+        layer?.texture ?? placeholderTexture ?? refs.uTextures.value[k];
+      // Color only matters for raster slots; hillshade is zeroed and elevation
+      // reads the colormap, so reset others to white to drop stale values.
+      if (layer && layer.kind === "raster") {
+        refs.uColors.value[k].copy(layer.color);
+      } else {
+        refs.uColors.value[k].copy(WHITE);
+      }
+      refs.uOpacities.value[k] =
+        layer && "opacity" in layer ? layer.opacity : 1;
+      if (layer) {
+        refs.uLayerUvOffset.value[k].copy(layer.uvOffset);
+        refs.uLayerUvScale.value[k].copy(layer.uvScale);
+      } else {
+        refs.uLayerUvOffset.value[k].set(0, 0);
+        refs.uLayerUvScale.value[k].set(1, 1);
+      }
+
+      const reproject =
+        layer && layer.kind === "raster" ? layer.reproject : undefined;
+      if (reproject && layer) {
+        const [Ts, Tn] = reproject;
+        // Recover the source tile's latitude band [Rs, Rn] from the affine y
+        // mapping, then its Mercator-space start (mRs) and span (mDen). These are
+        // constant per slot, so the shader reads them instead of evaluating
+        // log/tan per fragment — only the shared per-fragment mLat stays on GPU.
+        const span = (Tn - Ts) / layer.uvScale.y;
+        const Rs = Ts - layer.uvOffset.y * span;
+        const Rn = Rs + span;
+        const mRs = Math.log(Math.tan(Math.PI * 0.25 + Rs * 0.5));
+        const mRn = Math.log(Math.tan(Math.PI * 0.25 + Rn * 0.5));
+        // Polar cap: clamp the overshoot onto the band-edge texel when this tile's
+        // north/south edge sits on the WebMercator latitude limit.
+        const clampTop = Rn >= WM_MAX_LAT - 1e-4 ? 1 : 0;
+        const clampBottom = Rs <= -WM_MAX_LAT + 1e-4 ? 1 : 0;
+        refs.uReproject.value[k] = 1;
+        refs.uReprojectTerrainLat.value[k].set(Ts, Tn);
+        refs.uReprojectMerc.value[k].set(mRs, mRn - mRs, clampTop, clampBottom);
+      } else {
+        refs.uReproject.value[k] = 0;
+      }
+    },
+  };
+}