@navaramap/three 0.0.0

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

@@ -0,0 +1,245 @@
+import type {
+  CompositeShaderContributions,
+  CompositeSlotContext,
+} from "./types";
+
+/**
+ * Per-slot marker comment, used by unit tests to assert that a given compact
+ * slot maps to the expected absolute slot + region. Exported so tests build
+ * the same string the shader emits — single source of truth for the format.
+ */
+export const compositeSlotMarker = (
+  compactSlot: number,
+  absoluteSlot: number,
+  isVector: boolean,
+): string =>
+  `// ---- compact slot ${compactSlot} (absolute slot ${absoluteSlot}, ${isVector ? "vector" : "raster"}) ----`;
+
+/**
+ * True only in vitest runs (Vite sets MODE="test"). Gates injection of
+ * `compositeSlotMarker` comments into the generated shader so production
+ * builds (MODE="development" | "production" | undefined for non-Vite
+ * consumers) carry no debug comments at all.
+ */
+const EMIT_SHADER_DEBUG_COMMENTS = import.meta.env?.MODE === "test";
+
+const emitSlotMarker = (
+  compactSlot: number,
+  absoluteSlot: number,
+  isVector: boolean,
+): string =>
+  EMIT_SHADER_DEBUG_COMMENTS
+    ? `  ${compositeSlotMarker(compactSlot, absoluteSlot, isVector)}`
+    : "";
+
+/**
+ * Default raster sampler: a straight texture fetch tinted by the per-slot color.
+ * Composite layer enhancers can override this via
+ * `CompositeShaderContributions.sampleProducer` (e.g. the elevation heatmap).
+ */
+const defaultRasterSampleProducer = ({ k }: CompositeSlotContext): string => `
+    vec4 texColor${k} = texture2D(uTextures[${k}], texUv${k}) * vec4(uColors[${k}], 1.0);`;
+
+/**
+ * Build the composite-pass fragment shader skeleton, driving the per-slot loop
+ * and wiring in feature contributions from the composed layer enhancers.
+ *
+ * The base owns:
+ *   - the `main()` scaffold + the standard local accumulators,
+ *   - the core per-slot uniforms (shows/colors/opacities/textures/uv),
+ *   - the compact→absolute slot mapping (baked into `winningSlot`),
+ *   - the alpha-over blend and the MRT output writes.
+ *
+ * Everything feature-specific (hillshade, elevation heatmap, water, watermask)
+ * flows in through `contributions`, so the skeleton stays expression-agnostic.
+ *
+ * MRT outputs (WebGL2 layout(location=…)):
+ *   0: colorBuffer  — composited diffuse (RGBA)
+ *   1: attrBuffer   — packed material attrs (RGBA8):
+ *                       r = isWater, g = isTexturized, b = 0,
+ *                       a = (winSlot + 1) / 255 — 0 means no winner
+ *   2: normalBuffer — hillshade normal in [0,1]; .a = 1 when present, 0 when not.
+ */
+export function buildCompositeFragmentShader(
+  rasterCount: number,
+  vectorCount: number,
+  texturizedSceneIndexFrom: number,
+  contributions: CompositeShaderContributions,
+): string {
+  const numTextures = rasterCount + vectorCount;
+
+  // Per-slot uniform arrays are elided when numTextures === 0 — GLSL forbids
+  // zero-length arrays (`uniform int x[0];` fails to compile). Watermask-only
+  // tiles (no raster + no vector layers, but a quantized-mesh watermask) still
+  // need to run the shader so the watermask sample reaches attr.r.
+  const slotUniforms =
+    numTextures > 0
+      ? `
+uniform int uShows[${numTextures}];
+uniform vec3 uColors[${numTextures}];
+uniform float uOpacities[${numTextures}];
+uniform sampler2D uTextures[${numTextures}];
+uniform vec2 uLayerUvOffset[${numTextures}];
+uniform vec2 uLayerUvScale[${numTextures}];
+uniform int uReproject[${numTextures}];
+uniform vec2 uReprojectTerrainLat[${numTextures}];
+// CPU-precomputed per-slot reprojection constants (see mutates.ts):
+//   .xy = (mRs, mDen) — source tile's Mercator band start + span,
+//   .z  = clamp-to-top-edge flag, .w = clamp-to-bottom-edge flag (polar cap).
+uniform vec4 uReprojectMerc[${numTextures}];
+${contributions.slotUniformDecls}
+`
+      : "";
+
+  const declUniforms = `
+${slotUniforms}
+${contributions.globalUniformDecls}
+`;
+
+  const sampleProducer =
+    contributions.sampleProducer ?? defaultRasterSampleProducer;
+
+  // For each compact slot k, decide texColor and (conditionally) update winning
+  // slot index + per-winner attrs. The absolute slot index is baked in as a
+  // GLSL int constant so the TileMesh main shader's per-slot uniform arrays
+  // remain addressable by `winIdx` (= attr.a decoded). Last-writer-wins: a later
+  // slot's opaque pixel overwrites the winner recorded by earlier slots.
+  const slotBlocks = Array.from({ length: numTextures }, (_, k) => {
+    const isVector = k >= rasterCount;
+    const absSlot = isVector ? texturizedSceneIndexFrom + (k - rasterCount) : k;
+    const isTexturizedConst = isVector ? "1.0" : "0.0";
+    const ctx: CompositeSlotContext = { k, absSlot, isVector };
+
+    // WebMercator-on-Geographic latitude reprojection. Applies to both raster
+    // (imagery) slots and baked-vector slots: a vector layer's render target is
+    // baked spanning the terrain tile's WebMercator extent, so the paste remaps
+    // the latitude axis the same way (identity when the slot doesn't reproject,
+    // i.e. WebMercator terrain, where uReproject[k] == 0 makes this a no-op).
+    //
+    // Reprojection (and therefore N:M sub-rect confinement) is the only path that
+    // can drive texUv outside [0,1], so both the transcendental math and the
+    // `inBounds` test live behind the `uReproject` branch — non-reprojecting slots
+    // keep texUv in [0,1] by construction and pay neither cost.
+    const reprojectBlock = `
+    if (uReproject[${k}] == 1) {
+      // Affine UV is correct in longitude but stretches latitude. Remap this
+      // fragment's latitude through Mercator so it samples the source correctly.
+      //
+      // The only per-fragment transcendental left is mLat: it depends solely on
+      // vUv.y and the (tile-wide, slot-invariant) terrain lat range, so it is
+      // identical for every reprojecting slot — computed once and reused. The
+      // per-slot source band (mRs, mDen) and polar-cap flags are constant per slot
+      // and precomputed on the CPU (see mutates.ts), so no log/tan runs per slot.
+      if (!gReprojMLatReady) {
+        float lat = uReprojectTerrainLat[${k}].x
+          + vUv.y * (uReprojectTerrainLat[${k}].y - uReprojectTerrainLat[${k}].x);
+        gReprojMLat = log(tan(PI * 0.25 + lat * 0.5));
+        gReprojMLatReady = true;
+      }
+      float mRs = uReprojectMerc[${k}].x;
+      float mDen = uReprojectMerc[${k}].y;
+      // Only reproject when the source's Mercator span is wide enough to be
+      // numerically safe. For deep/upsampled tiles the span shrinks to ~1e-6 while
+      // mLat/mRs are ~O(1), so (mLat-mRs)/(mRn-mRs) catastrophically cancels in
+      // float32 and produces vertical-stretch noise. There the Mercator correction
+      // is sub-pixel anyway, so the affine texUv.y is both correct and stable.
+      if (abs(mDen) > 1e-3) {
+        texUv${k}.y = (gReprojMLat - mRs) / mDen;
+      }
+      // Polar cap fill: WebMercator content stops at ±~85.05° but Geographic
+      // terrain reaches ±90°. When this slot is the band-edge source (its
+      // north/south edge sits on the WM limit), clamp the polar overshoot onto
+      // that edge texel so the last available source row stretches across the cap
+      // instead of being dropped by the in-bounds test below. Non-edge tiles keep
+      // the normal drop.
+      if (uReprojectMerc[${k}].z > 0.5) texUv${k}.y = min(texUv${k}.y, 1.0);
+      if (uReprojectMerc[${k}].w > 0.5) texUv${k}.y = max(texUv${k}.y, 0.0);
+      // Confine the slot to the sub-rect it actually covers. With N:M draping each
+      // source tile covers only part of the terrain tile; outside its [0,1] range
+      // the sampler would smear the edge texel across the rest, so drop it there.
+      inBounds${k} = step(0.0, texUv${k}.x) * step(texUv${k}.x, 1.0)
+                   * step(0.0, texUv${k}.y) * step(texUv${k}.y, 1.0);
+    }`;
+
+    return `
+${emitSlotMarker(k, absSlot, isVector)}
+  if (uShows[${k}] == 1) {
+    vec2 texUv${k} = vUv * uLayerUvScale[${k}] + uLayerUvOffset[${k}];
+    // 1.0 unless the reproject branch below confines this slot to a sub-rect.
+    float inBounds${k} = 1.0;
+${reprojectBlock}
+${sampleProducer(ctx)}
+${contributions.perSlotPostSample(ctx)}
+    float alpha${k} = texColor${k}.a * uOpacities[${k}] * inBounds${k};
+    if (alpha${k} > 0.01) {
+      compositedColor = mix(compositedColor, vec4(texColor${k}.rgb, 1.0), alpha${k});
+      winningSlot = ${absSlot};
+      isTexturized = ${isTexturizedConst};
+${contributions.perSlotOnWinner(ctx)}
+    }
+  }`;
+  }).join("\n");
+
+  return `
+precision highp float;
+precision highp int;
+
+#include <common>
+
+varying vec2 vUv;
+
+${declUniforms}
+
+${contributions.includes}
+
+layout(location = 0) out vec4 colorBuffer;
+layout(location = 1) out vec4 attrBuffer;
+layout(location = 2) out vec4 normalBuffer;
+
+void main() {
+  vec4 compositedColor = vec4(0.0);
+  int winningSlot = -1;
+  float isWater = 0.0;
+  float isTexturized = 0.0;
+
+  vec3 hillshadeNormal = vec3(0.5, 0.5, 1.0); // neutral upward
+  bool hasHillshadeNormal = false;
+
+  // Shared WebMercator reprojection latitude for this fragment. The terrain lat
+  // range is tile-wide, so mLat is identical across every reprojecting slot —
+  // computed lazily on first use and reused by the rest (see reproject block).
+  float gReprojMLat = 0.0;
+  bool gReprojMLatReady = false;
+
+${slotBlocks}
+
+${contributions.postLoop}
+
+  colorBuffer = compositedColor;
+
+  // Attr.a packs the winning slot index as (idx+1)/255 — 0 means no winner.
+  // Main shader: int winIdx = int(round(attr.a * 255.0)) - 1.
+  attrBuffer = vec4(
+    isWater,
+    isTexturized,
+    0.0,
+    float(winningSlot + 1) / 255.0
+  );
+
+  normalBuffer = vec4(hillshadeNormal, hasHillshadeNormal ? 1.0 : 0.0);
+}
+`;
+}
+
+/**
+ * Vertex shader for the composite fullscreen quad. `position` and `uv` are
+ * auto-injected by three.js for ShaderMaterial — declaring them here causes
+ * a redefinition error under glslVersion: GLSL3.
+ */
+export const COMPOSITE_VERTEX_SHADER = `
+varying vec2 vUv;
+void main() {
+  vUv = uv;
+  gl_Position = vec4(position, 1.0);
+}
+`;

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

