@navaramap/three 0.0.4 → 0.0.5

package/src/material/enhancer/sdfText/sdfTextBaseEnhancer/mutates.ts

@@ -14,22 +14,17 @@ import type {
  * Create mutation functions for the sdfText base enhancer.
  * Refs are created internally and captured via closure.
  *
- * @param useRTE - Whether RTE positioning is enabled
+ * Every ref here is batch-wide — one material draws all of a tile-layer's
+ * labels. Per-label values are read by the shader from `uLabelData`.
+ *
  * @param rtcCenter - The RTC center position [x, y, z]
- * @param batchId - Batch ID for picking
  */
 export const createBaseMutates = (
-  useRTE: boolean,
   rtcCenter?: [number, number, number],
-  batchId?: number,
 ): SdfTextBaseMutates => {
   const refs: SdfTextBaseRefs = {
-    uColor: { value: new Color(1, 1, 1) },
-    uOpacity: { value: 1.0 },
-    uFontSize: { value: 16.0 },
     uCenter: { value: new Vector2(0.5, 0.0) },
     uSizeInMeters: { value: true },
-    uAddHeight: { value: 0.0 },
     uOffsetDepth: { value: true },
     uSdfThreshold: { value: 0.5 },
     uOutlineWidth: { value: 0.0 },
@@ -42,10 +37,6 @@ export const createBaseMutates = (
     uFovRad: { value: 1.0 },
     uScreenHeightPx: { value: 1080.0 },
     uFarPlane: { value: 1000.0 },
-    uTextWidth: { value: 0.0 },
-    uTextHeight: { value: 0.0 },
-    uBgYBounds: { value: new Vector2(0.0, 1.0) },
-    uDeclutterHide: { value: 0.0 },
     uRTCCenter: {
       value: new Vector3(
         rtcCenter?.[0] ?? 0,
@@ -56,7 +47,6 @@ export const createBaseMutates = (
     uRTCCenterView: { value: new Vector3(0, 0, 0) },
     uEyeRTELow: { value: new Vector3(0, 0, 0) },
     uEyeRTEHigh: { value: new Vector3(0, 0, 0) },
-    nvr_uBatchId: { value: batchId ?? 0 },
     nvr_uPickable: { value: 0.0 },
     uAtlas: { value: null },
     uColorAtlas: { value: null },
@@ -64,24 +54,16 @@ export const createBaseMutates = (
     // is bound; UVs are unused until glyph quads exist anyway.
     uSdfAtlasSize: { value: new Vector2(1, 1) },
     uColorAtlasSize: { value: new Vector2(1, 1) },
+    uLabelData: { value: null },
+    // Non-zero so the shader's `i % width` / `i / width` never divide by zero
+    // before the mesh binds its label texture.
+    uLabelTexSize: { value: new Vector2(1, 1) },
   };
 
-  // Conditional position uniforms based on RTE mode
-  if (useRTE) {
-    refs.uRTEPositionLOW = { value: new Vector3(0, 0, 0) };
-    refs.uRTEPositionHIGH = { value: new Vector3(0, 0, 0) };
-  } else {
-    refs.uRTCPosition = { value: new Vector3(0, 0, 0) };
-  }
-
   return {
     update: (state: SdfTextBaseState) => {
-      refs.uColor.value.set(state.color);
-      refs.uOpacity.value = state.opacity;
-      refs.uFontSize.value = state.fontSize;
       refs.uCenter.value.set(state.center[0], state.center[1]);
       refs.uSizeInMeters.value = state.sizeInMeters;
-      refs.uAddHeight.value = state.addHeight;
       refs.uOffsetDepth.value = state.offsetDepth;
       refs.uOutlineWidth.value = state.outlineWidth;
       refs.uOutlineColor.value.set(state.outlineColor);
@@ -94,12 +76,8 @@ export const createBaseMutates = (
     },
 
     updateUniforms: (uniforms) => {
-      uniforms.uColor = refs.uColor;
-      uniforms.uOpacity = refs.uOpacity;
-      uniforms.uFontSize = refs.uFontSize;
       uniforms.uCenter = refs.uCenter;
       uniforms.uSizeInMeters = refs.uSizeInMeters;
-      uniforms.uAddHeight = refs.uAddHeight;
       uniforms.uOffsetDepth = refs.uOffsetDepth;
       uniforms.uSdfThreshold = refs.uSdfThreshold;
       uniforms.uOutlineWidth = refs.uOutlineWidth;
@@ -112,31 +90,18 @@ export const createBaseMutates = (
       uniforms.uFovRad = refs.uFovRad;
       uniforms.uScreenHeightPx = refs.uScreenHeightPx;
       uniforms.uFarPlane = refs.uFarPlane;
-      uniforms.uTextWidth = refs.uTextWidth;
-      uniforms.uTextHeight = refs.uTextHeight;
-      uniforms.uBgYBounds = refs.uBgYBounds;
-      uniforms.uDeclutterHide = refs.uDeclutterHide;
       uniforms.uRTCCenter = refs.uRTCCenter;
       uniforms.uRTCCenterView = refs.uRTCCenterView;
       uniforms.uEyeRTELow = refs.uEyeRTELow;
       uniforms.uEyeRTEHigh = refs.uEyeRTEHigh;
       uniforms.u_rteOne = RTE_ONE_UNIFORM;
-      uniforms.nvr_uBatchId = refs.nvr_uBatchId;
       uniforms.nvr_uPickable = refs.nvr_uPickable;
       uniforms.uAtlas = refs.uAtlas;
       uniforms.uColorAtlas = refs.uColorAtlas;
       uniforms.uSdfAtlasSize = refs.uSdfAtlasSize;
       uniforms.uColorAtlasSize = refs.uColorAtlasSize;
-
-      if (refs.uRTEPositionLOW) {
-        uniforms.uRTEPositionLOW = refs.uRTEPositionLOW;
-      }
-      if (refs.uRTEPositionHIGH) {
-        uniforms.uRTEPositionHIGH = refs.uRTEPositionHIGH;
-      }
-      if (refs.uRTCPosition) {
-        uniforms.uRTCPosition = refs.uRTCPosition;
-      }
+      uniforms.uLabelData = refs.uLabelData;
+      uniforms.uLabelTexSize = refs.uLabelTexSize;
     },
 
     updatePerFrame: (
@@ -172,17 +137,6 @@ export const createBaseMutates = (
       }
     },
 
-    updateTextDimensions: (
-      textWidth: number,
-      textHeight: number,
-      bgMinY: number,
-      bgMaxY: number,
-    ) => {
-      refs.uTextWidth.value = textWidth;
-      refs.uTextHeight.value = textHeight;
-      refs.uBgYBounds.value.set(bgMinY, bgMaxY);
-    },
-
     setAtlasTexture: (texture: UniformValue<DataTexture | null>) => {
       refs.uAtlas.value = texture.value;
     },
@@ -202,39 +156,18 @@ export const createBaseMutates = (
       }
     },
 
-    setPosition: (
-      position: Float32Array | { high: Float32Array; low: Float32Array },
-      posUseRTE: boolean,
-      posRtcCenter?: [number, number, number],
+    setLabelDataTexture: (
+      texture: DataTexture | null,
+      width: number,
+      height: number,
     ) => {
-      if (posUseRTE) {
-        const p = position as { high: Float32Array; low: Float32Array };
-        refs.uRTEPositionLOW?.value.set(p.low[0], p.low[1], p.low[2] ?? 0.0);
-        refs.uRTEPositionHIGH?.value.set(
-          p.high[0],
-          p.high[1],
-          p.high[2] ?? 0.0,
-        );
-      } else {
-        const p = position as Float32Array;
-        refs.uRTCPosition?.value.set(p[0], p[1], p[2] ?? 0.0);
-
-        if (posRtcCenter) {
-          refs.uRTCCenter.value.set(
-            posRtcCenter[0],
-            posRtcCenter[1],
-            posRtcCenter[2],
-          );
-        }
-      }
-    },
-
-    setBatchId: (id: number) => {
-      refs.nvr_uBatchId.value = id;
+      refs.uLabelData.value = texture;
+      // Guard against a zero size reaching the shader's modulo/divide.
+      refs.uLabelTexSize.value.set(Math.max(1, width), Math.max(1, height));
     },
 
-    setDeclutterHide: (value: number) => {
-      refs.uDeclutterHide.value = value;
+    setRtcCenter: (center: [number, number, number]) => {
+      refs.uRTCCenter.value.set(center[0], center[1], center[2]);
     },
   };
 };

package/src/material/enhancer/sdfText/sdfTextBaseEnhancer/shader.test.ts

@@ -0,0 +1,77 @@
+import sdfTextFragmentShader from "@shaders/glsl/sdfText.frag.glsl";
+import sdfTextVertexShader from "@shaders/glsl/sdfText.vert.glsl";
+import { describe, expect, it } from "vitest";
+
+import { LABEL_ROWS, LabelRow } from "./types";
+
+import { createSdfTextBaseEnhancer, type SupportedMaterial } from ".";
+
+describe("sdfTextBaseEnhancer shader", () => {
+  const createMockMaterial = () =>
+    ({
+      type: "ShaderMaterial",
+      userData: {},
+    }) as unknown as SupportedMaterial;
+
+  const createMockShader = () => ({
+    vertexShader: "",
+    fragmentShader: "",
+    uniforms: {} as Record<string, { value: unknown }>,
+    defines: {} as Record<string, unknown>,
+  });
+
+  const transform = (
+    props: Parameters<ReturnType<typeof createSdfTextBaseEnhancer>["mount"]>[0],
+  ) => {
+    const enhancer = createSdfTextBaseEnhancer(createMockMaterial());
+    enhancer.mount(props);
+    const shader = createMockShader();
+    enhancer.transformShader(shader as never);
+    return shader;
+  };
+
+  it("should set correct vertex and fragment shaders", () => {
+    const shader = transform({});
+    expect(shader.vertexShader).toBe(sdfTextVertexShader);
+    expect(shader.fragmentShader).toBe(sdfTextFragmentShader);
+  });
+
+  it("should set USE_RTE define only when useRTE=true", () => {
+    expect(transform({ useRTE: true }).defines.USE_RTE).toBe(1);
+    expect(transform({ useRTE: false }).defines.USE_RTE).toBeUndefined();
+  });
+
+  it("should set USE_MSDF define only when useMsdf=true", () => {
+    expect(transform({ useMsdf: true }).defines.USE_MSDF).toBe(1);
+    expect(transform({ useMsdf: false }).defines.USE_MSDF).toBeUndefined();
+  });
+
+  // The shader indexes the label data texture as `slot * LABEL_ROWS + row`.
+  // If the define and the CPU-side row table disagree, every label reads
+  // another label's state — hence injecting it rather than hard-coding it.
+  describe("label data texture contract", () => {
+    it("injects LABEL_ROWS as a define", () => {
+      expect(transform({}).defines.LABEL_ROWS).toBe(LABEL_ROWS);
+    });
+
+    it("keeps LABEL_ROWS in step with the row table", () => {
+      const rows = Object.values(LabelRow);
+      expect(LABEL_ROWS).toBe(rows.length);
+      // Rows must be a dense 0..n-1 range for the stride math to hold.
+      expect([...rows].sort((a, b) => a - b)).toEqual(rows.map((_, i) => i));
+    });
+
+    it("binds the label texture uniforms", () => {
+      const shader = transform({});
+      expect(shader.uniforms.uLabelData).toBeDefined();
+      expect(shader.uniforms.uLabelTexSize).toBeDefined();
+    });
+  });
+
+  it("should assign batch-wide uniforms to shader.uniforms", () => {
+    const shader = transform({ outlineOpacity: 0.25 });
+    expect(shader.uniforms.uCenter).toBeDefined();
+    expect(shader.uniforms.uOutlineOpacity?.value).toBe(0.25);
+    expect(shader.uniforms.nvr_uPickable).toBeDefined();
+  });
+});

package/src/material/enhancer/sdfText/sdfTextBaseEnhancer/shader.ts

@@ -2,7 +2,11 @@ import sdfTextFragmentShader from "@shaders/glsl/sdfText.frag.glsl";
 import sdfTextVertexShader from "@shaders/glsl/sdfText.vert.glsl";
 import type { WebGLProgramParametersWithUniforms } from "three";
 
-import type { SdfTextBaseMutates, SdfTextBaseState } from "./types";
+import {
+  LABEL_ROWS,
+  type SdfTextBaseMutates,
+  type SdfTextBaseState,
+} from "./types";
 
 /**
  * Transform shader with sdfText base modifications.
@@ -24,6 +28,10 @@ export const transformShader = (
   // Set defines based on state
   shader.defines ??= {};
 
+  // Stride of the per-label data texture. Injected rather than hard-coded in
+  // GLSL so the shader's row addressing always matches `LabelRow`.
+  shader.defines.LABEL_ROWS = LABEL_ROWS;
+
   if (state.useRTE) {
     shader.defines.USE_RTE = 1;
   }

package/src/material/enhancer/sdfText/sdfTextBaseEnhancer/state.test.ts

@@ -6,8 +6,8 @@ import { sdfRadiusFor } from "./types";
 describe("sdfTextBaseEnhancer / state", () => {
   describe("updateState", () => {
     it("initializes state from props with defaults", () => {
-      const state = updateState({ fontSize: 24 }, DEFAULT_BASE_STATE);
-      expect(state.fontSize).toBe(24);
+      const state = updateState({ offsetDepth: false }, DEFAULT_BASE_STATE);
+      expect(state.offsetDepth).toBe(false);
       expect(state.center).toEqual([0.5, 0.0]);
       expect(state.sizeInMeters).toBe(true);
     });
@@ -18,16 +18,6 @@ describe("sdfTextBaseEnhancer / state", () => {
       expect(state.useRTE).toBe(true);
     });
 
-    it("updates color from hex to RGB tuple", () => {
-      const state = updateState({ color: 0xff0000 }, DEFAULT_BASE_STATE);
-      expect(state.color.getHex()).toBe(0xff0000);
-    });
-
-    it("updates fontSize", () => {
-      const state = updateState({ fontSize: 32 }, DEFAULT_BASE_STATE);
-      expect(state.fontSize).toBe(32);
-    });
-
     it("updates center", () => {
       const state = updateState({ center: [0.0, 0.5] }, DEFAULT_BASE_STATE);
       expect(state.center).toEqual([0.0, 0.5]);
@@ -38,11 +28,6 @@ describe("sdfTextBaseEnhancer / state", () => {
       expect(state.sizeInMeters).toBe(true);
     });
 
-    it("updates addHeight", () => {
-      const state = updateState({ addHeight: 100 }, DEFAULT_BASE_STATE);
-      expect(state.addHeight).toBe(100);
-    });
-
     it("updates offsetDepth", () => {
       const state = updateState({ offsetDepth: false }, DEFAULT_BASE_STATE);
       expect(state.offsetDepth).toBe(false);
@@ -99,6 +84,17 @@ describe("sdfTextBaseEnhancer / state", () => {
       expect(state.pickable).toBe(true);
     });
 
+    // Colour, opacity, font size and height moved into the per-label data
+    // texture when text became a single batched draw call, so they must not
+    // reappear as batch-wide state.
+    it("carries no per-label style", () => {
+      const state = updateState({}, DEFAULT_BASE_STATE);
+      expect(state).not.toHaveProperty("color");
+      expect(state).not.toHaveProperty("opacity");
+      expect(state).not.toHaveProperty("fontSize");
+      expect(state).not.toHaveProperty("addHeight");
+    });
+
     it("updates depthTest", () => {
       const state = updateState({ depthTest: false }, DEFAULT_BASE_STATE);
       expect(state.depthTest).toBe(false);
@@ -107,11 +103,11 @@ describe("sdfTextBaseEnhancer / state", () => {
     it("falls back to currentState for missing props", () => {
       const currentState = {
         ...DEFAULT_BASE_STATE,
-        fontSize: 42,
+        outlineOpacity: 0.25,
         center: [1, 2] as [number, number],
       };
       const state = updateState({}, currentState);
-      expect(state.fontSize).toBe(42);
+      expect(state.outlineOpacity).toBe(0.25);
       expect(state.center).toEqual([1, 2]);
     });
   });

package/src/material/enhancer/sdfText/sdfTextBaseEnhancer/state.ts

@@ -15,12 +15,8 @@ export const DEFAULT_BASE_PROPS: Required<
 > = {
   useRTE: false,
   useMsdf: false,
-  color: 0xffffff,
-  opacity: 1.0,
-  fontSize: 16.0,
   center: [0.5, 0.0],
   sizeInMeters: true,
-  addHeight: 0.0,
   offsetDepth: true,
   outlineWidth: 0,
   outlineColor: 0x000000,
@@ -38,12 +34,8 @@ export const DEFAULT_BASE_PROPS: Required<
 export const DEFAULT_BASE_STATE: SdfTextBaseState = {
   useRTE: DEFAULT_BASE_PROPS.useRTE,
   useMsdf: DEFAULT_BASE_PROPS.useMsdf,
-  color: hexToColor(DEFAULT_BASE_PROPS.color),
-  opacity: DEFAULT_BASE_PROPS.opacity,
-  fontSize: DEFAULT_BASE_PROPS.fontSize,
   center: DEFAULT_BASE_PROPS.center,
   sizeInMeters: DEFAULT_BASE_PROPS.sizeInMeters,
-  addHeight: DEFAULT_BASE_PROPS.addHeight,
   offsetDepth: DEFAULT_BASE_PROPS.offsetDepth,
   outlineWidth:
     DEFAULT_BASE_PROPS.outlineWidth / sdfRadiusFor(DEFAULT_BASE_PROPS.useMsdf),
@@ -72,13 +64,8 @@ export const updateState = (
     useRTE: currentState.useRTE,
     useMsdf: currentState.useMsdf,
     // Mutable
-    color:
-      props.color !== undefined ? hexToColor(props.color) : currentState.color,
-    opacity: props.opacity ?? currentState.opacity,
-    fontSize: props.fontSize ?? currentState.fontSize,
     center: props.center ?? currentState.center,
     sizeInMeters: props.sizeInMeters ?? currentState.sizeInMeters,
-    addHeight: props.addHeight ?? currentState.addHeight,
     offsetDepth: props.offsetDepth ?? currentState.offsetDepth,
     outlineWidth:
       props.outlineWidth !== undefined

package/src/material/enhancer/sdfText/sdfTextBaseEnhancer/types.ts

@@ -10,8 +10,39 @@ import type { Mutates } from "../../MaterialEnhancer";
  *  `MSDF_RANGE_PX` (8 px). See [`atlasRangePx`] in `@navaramap/font`. */
 export const sdfRadiusFor = (useMsdf: boolean): number => atlasRangePx(useMsdf);
 
+/**
+ * Layout of the per-label data texture (`uLabelData`).
+ *
+ * This is a contract between three places: the vertex shader's `nvr_readLabel`
+ * (`shaders/glsl/sdfText.vert.glsl`), which receives {@link LABEL_ROWS} as a
+ * define so it can't drift; the CPU-side writer
+ * (`mesh/sdfText/labelData.ts`); and the mesh that fills the rows. It lives
+ * here because the enhancer owns the shader.
+ */
+export const LabelRow = {
+  /** xyz = anchor high (RTE) or RTC-relative anchor, w = fontSize. */
+  POSITION_HIGH_SIZE: 0,
+  /** xyz = anchor low (RTE only), w = addHeight. */
+  POSITION_LOW_HEIGHT: 1,
+  /** rgb = colour, a = opacity. */
+  COLOR_OPACITY: 2,
+  /** x = textWidth, y = textHeight, z = bgMinY, w = bgMaxY (all in ems). */
+  BOX: 3,
+  /** x = declutterHide, y = batchId, z = show, w = reserved. */
+  STATE: 4,
+} as const;
+
+/** Texels per label. Derived from {@link LabelRow} so the two can't disagree. */
+export const LABEL_ROWS = Object.keys(LabelRow).length;
+
 /**
  * Props for the sdfText base enhancer.
+ *
+ * Everything here is **batch-wide**: one material draws every label in a
+ * tile-layer. Per-label values (position, colour, opacity, font size, height,
+ * block metrics, batch id, declutter fade) live in the label data texture
+ * owned by `BatchedSdfTextMesh`, not in this state — see
+ * `web/navara_three/src/mesh/sdfText/labelData.ts`.
  */
 export type SdfTextBaseProps = {
   // Immutable after mount
@@ -21,12 +52,8 @@ export type SdfTextBaseProps = {
   useMsdf?: boolean;
 
   // Mutable state
-  color?: number; // hex color
-  opacity?: number;
-  fontSize?: number;
   center?: [number, number];
   sizeInMeters?: boolean;
-  addHeight?: number;
   offsetDepth?: boolean;
   outlineWidth?: number; // raw width, converted in state via sdfRadiusFor(useMsdf)
   outlineColor?: number; // hex
@@ -55,12 +82,8 @@ export type SdfTextBaseState = Readonly<{
   useMsdf: boolean;
 
   // Mutable
-  color: Color;
-  opacity: number;
-  fontSize: number;
   center: [number, number];
   sizeInMeters: boolean;
-  addHeight: number;
   offsetDepth: boolean;
   outlineWidth: number; // pre-converted: raw / sdfRadiusFor(useMsdf)
   outlineColor: Color;
@@ -82,12 +105,8 @@ export type SdfTextBaseState = Readonly<{
  * Internal type - not exposed externally.
  */
 export type SdfTextBaseRefs = {
-  uColor: UniformValue<Color>;
-  uOpacity: UniformValue<number>;
-  uFontSize: UniformValue<number>;
   uCenter: UniformValue<Vector2>;
   uSizeInMeters: UniformValue<boolean>;
-  uAddHeight: UniformValue<number>;
   uOffsetDepth: UniformValue<boolean>;
   uSdfThreshold: UniformValue<number>;
   uOutlineWidth: UniformValue<number>;
@@ -100,20 +119,12 @@ export type SdfTextBaseRefs = {
   uFovRad: UniformValue<number>;
   uScreenHeightPx: UniformValue<number>;
   uFarPlane: UniformValue<number>;
-  uTextWidth: UniformValue<number>;
-  uTextHeight: UniformValue<number>;
-  uBgYBounds: UniformValue<Vector2>;
-  /** Screen-space declutter hide factor (0 = shown … 1 = hidden), animated
-   *  by the declutter fade. Driven by the declutter pass, not by material
-   *  style updates. */
-  uDeclutterHide: UniformValue<number>;
   uRTCCenter: UniformValue<Vector3>;
   uRTCCenterView: UniformValue<Vector3>;
   uEyeRTELow: UniformValue<Vector3>;
   uEyeRTEHigh: UniformValue<Vector3>;
   /** Always 1.0 — blocks fast-math reassociation of the RTE recombination. */
   u_rteOne?: UniformValue<number>;
-  nvr_uBatchId: UniformValue<number>;
   nvr_uPickable: UniformValue<number>;
   uAtlas: UniformValue<DataTexture | null>;
   /** COLRv1 RGBA atlas. `null` when the font has no color glyphs. */
@@ -122,11 +133,12 @@ export type SdfTextBaseRefs = {
   uSdfAtlasSize: UniformValue<Vector2>;
   /** Current color atlas pixel dimensions; updated when the color atlas grows. */
   uColorAtlasSize: UniformValue<Vector2>;
-
-  // Conditional RTE/RTC position uniforms
-  uRTEPositionLOW?: UniformValue<Vector3>;
-  uRTEPositionHIGH?: UniformValue<Vector3>;
-  uRTCPosition?: UniformValue<Vector3>;
+  /** Per-label state, indexed by the `labelIndex` instance attribute. Owned by
+   *  the mesh and swapped wholesale when it outgrows its capacity. */
+  uLabelData: UniformValue<DataTexture | null>;
+  /** Dimensions of `uLabelData` in texels, for the shader's index-to-texel
+   *  math. Read as an `ivec2`. */
+  uLabelTexSize: UniformValue<Vector2>;
 };
 
 export type SdfTextBaseUniforms = Partial<SdfTextBaseRefs>;
@@ -151,15 +163,6 @@ export type SdfTextBaseMutates = Mutates<
       viewMatrix: Matrix4,
       state: SdfTextBaseState,
     ) => void;
-    /**
-     * Update text dimension uniforms after text shaping.
-     */
-    updateTextDimensions: (
-      textWidth: number,
-      textHeight: number,
-      bgMinY: number,
-      bgMaxY: number,
-    ) => void;
     /**
      * Set the SDF atlas texture external ref.
      */
@@ -175,23 +178,18 @@ export type SdfTextBaseMutates = Mutates<
      */
     updateAtlasSizes: () => void;
     /**
-     * Update position uniforms (RTE or RTC).
+     * Point the shader at the mesh's per-label data texture. Must be re-called
+     * whenever the mesh grows it, since growing allocates a new texture.
      */
-    setPosition: (
-      position: Float32Array | { high: Float32Array; low: Float32Array },
-      useRTE: boolean,
-      rtcCenter?: [number, number, number],
+    setLabelDataTexture: (
+      texture: DataTexture | null,
+      width: number,
+      height: number,
     ) => void;
     /**
-     * Set the batch ID uniform (immutable after mount, but needed for batch creation).
-     */
-    setBatchId: (batchId: number) => void;
-    /**
-     * Set the declutter hide factor (0 = shown … 1 = hidden); the fragment
-     * shader scales opacity by `1 - value` and the vertex shader hard-culls
-     * at 1. Kept separate from `show`/`opacity` so user-driven visibility and
-     * declutter results compose instead of clobbering each other.
+     * Update the batch's RTC center (the tile transform). Only meaningful in
+     * RTC mode; in RTE mode anchors carry their own high/low split.
      */
-    setDeclutterHide: (value: number) => void;
+    setRtcCenter: (center: [number, number, number]) => void;
   }
 >;

package/src/mesh/constants.ts

@@ -0,0 +1,22 @@
+/**
+ * Geometry type constants for mesh objects.
+ * These types are used for feature evaluation and runtime validation.
+ */
+export const GEOMETRY_TYPES = {
+  Billboard: "billboard",
+  Text: "text",
+  Point: "point",
+  Polyline: "polyline",
+  Polygon: "polygon",
+  Model: "model",
+} as const;
+
+/**
+ * Array of valid geometry type values for runtime validation.
+ */
+export const VALID_GEOMETRY_TYPES = Object.values(GEOMETRY_TYPES);
+
+/**
+ * Type representing a valid geometry type value.
+ */
+export type GeometryType = (typeof GEOMETRY_TYPES)[keyof typeof GEOMETRY_TYPES];

package/src/mesh/index.ts

@@ -1,3 +1,4 @@
+export * from "./constants";
 export * from "./model";
 export * from "./polygon";
 export * from "./polyline";
@@ -12,5 +13,4 @@ export * from "./pickableMeshWrapper";
 export * from "./rtcRteHelper";
 export * from "./sprite";
 export * from "./sdfText";
-export * from "./batchedSdfText";
 export * from "./DrapedMesh";

package/src/mesh/model.ts

@@ -39,6 +39,7 @@ import {
   updateBatchAttribute,
   type BatchTextureConfig,
 } from "./batchTexture";
+import { GEOMETRY_TYPES } from "./constants";
 import type { FeatureMesh } from "./featureMesh";
 import type { PickableMesh } from "./pickableMesh";
 import { releaseGeometryArraysAfterUpload } from "./releaseGeometryArrays";
@@ -96,6 +97,11 @@ export class ModelMesh
     });
   }
 
+  /**
+   * Geometry type of this mesh.
+   */
+  readonly geometryType = GEOMETRY_TYPES.Model;
+
   get water(): boolean {
     for (const enhancer of this._enhancers.values()) {
       // Assume the first enhancer has the common value.

package/src/mesh/polygon.ts

@@ -32,6 +32,7 @@ import type {
   BatchTextureRowKey,
   DefaultBatchAttributeValues,
 } from "./batchTexture";
+import { GEOMETRY_TYPES } from "./constants";
 import { releaseGeometryArraysAfterUpload } from "./releaseGeometryArrays";
 import { setupRTECallback } from "./rtcRteHelper";
 
@@ -85,6 +86,11 @@ export class PolygonMesh extends BatchedFeatureMesh<
     return !!this._enhancedMaterial;
   }
 
+  /**
+   * Geometry type of this mesh.
+   */
+  readonly geometryType = GEOMETRY_TYPES.Polygon;
+
   init(mesh: NavaraPolygonMesh, tileHandle: TileHandle | undefined) {
     this.batchLength = mesh.batch_length;
     // Register cleanup listener first (before any potential early returns)

package/src/mesh/polyline.ts

@@ -24,6 +24,7 @@ import type {
   BatchTextureRowKey,
   DefaultBatchAttributeValues,
 } from "./batchTexture";
+import { GEOMETRY_TYPES } from "./constants";
 import { releaseGeometryArraysAfterUpload } from "./releaseGeometryArrays";
 import { setupRTECallback } from "./rtcRteHelper";
 
@@ -65,6 +66,11 @@ export class PolylineMesh extends BatchedFeatureMesh<
     this.ctx = ctx;
   }
 
+  /**
+   * Geometry type of this mesh.
+   */
+  readonly geometryType = GEOMETRY_TYPES.Polyline;
+
   init(mesh: NavaraPolylineMesh) {
     this.batchLength = mesh.batch_length;
     const geometryResult = this.initGeometry(mesh);