@navaramap/three 0.0.0

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

@@ -0,0 +1,19 @@
+import type { ShaderMarkers } from "../../ShaderReplacer";
+import { createShaderReplacer } from "../../ShaderReplacer";
+
+/**
+ * Shader markers for the sdfText base enhancer.
+ * These markers are placed in the shader code to allow composing enhancers to inject their own code.
+ */
+export const SDF_TEXT_BASE_SHADER_MARKERS = {
+  vertex: {},
+  fragment: {},
+} as const satisfies ShaderMarkers;
+
+/**
+ * Factory function to create a ShaderReplacer restricted to sdfText base markers.
+ * Used by composing enhancers to safely modify shaders.
+ */
+export function createSdfTextBaseShaderReplacer(source: string) {
+  return createShaderReplacer<typeof SDF_TEXT_BASE_SHADER_MARKERS>(source);
+}

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

@@ -0,0 +1,35 @@
+import { ShaderMaterial } from "three";
+import { describe, expect, it } from "vitest";
+
+import { updateMaterialProps } from "./material";
+
+describe("sdfTextBaseEnhancer/material", () => {
+  describe("updateMaterialProps", () => {
+    it("should not update properties when props are undefined", () => {
+      const material = new ShaderMaterial();
+      material.depthTest = false;
+      material.transparent = true;
+
+      updateMaterialProps(material, {});
+
+      expect(material.depthTest).toBe(false);
+      expect(material.transparent).toBe(true);
+    });
+
+    it("should update depthTest when provided", () => {
+      const material = new ShaderMaterial();
+      material.depthTest = true;
+
+      updateMaterialProps(material, { depthTest: false });
+      expect(material.depthTest).toBe(false);
+    });
+
+    it("should update transparent when provided", () => {
+      const material = new ShaderMaterial();
+      material.transparent = false;
+
+      updateMaterialProps(material, { transparent: true });
+      expect(material.transparent).toBe(true);
+    });
+  });
+});

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

@@ -0,0 +1,32 @@
+import { ShaderMaterial } from "three";
+
+import type { ShaderName } from "../../MaterialEnhancer";
+
+import type { SdfTextBaseProps } from "./types";
+
+/**
+ * Shaders that the sdfText base enhancer supports.
+ * SdfText uses ShaderMaterial with custom shaders.
+ */
+export const AVAILABLE_SHADERS = ["shader"] satisfies ShaderName[];
+
+/**
+ * Material types that the sdfText base enhancer supports.
+ */
+export type SupportedMaterial = ShaderMaterial;
+
+/**
+ * Update material properties that affect the Three.js material directly.
+ * These properties are not handled by shader uniforms.
+ */
+export function updateMaterialProps(
+  material: SupportedMaterial,
+  props: SdfTextBaseProps,
+): void {
+  if (props.depthTest !== undefined) {
+    material.depthTest = props.depthTest;
+  }
+  if (props.transparent !== undefined) {
+    material.transparent = props.transparent;
+  }
+}

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