@@ -0,0 +1,43 @@
+/**
+ * Per-compact-slot context handed to the shader-contribution hooks while the
+ * base enhancer unrolls the composite slot loop.
+ */
+export type CompositeSlotContext = {
+  /** Compact slot index `[0, rasterCount + vectorCount)`. */
+  k: number;
+  /** Absolute slot index baked into `winningSlot` for the main shader. */
+  absSlot: number;
+  /** True when the slot lives in the vector region (≥ rasterCount). */
+  isVector: boolean;
+};
+
+/**
+ * GLSL contributions assembled by the composite layer enhancers and consumed by
+ * the base enhancer's skeleton builder. The base owns the `main()` scaffold, the
+ * MRT outputs, the core uniforms, and the per-slot loop driver; everything
+ * feature-specific arrives through these hooks so a new expression is a new
+ * enhancer rather than an edit threaded across the generator.
+ */
+export type CompositeShaderContributions = {
+  /**
+   * Feature per-slot uniform declarations (sized at numTextures). Joined by the
+   * base inside the `numTextures > 0` guard alongside the core uniforms.
+   */
+  slotUniformDecls: string;
+  /** Slot-independent uniform declarations (e.g. the watermask sampler). */
+  globalUniformDecls: string;
+  /** GLSL chunks inlined before `main()` (e.g. the elevation decoder). */
+  includes: string;
+  /**
+   * Produces `vec4 texColor${k} = …;` for a slot. Mutually exclusive — the most
+   * specific contributor wins (elevation heatmap overrides the raster default).
+   * Omitted → the base's default raster sampler is used.
+   */
+  sampleProducer?: (ctx: CompositeSlotContext) => string;
+  /** Additive transform applied to `texColor${k}` after sampling (hillshade). */
+  perSlotPostSample: (ctx: CompositeSlotContext) => string;
+  /** Additive attr update when a slot wins the alpha-over blend (water). */
+  perSlotOnWinner: (ctx: CompositeSlotContext) => string;
+  /** GLSL injected after the slot loop (hillshade normal pass, watermask). */
+  postLoop: string;
+};

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

@@ -0,0 +1,29 @@
+import type { CompositeLayerEnhancer } from "../types";
+
+import { createElevationMutates } from "./mutates";
+import {
+  elevationIncludes,
+  elevationSampleProducer,
+  elevationSlotUniformDecls,
+} from "./shader";
+
+/**
+ * Elevation heatmap layers decode a DEM raster to a height and colorize it
+ * through the shared 1-D colormap. The decoder uniforms and colormap sampler
+ * are slot-independent; the decoder chunk is inlined via `includes`.
+ */
+export function createTileElevationHeatmapEnhancer(
+  active: boolean,
+): CompositeLayerEnhancer | undefined {
+  if (!active) return undefined;
+  const mutates = createElevationMutates();
+  return {
+    defines: { USE_ELEVATION_HEATMAP: 1 },
+    slotUniformDecls: elevationSlotUniformDecls,
+    includes: elevationIncludes,
+    sampleProducer: elevationSampleProducer,
+    attachUniforms: mutates.attachUniforms,
+    bindSlot: mutates.bindSlot,
+    bindGlobal: mutates.bindGlobal,
+  };
+}

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

@@ -0,0 +1,68 @@
+import { Uniform, Vector3, Vector4, type Texture } from "three";
+
+import type {
+  CompositeGlobals,
+  CompositeLayer,
+} from "../../../../tileTexture/types";
+import type { CompositeUniformTarget } from "../tileCompositeBaseEnhancer";
+
+export type ElevationMutates = {
+  attachUniforms: (
+    target: CompositeUniformTarget,
+    numTextures: number,
+    placeholder: Texture,
+  ) => void;
+  bindSlot: (compactSlot: number, layer: CompositeLayer | undefined) => void;
+  bindGlobal: (globals: CompositeGlobals) => void;
+};
+
+/**
+ * Owns the elevation heatmap per-slot flag array plus the slot-independent
+ * colormap sampler and DEM decoder params.
+ */
+export function createElevationMutates(): ElevationMutates {
+  const refs = {
+    uIsElevationHeatmaps: new Uniform<boolean[]>([]),
+    uColorMapTexture: new Uniform<Texture | null>(null),
+    uElevationRGBScaler: new Uniform(new Vector3()),
+    uElevationMinMaxHeightAndBoundary: new Uniform(new Vector3()),
+    uElevationMinMaxOffsetAndEpsilonAndOffset: new Uniform(new Vector4()),
+    uLogarithmic: new Uniform(false),
+    uLogBase: new Uniform(10),
+    uLogBoundary: new Uniform(10),
+  };
+  return {
+    attachUniforms: (target, numTextures, placeholder) => {
+      refs.uIsElevationHeatmaps.value = new Array<boolean>(numTextures).fill(
+        false,
+      );
+      refs.uColorMapTexture.value = placeholder;
+      target.uIsElevationHeatmaps = refs.uIsElevationHeatmaps;
+      target.uColorMapTexture = refs.uColorMapTexture;
+      target.uElevationRGBScaler = refs.uElevationRGBScaler;
+      target.uElevationMinMaxHeightAndBoundary =
+        refs.uElevationMinMaxHeightAndBoundary;
+      target.uElevationMinMaxOffsetAndEpsilonAndOffset =
+        refs.uElevationMinMaxOffsetAndEpsilonAndOffset;
+      target.uLogarithmic = refs.uLogarithmic;
+      target.uLogBase = refs.uLogBase;
+      target.uLogBoundary = refs.uLogBoundary;
+    },
+    bindSlot: (k, layer) => {
+      refs.uIsElevationHeatmaps.value[k] = layer?.kind === "elevationHeatmap";
+    },
+    bindGlobal: (globals) => {
+      refs.uColorMapTexture.value = globals.colorMapTexture;
+      refs.uElevationRGBScaler.value.copy(globals.elevationRGBScaler);
+      refs.uElevationMinMaxHeightAndBoundary.value.copy(
+        globals.elevationMinMaxHeightAndBoundary,
+      );
+      refs.uElevationMinMaxOffsetAndEpsilonAndOffset.value.copy(
+        globals.elevationMinMaxOffsetAndEpsilonAndOffset,
+      );
+      refs.uLogarithmic.value = globals.logarithmic;
+      refs.uLogBase.value = globals.logBase;
+      refs.uLogBoundary.value = globals.logBoundary;
+    },
+  };
+}