@@ -0,0 +1,381 @@
+import { type DataTexture, Color, Matrix4 } from "three";
+import { describe, expect, it, vi } from "vitest";
+
+import type { ShaderUniforms } from "../../MaterialEnhancer";
+
+import { createBaseMutates } from "./mutates";
+import { DEFAULT_BASE_STATE } from "./state";
+import type { SdfTextBaseState } from "./types";
+
+vi.mock("@navaramap/engine-api", () => ({
+  encodePosition: (_x: number, _y: number, _z: number) => ({
+    high: { x: 1000, y: 2000, z: 3000 },
+    low: { x: 0.5, y: 0.25, z: 0.125 },
+  }),
+}));
+
+describe("sdfTextBaseEnhancer/mutates", () => {
+  describe("update syncs refs from state", () => {
+    it("should sync core refs from state", () => {
+      const state: SdfTextBaseState = {
+        ...DEFAULT_BASE_STATE,
+        color: new Color(0xff0000),
+        fontSize: 24,
+        center: [0.5, 0.5],
+        sizeInMeters: true,
+        addHeight: 50,
+        offsetDepth: false,
+        outlineWidth: 0.1,
+        outlineColor: new Color(0x00ff00),
+        outlineOpacity: 0.8,
+        showBackground: true,
+        backgroundColor: new Color(0x0000ff),
+        backgroundOutlineColor: new Color(0xffff00),
+        backgroundOutlineWidth: 0.2,
+        pickable: true,
+      };
+      const mutates = createBaseMutates(false);
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uColor?.value.getHex()).toBe(0xff0000);
+      expect(uniforms.uFontSize?.value).toBe(24);
+      expect(uniforms.uCenter?.value.x).toBe(0.5);
+      expect(uniforms.uCenter?.value.y).toBe(0.5);
+      expect(uniforms.uSizeInMeters?.value).toBe(true);
+      expect(uniforms.uAddHeight?.value).toBe(50);
+      expect(uniforms.uOffsetDepth?.value).toBe(false);
+      expect(uniforms.uOutlineWidth?.value).toBe(0.1);
+      expect(uniforms.uOutlineColor?.value.getHex()).toBe(0x00ff00);
+      expect(uniforms.uOutlineOpacity?.value).toBe(0.8);
+      expect(uniforms.uShowBackground?.value).toBe(true);
+      expect(uniforms.uBackgroundColor?.value.getHex()).toBe(0x0000ff);
+      expect(uniforms.uBackgroundOutlineColor?.value.getHex()).toBe(0xffff00);
+      expect(uniforms.uBackgroundOutlineWidth?.value).toBe(0.2);
+      expect(uniforms.nvr_uPickable?.value).toBe(1.0);
+    });
+  });
+
+  describe("RTC center", () => {
+    it("should initialize uRTCCenter from constructor args", () => {
+      const state: SdfTextBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false, [10, 20, 30]);
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uRTCCenter?.value.x).toBe(10);
+      expect(uniforms.uRTCCenter?.value.y).toBe(20);
+      expect(uniforms.uRTCCenter?.value.z).toBe(30);
+    });
+  });
+
+  describe("RTE position refs", () => {
+    it("should create RTE position uniforms when useRTE=true", () => {
+      const state: SdfTextBaseState = {
+        ...DEFAULT_BASE_STATE,
+        useRTE: true,
+      };
+      const mutates = createBaseMutates(true);
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uRTEPositionLOW).toBeDefined();
+      expect(uniforms.uRTEPositionHIGH).toBeDefined();
+      expect(uniforms.uRTCPosition).toBeUndefined();
+    });
+
+    it("should create RTC position uniform when useRTE=false", () => {
+      const state: SdfTextBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false);
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uRTCPosition).toBeDefined();
+      expect(uniforms.uRTEPositionLOW).toBeUndefined();
+      expect(uniforms.uRTEPositionHIGH).toBeUndefined();
+    });
+  });
+
+  describe("atlas texture ref", () => {
+    it("should update uAtlas value without replacing uniform ref", () => {
+      const state: SdfTextBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false);
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+      const initialAtlasUniform = uniforms.uAtlas;
+      expect(initialAtlasUniform).toBeDefined();
+      expect(initialAtlasUniform?.value).toBeNull();
+
+      const nextTexture = {
+        image: { width: 256, height: 256, data: new Uint8Array(256 * 256) },
+      } as unknown as DataTexture;
+
+      mutates.setAtlasTexture({ value: nextTexture });
+
+      expect(uniforms.uAtlas).toBe(initialAtlasUniform);
+      expect(uniforms.uAtlas?.value).toBe(nextTexture);
+    });
+  });
+
+  describe("updateAtlasSizes", () => {
+    it("should sync uSdfAtlasSize and uColorAtlasSize from bound texture images", () => {
+      const state: SdfTextBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false);
+      mutates.update(state);
+
+      const sdfTex = {
+        image: { width: 1024, height: 2048, data: new Uint8Array(1) },
+      } as unknown as DataTexture;
+      const colorTex = {
+        image: { width: 4096, height: 4096, data: new Uint8Array(1) },
+      } as unknown as DataTexture;
+
+      mutates.setAtlasTexture({ value: sdfTex });
+      mutates.setColorAtlasTexture({ value: colorTex });
+      mutates.updateAtlasSizes();
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uSdfAtlasSize?.value.x).toBe(1024);
+      expect(uniforms.uSdfAtlasSize?.value.y).toBe(2048);
+      expect(uniforms.uColorAtlasSize?.value.x).toBe(4096);
+      expect(uniforms.uColorAtlasSize?.value.y).toBe(4096);
+    });
+
+    it("should pick up new dimensions after the atlas grows", () => {
+      const state: SdfTextBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false);
+      mutates.update(state);
+
+      const sdfTex = {
+        image: { width: 2048, height: 2048, data: new Uint8Array(1) },
+      } as unknown as DataTexture;
+      mutates.setAtlasTexture({ value: sdfTex });
+      mutates.updateAtlasSizes();
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+      expect(uniforms.uSdfAtlasSize?.value.x).toBe(2048);
+      expect(uniforms.uSdfAtlasSize?.value.y).toBe(2048);
+
+      // Simulate the SDFAtlas growing — the image dims on the same texture
+      // change, and updateAtlasSizes() must propagate them to the uniform.
+      sdfTex.image = {
+        width: 4096,
+        height: 4096,
+        data: new Uint8Array(1),
+      } as DataTexture["image"];
+      mutates.updateAtlasSizes();
+
+      expect(uniforms.uSdfAtlasSize?.value.x).toBe(4096);
+      expect(uniforms.uSdfAtlasSize?.value.y).toBe(4096);
+    });
+
+    it("should leave atlas size uniforms unchanged when textures are null", () => {
+      const state: SdfTextBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false);
+      mutates.update(state);
+
+      // Both uAtlas and uColorAtlas default to null.
+      mutates.updateAtlasSizes();
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      // Defaults set in createBaseMutates: (1, 1) to avoid divide-by-zero.
+      expect(uniforms.uSdfAtlasSize?.value.x).toBe(1);
+      expect(uniforms.uSdfAtlasSize?.value.y).toBe(1);
+      expect(uniforms.uColorAtlasSize?.value.x).toBe(1);
+      expect(uniforms.uColorAtlasSize?.value.y).toBe(1);
+    });
+
+    it("should leave atlas size uniforms unchanged when image has zero dimensions", () => {
+      const state: SdfTextBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false);
+      mutates.update(state);
+
+      const sdfTex = {
+        image: { width: 0, height: 0, data: new Uint8Array(0) },
+      } as unknown as DataTexture;
+      mutates.setAtlasTexture({ value: sdfTex });
+      mutates.updateAtlasSizes();
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uSdfAtlasSize?.value.x).toBe(1);
+      expect(uniforms.uSdfAtlasSize?.value.y).toBe(1);
+    });
+  });
+
+  describe("updatePerFrame", () => {
+    it("should update camera uniforms", () => {
+      const state: SdfTextBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false);
+      mutates.update(state);
+
+      mutates.updatePerFrame(1.5, 1080, 10000, 0, 0, 0, new Matrix4(), state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uFovRad?.value).toBe(1.5);
+      expect(uniforms.uScreenHeightPx?.value).toBe(1080);
+      expect(uniforms.uFarPlane?.value).toBe(10000);
+    });
+
+    it("should update RTE eye uniforms when useRTE=true", () => {
+      const state: SdfTextBaseState = {
+        ...DEFAULT_BASE_STATE,
+        useRTE: true,
+      };
+      const mutates = createBaseMutates(true);
+      mutates.update(state);
+
+      mutates.updatePerFrame(
+        1.0,
+        1080,
+        1000,
+        100,
+        200,
+        300,
+        new Matrix4(),
+        state,
+      );
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      const eyeHigh = uniforms.uEyeRTEHigh?.value;
+      const eyeLow = uniforms.uEyeRTELow?.value;
+      expect(eyeHigh).toBeDefined();
+      expect(eyeLow).toBeDefined();
+      // Values come from the mocked encodePosition
+      expect(eyeHigh?.x).toBe(1000);
+      expect(eyeLow?.x).toBe(0.5);
+    });
+
+    it("should not update RTE eye uniforms when useRTE=false", () => {
+      const state: SdfTextBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false);
+      mutates.update(state);
+
+      mutates.updatePerFrame(
+        1.0,
+        1080,
+        1000,
+        100,
+        200,
+        300,
+        new Matrix4(),
+        state,
+      );
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uEyeRTEHigh?.value.x).toBe(0);
+      expect(uniforms.uEyeRTEHigh?.value.y).toBe(0);
+      expect(uniforms.uEyeRTEHigh?.value.z).toBe(0);
+    });
+
+    it("should transform the RTC center into view space when useRTE=false", () => {
+      const state: SdfTextBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false, [6_400_000, 0, 0]);
+      mutates.update(state);
+
+      // View matrix cancels the center's large X so it lands near the origin.
+      const viewInverse = new Matrix4().makeTranslation(-6_400_000, 0, 0);
+      mutates.updatePerFrame(1.0, 1080, 1000, 0, 0, 0, viewInverse, state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uRTCCenterView?.value.x).toBeCloseTo(0, 3);
+      expect(uniforms.uRTCCenterView?.value.y).toBeCloseTo(0, 3);
+      expect(uniforms.uRTCCenterView?.value.z).toBeCloseTo(0, 3);
+    });
+  });
+
+  describe("updateTextDimensions", () => {
+    it("should update text dimension uniforms", () => {
+      const state: SdfTextBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false);
+      mutates.update(state);
+
+      mutates.updateTextDimensions(5.0, 1.0, -0.2, 0.8);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uTextWidth?.value).toBe(5.0);
+      expect(uniforms.uTextHeight?.value).toBe(1.0);
+      expect(uniforms.uBgYBounds?.value.x).toBe(-0.2);
+      expect(uniforms.uBgYBounds?.value.y).toBe(0.8);
+    });
+  });
+
+  describe("setPosition", () => {
+    it("should set RTE position uniforms", () => {
+      const state: SdfTextBaseState = {
+        ...DEFAULT_BASE_STATE,
+        useRTE: true,
+      };
+      const mutates = createBaseMutates(true);
+      mutates.update(state);
+
+      const high = new Float32Array([100, 200, 300]);
+      const low = new Float32Array([0.1, 0.2, 0.3]);
+      mutates.setPosition({ high, low }, true);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uRTEPositionHIGH?.value.x).toBe(100);
+      expect(uniforms.uRTEPositionLOW?.value.x).toBeCloseTo(0.1);
+    });
+
+    it("should set RTC position uniforms", () => {
+      const state: SdfTextBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false);
+      mutates.update(state);
+
+      const pos = new Float32Array([10, 20, 30]);
+      mutates.setPosition(pos, false, [100, 200, 300]);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uRTCPosition?.value.x).toBe(10);
+      expect(uniforms.uRTCPosition?.value.y).toBe(20);
+      expect(uniforms.uRTCCenter?.value.x).toBe(100);
+      expect(uniforms.uRTCCenter?.value.y).toBe(200);
+    });
+  });
+
+  describe("setBatchId", () => {
+    it("should update nvr_uBatchId value", () => {
+      const state: SdfTextBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false);
+      mutates.update(state);
+
+      mutates.setBatchId(42);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.nvr_uBatchId?.value).toBe(42);
+    });
+  });
+});

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