package/src/material/enhancer/tileComposite/tileElevationHeatmapEnhancer/shader.ts

@@ -0,0 +1,24 @@
+import ElevationParsFragment from "@shaders/glsl/chunks/elevation_pars_fragment.glsl";
+
+import type { CompositeSlotContext } from "../tileCompositeBaseEnhancer";
+
+export const elevationSlotUniformDecls = (numTextures: number): string =>
+  `uniform bool uIsElevationHeatmaps[${numTextures}];`;
+
+export const elevationIncludes = (): string => ElevationParsFragment;
+
+/**
+ * Replaces the per-slot sampler with a DEM-decode + colormap lookup; non-heatmap
+ * slots fall back to the straight raster fetch in the else branch.
+ */
+export const elevationSampleProducer = ({
+  k,
+}: CompositeSlotContext): string => `
+    vec4 texColor${k};
+    if (uIsElevationHeatmaps[${k}]) {
+      ivec2 demTexSize = textureSize(uTextures[${k}], 0);
+      float normalized_h = sampleElevationBilinear(uTextures[${k}], texUv${k}, demTexSize);
+      texColor${k} = vec4(texture2D(uColorMapTexture, vec2(normalized_h, 0.5)).rgb, 1.0);
+    } else {
+      texColor${k} = texture2D(uTextures[${k}], texUv${k}) * vec4(uColors[${k}], 1.0);
+    }`;

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

@@ -0,0 +1,29 @@
+import type { CompositeLayerEnhancer } from "../types";
+
+import { createHillshadeMutates } from "./mutates";
+import {
+  hillshadePerSlotPostSample,
+  hillshadePostLoop,
+  hillshadeSlotUniformDecls,
+} from "./shader";
+
+/**
+ * Hillshade layers carry a DEM-derived normal map. They contribute no color to
+ * the composite (their slot color is zeroed) but write a tangent-space normal
+ * into the atlas's normal attachment, which the TileMesh main shader rotates
+ * via its TBN.
+ */
+export function createTileHillshadeEnhancer(
+  active: boolean,
+): CompositeLayerEnhancer | undefined {
+  if (!active) return undefined;
+  const mutates = createHillshadeMutates();
+  return {
+    slotUniformDecls: hillshadeSlotUniformDecls,
+    perSlotPostSample: hillshadePerSlotPostSample,
+    postLoop: hillshadePostLoop,
+    attachUniforms: mutates.attachUniforms,
+    bindSlot: mutates.bindSlot,
+    bindGlobal: mutates.bindGlobal,
+  };
+}

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

@@ -0,0 +1,34 @@
+import { Uniform } from "three";
+
+import type {
+  CompositeGlobals,
+  CompositeLayer,
+} from "../../../../tileTexture/types";
+import type { CompositeUniformTarget } from "../tileCompositeBaseEnhancer";
+
+export type HillshadeMutates = {
+  attachUniforms: (target: CompositeUniformTarget, numTextures: number) => void;
+  bindSlot: (compactSlot: number, layer: CompositeLayer | undefined) => void;
+  bindGlobal: (globals: CompositeGlobals) => void;
+};
+
+/** Owns the hillshade per-slot flag array + shared exaggeration uniform. */
+export function createHillshadeMutates(): HillshadeMutates {
+  const refs = {
+    uIsHillshades: new Uniform<boolean[]>([]),
+    uHillshadeExaggeration: new Uniform(1.0),
+  };
+  return {
+    attachUniforms: (target, numTextures) => {
+      refs.uIsHillshades.value = new Array<boolean>(numTextures).fill(false);
+      target.uIsHillshades = refs.uIsHillshades;
+      target.uHillshadeExaggeration = refs.uHillshadeExaggeration;
+    },
+    bindSlot: (k, layer) => {
+      refs.uIsHillshades.value[k] = layer?.kind === "hillshade";
+    },
+    bindGlobal: (globals) => {
+      refs.uHillshadeExaggeration.value = globals.hillshadeExaggeration;
+    },
+  };
+}