@@ -0,0 +1,232 @@
+import { encodePosition } from "@navaramap/engine-api";
+import { Color, DataTexture, type Matrix4, Vector2, Vector3 } from "three";
+
+import type { UniformValue } from "../../../types";
+
+import type {
+  SdfTextBaseMutates,
+  SdfTextBaseRefs,
+  SdfTextBaseState,
+} from "./types";
+
+/**
+ * Create mutation functions for the sdfText base enhancer.
+ * Refs are created internally and captured via closure.
+ *
+ * @param useRTE - Whether RTE positioning is enabled
+ * @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 },
+    uOutlineColor: { value: new Color(1, 0, 0) },
+    uOutlineOpacity: { value: 1.0 },
+    uShowBackground: { value: false },
+    uBackgroundColor: { value: new Color(1, 0, 0) },
+    uBackgroundOutlineColor: { value: new Color(1, 0, 0) },
+    uBackgroundOutlineWidth: { value: 0.1 },
+    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) },
+    uRTCCenter: {
+      value: new Vector3(
+        rtcCenter?.[0] ?? 0,
+        rtcCenter?.[1] ?? 0,
+        rtcCenter?.[2] ?? 0,
+      ),
+    },
+    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 },
+    // Default to 1.0 to avoid divide-by-zero in the shader before a texture
+    // is bound; UVs are unused until glyph quads exist anyway.
+    uSdfAtlasSize: { value: new Vector2(1, 1) },
+    uColorAtlasSize: { 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);
+      refs.uOutlineOpacity.value = state.outlineOpacity;
+      refs.uShowBackground.value = state.showBackground;
+      refs.uBackgroundColor.value.set(state.backgroundColor);
+      refs.uBackgroundOutlineColor.value.set(state.backgroundOutlineColor);
+      refs.uBackgroundOutlineWidth.value = state.backgroundOutlineWidth;
+      refs.nvr_uPickable.value = state.pickable ? 1.0 : 0.0;
+    },
+
+    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;
+      uniforms.uOutlineColor = refs.uOutlineColor;
+      uniforms.uOutlineOpacity = refs.uOutlineOpacity;
+      uniforms.uShowBackground = refs.uShowBackground;
+      uniforms.uBackgroundColor = refs.uBackgroundColor;
+      uniforms.uBackgroundOutlineColor = refs.uBackgroundOutlineColor;
+      uniforms.uBackgroundOutlineWidth = refs.uBackgroundOutlineWidth;
+      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.uRTCCenter = refs.uRTCCenter;
+      uniforms.uRTCCenterView = refs.uRTCCenterView;
+      uniforms.uEyeRTELow = refs.uEyeRTELow;
+      uniforms.uEyeRTEHigh = refs.uEyeRTEHigh;
+      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;
+      }
+    },
+
+    updatePerFrame: (
+      fovRad: number,
+      screenHeightPx: number,
+      farPlane: number,
+      cameraX: number,
+      cameraY: number,
+      cameraZ: number,
+      viewMatrix: Matrix4,
+      state: SdfTextBaseState,
+    ) => {
+      refs.uFovRad.value = fovRad;
+      refs.uScreenHeightPx.value = screenHeightPx;
+      refs.uFarPlane.value = farPlane;
+
+      if (state.useRTE) {
+        const encoded = encodePosition(cameraX, cameraY, cameraZ);
+        refs.uEyeRTELow.value.set(encoded.low.x, encoded.low.y, encoded.low.z);
+        refs.uEyeRTEHigh.value.set(
+          encoded.high.x,
+          encoded.high.y,
+          encoded.high.z,
+        );
+      } else {
+        // Transform the RTC center into view space here (JS numbers are
+        // float64), so the shader receives a small, precise value instead of
+        // doing `viewMatrix * uRTCCenter` where both operands are ~6.4e6 in
+        // float32 — the source of the jitter.
+        refs.uRTCCenterView.value
+          .copy(refs.uRTCCenter.value)
+          .applyMatrix4(viewMatrix);
+      }
+    },
+
+    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;
+    },
+
+    setColorAtlasTexture: (texture: UniformValue<DataTexture | null>) => {
+      refs.uColorAtlas.value = texture.value;
+    },
+
+    updateAtlasSizes: () => {
+      const sdfImg = refs.uAtlas.value?.image;
+      if (sdfImg && sdfImg.width > 0 && sdfImg.height > 0) {
+        refs.uSdfAtlasSize.value.set(sdfImg.width, sdfImg.height);
+      }
+      const colorImg = refs.uColorAtlas.value?.image;
+      if (colorImg && colorImg.width > 0 && colorImg.height > 0) {
+        refs.uColorAtlasSize.value.set(colorImg.width, colorImg.height);
+      }
+    },
+
+    setPosition: (
+      position: Float32Array | { high: Float32Array; low: Float32Array },
+      posUseRTE: boolean,
+      posRtcCenter?: [number, number, 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;
+    },
+  };
+};