package/src/material/enhancer/tileComposite/tileHillshadeEnhancer/shader.ts

@@ -0,0 +1,36 @@
+import type { CompositeSlotContext } from "../tileCompositeBaseEnhancer";
+
+export const hillshadeSlotUniformDecls = (numTextures: number): string =>
+  `uniform bool uIsHillshades[${numTextures}];
+uniform float uHillshadeExaggeration;`;
+
+/** Hillshade slots contribute no color — their data is a normal map. */
+export const hillshadePerSlotPostSample = ({
+  k,
+}: CompositeSlotContext): string => `
+    if (uIsHillshades[${k}]) {
+      texColor${k} = vec4(0.0);
+    }`;
+
+/**
+ * After the slot loop, sample each hillshade slot's normal into the atlas's
+ * normal attachment — the last hillshade slot wins. The TileMesh main shader
+ * rotates the stored tangent-space normal via its TBN.
+ */
+export const hillshadePostLoop = (numTextures: number): string =>
+  Array.from(
+    { length: numTextures },
+    (_, k) => `
+  if (uIsHillshades[${k}]) {
+    ivec2 normalMapSize${k} = textureSize(uTextures[${k}], 0);
+    if (normalMapSize${k}.x > 1 && normalMapSize${k}.y > 1) {
+      vec2 hillshadeUv${k} = clamp(vUv * uLayerUvScale[${k}] + uLayerUvOffset[${k}], vec2(0.0), vec2(1.0));
+      vec3 n${k} = texture2D(uTextures[${k}], hillshadeUv${k}).rgb * 2.0 - 1.0;
+      n${k} = normalize(n${k});
+      n${k}.xy *= uHillshadeExaggeration;
+      n${k} = normalize(n${k});
+      hillshadeNormal = n${k} * 0.5 + 0.5; // store in [0,1]
+      hasHillshadeNormal = true;
+    }
+  }`,
+  ).join("\n");

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

@@ -0,0 +1,23 @@
+import type { CompositeLayerEnhancer } from "../types";
+
+import { createWaterMutates } from "./mutates";
+import { waterPerSlotOnWinner, waterSlotUniformDecls } from "./shader";
+
+/**
+ * Water layers flag the winning slot's pixel as water (attr.r), which the
+ * TileMesh main shader turns into a specular reflection. Precision-sensitive
+ * water params (scale, speed, …) stay in the main shader's per-slot uniform
+ * arrays — only the boolean flag is baked into the atlas here.
+ */
+export function createTileWaterEnhancer(
+  active: boolean,
+): CompositeLayerEnhancer | undefined {
+  if (!active) return undefined;
+  const mutates = createWaterMutates();
+  return {
+    slotUniformDecls: waterSlotUniformDecls,
+    perSlotOnWinner: waterPerSlotOnWinner,
+    attachUniforms: mutates.attachUniforms,
+    bindSlot: mutates.bindSlot,
+  };
+}

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

@@ -0,0 +1,23 @@
+import { Uniform } from "three";
+
+import type { CompositeLayer } from "../../../../tileTexture/types";
+import type { CompositeUniformTarget } from "../tileCompositeBaseEnhancer";
+
+export type WaterMutates = {
+  attachUniforms: (target: CompositeUniformTarget, numTextures: number) => void;
+  bindSlot: (compactSlot: number, layer: CompositeLayer | undefined) => void;
+};
+
+/** Owns the per-slot water flag array. */
+export function createWaterMutates(): WaterMutates {
+  const refs = { uWaters: new Uniform<boolean[]>([]) };
+  return {
+    attachUniforms: (target, numTextures) => {
+      refs.uWaters.value = new Array<boolean>(numTextures).fill(false);
+      target.uWaters = refs.uWaters;
+    },
+    bindSlot: (k, layer) => {
+      refs.uWaters.value[k] = layer?.kind === "raster" ? layer.water : false;
+    },
+  };
+}

package/src/material/enhancer/tileComposite/tileWaterEnhancer/shader.ts

@@ -0,0 +1,8 @@
+import type { CompositeSlotContext } from "../tileCompositeBaseEnhancer";
+
+export const waterSlotUniformDecls = (numTextures: number): string =>
+  `uniform bool uWaters[${numTextures}];`;
+
+/** Flag the winning slot's pixel as water (attr.r). */
+export const waterPerSlotOnWinner = ({ k }: CompositeSlotContext): string => `
+      isWater = uWaters[${k}] ? 1.0 : 0.0;`;

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

@@ -0,0 +1,23 @@
+import type { CompositeLayerEnhancer } from "../types";
+
+import { createWatermaskMutates } from "./mutates";
+import { watermaskGlobalUniformDecls, watermaskPostLoop } from "./shader";
+
+/**
+ * Quantized-mesh watermask: a slot-independent single-channel texture sampled
+ * once after the slot loop. Contributes a global sampler, not a per-slot
+ * uniform, so a watermask-only tile (no raster/vector layers) still bakes water
+ * into the atlas.
+ */
+export function createTileWatermaskEnhancer(
+  active: boolean,
+): CompositeLayerEnhancer | undefined {
+  if (!active) return undefined;
+  const mutates = createWatermaskMutates();
+  return {
+    globalUniformDecls: watermaskGlobalUniformDecls,
+    postLoop: watermaskPostLoop,
+    attachUniforms: mutates.attachUniforms,
+    bindGlobal: mutates.bindGlobal,
+  };
+}

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

@@ -0,0 +1,34 @@
+import { Uniform, type Texture } from "three";
+
+import type { CompositeGlobals } from "../../../../tileTexture/types";
+import type { CompositeUniformTarget } from "../tileCompositeBaseEnhancer";
+
+export type WatermaskMutates = {
+  attachUniforms: (
+    target: CompositeUniformTarget,
+    numTextures: number,
+    placeholder: Texture,
+  ) => void;
+  bindGlobal: (globals: CompositeGlobals) => void;
+};
+
+/** Owns the slot-independent watermask sampler. */
+export function createWatermaskMutates(): WatermaskMutates {
+  const refs = { uWatermask: new Uniform<Texture | null>(null) };
+  let placeholderTexture: Texture | null = null;
+  return {
+    attachUniforms: (target, _numTextures, placeholder) => {
+      // Initialised to the 1×1 placeholder (byte 0 → no water) so the sampler
+      // is valid before the first bindGlobal.
+      placeholderTexture = placeholder;
+      refs.uWatermask.value = placeholder;
+      target.uWatermask = refs.uWatermask;
+    },
+    bindGlobal: (globals) => {
+      // No watermask on this tile → fall back to the placeholder so the sampler
+      // stays valid (R=0 → step(0.5, 0)=0 → no water) and a stale texture from a
+      // prior tile on this shared material doesn't leak through.
+      refs.uWatermask.value = globals.watermask ?? placeholderTexture;
+    },
+  };
+}

package/src/material/enhancer/tileComposite/tileWatermaskEnhancer/shader.ts

@@ -0,0 +1,13 @@
+export const watermaskGlobalUniformDecls = (): string =>
+  `uniform sampler2D uWatermask;`;
+
+/**
+ * Sampled once after the slot loop and OR'd into isWater so it takes priority
+ * even when no per-slot water flag fired (e.g. open-ocean tiles with no
+ * raster/vector layers).
+ */
+export const watermaskPostLoop = (): string => `
+  // Quantized-mesh watermask: 0 = land, 255 = water (per spec). Takes priority
+  // over per-slot uWaters — even if no winning slot flagged water, watermask
+  // can still mark this pixel as water. Threshold at 0.5 (byte > 127).
+  isWater = max(isWater, step(0.5, texture(uWatermask, vUv).r));`;