@navaramap/three 0.0.0

package/src/material/enhancer/model/modelWaterEnhancer/mutates.ts

@@ -0,0 +1,89 @@
+import type { Texture } from "three";
+
+import type { UniformValue } from "../../../types";
+
+import type { ModelWaterMutates, ModelWaterRefs } from "./types";
+
+/**
+ * Default refs with initial values.
+ * These are cloned in createWaterMutates and synced from state via update().
+ * Note: timeUniform and tSkyEnvMap are external refs assigned via setters (identity doesn't change).
+ */
+const DEFAULT_WATER_REFS: Omit<ModelWaterRefs, "uTime" | "tSkyEnvMap"> = {
+  reflectivity: { value: 0 },
+  uWaterNormalMap: { value: null },
+  cachedWaterNormalMap: { value: null },
+  uWaterScaleNormal: { value: 0 },
+  uWaterSpeed: { value: 0 },
+  uShininess: { value: 0 },
+  uSpecularStrength: { value: 0 },
+  uApplyWaterNormal: { value: 0 },
+  uSpecular: { value: false },
+  uIor: { value: 1.33333 },
+};
+
+/**
+ * Create mutation functions for the water enhancer.
+ * Refs are created internally and captured via closure.
+ */
+export const createWaterMutates = (): ModelWaterMutates => {
+  // Clone defaults so each enhancer instance gets independent ref objects
+  // timeUniform and tSkyEnvMap are external refs assigned via setters (identity doesn't change)
+  const refs: ModelWaterRefs = structuredClone(DEFAULT_WATER_REFS);
+
+  return {
+    update: (state) => {
+      // Sync refs from state
+      refs.reflectivity.value = state.reflectivity;
+      refs.uWaterNormalMap.value = state.useWater
+        ? refs.cachedWaterNormalMap.value
+        : null;
+      refs.uWaterScaleNormal.value = state.waterScaleNormal;
+      refs.uWaterSpeed.value = state.waterSpeed;
+      refs.uShininess.value = state.shininess;
+      refs.uSpecularStrength.value = state.specularStrength;
+      // Cast boolean to number for shader uniform
+      refs.uApplyWaterNormal.value = state.applyWaterNormal ? 1 : 0;
+      refs.uSpecular.value = state.specular;
+      refs.uIor.value = state.ior;
+    },
+    updateUniforms: (uniforms) => {
+      // Assign water uniform refs to shader.uniforms
+      uniforms.reflectivity = refs.reflectivity;
+      uniforms.uWaterNormalMap = refs.uWaterNormalMap;
+      uniforms.uWaterScaleNormal = refs.uWaterScaleNormal;
+      uniforms.uWaterSpeed = refs.uWaterSpeed;
+      uniforms.uShininess = refs.uShininess;
+      uniforms.uSpecularStrength = refs.uSpecularStrength;
+      uniforms.uApplyWaterNormal = refs.uApplyWaterNormal;
+      uniforms.uSpecular = refs.uSpecular;
+      uniforms.uIor = refs.uIor;
+      if (refs.uTime) {
+        uniforms.uTime = refs.uTime;
+      }
+      if (refs.tSkyEnvMap) {
+        uniforms.tSkyEnvMap = refs.tSkyEnvMap;
+      }
+    },
+    setWaterNormalMap: (
+      waterNormalMapUniform: UniformValue<Texture | null>,
+      useWater: boolean,
+    ): void => {
+      // Assign external ref object (identity doesn't change after mount)
+      refs.cachedWaterNormalMap = waterNormalMapUniform;
+      refs.uWaterNormalMap.value = useWater
+        ? refs.cachedWaterNormalMap.value
+        : null;
+    },
+    setTimeUniform: (timeUniform: UniformValue<number>): void => {
+      // Assign external ref object (identity doesn't change after mount)
+      refs.uTime = timeUniform;
+    },
+    setSkyEnvMapUniform: (
+      skyEnvMapUniform: UniformValue<Texture | null>,
+    ): void => {
+      // Assign external ref object (identity doesn't change after mount)
+      refs.tSkyEnvMap = skyEnvMapUniform;
+    },
+  };
+};

package/src/material/enhancer/model/modelWaterEnhancer/shader.test.ts

@@ -0,0 +1,34 @@
+import { testShaderCompatibility } from "../../test-utils/shaderCompatibility";
+import {
+  MODEL_BASE_SHADER_MARKERS,
+  createModelBaseEnhancer,
+} from "../modelBaseEnhancer";
+
+import { createModelWaterEnhancer, type SupportedMaterial } from ".";
+
+testShaderCompatibility(
+  "modelWaterEnhancer",
+  (material) =>
+    createModelWaterEnhancer(
+      createModelBaseEnhancer(material as SupportedMaterial),
+    ),
+  [
+    {
+      name: "With water",
+      props: {
+        water: {
+          water: true,
+        },
+      },
+    },
+    {
+      name: "Without water",
+      props: {
+        water: {
+          water: false,
+        },
+      },
+    },
+  ],
+  MODEL_BASE_SHADER_MARKERS,
+);

package/src/material/enhancer/model/modelWaterEnhancer/shader.ts

@@ -0,0 +1,111 @@
+import WaterParsFragment from "@shaders/glsl/chunks/water_pars_fragment.glsl?raw";
+import type { WebGLProgramParametersWithUniforms } from "three";
+
+import {
+  MODEL_BASE_SHADER_MARKERS,
+  createModelBaseShaderReplacer,
+} from "../modelBaseEnhancer/markers";
+
+import type { ModelWaterMutates, ModelWaterState } from "./types";
+
+/**
+ * Transform shader with water-specific modifications.
+ * Uniform assignment is handled by mutates.updateUniforms().
+ */
+export const transformWaterShader = (
+  shader: WebGLProgramParametersWithUniforms,
+  state: ModelWaterState,
+  mutates: ModelWaterMutates,
+): void => {
+  const { useWater } = state;
+
+  // Derive shader defines from semantic state flags
+  shader.defines ??= {};
+  if (useWater) {
+    shader.defines.WATER = 1;
+    if (state.skyEnvMap) {
+      shader.defines.USE_SKY_ENVMAP = "1";
+    }
+  } else {
+    delete shader.defines.WATER;
+  }
+
+  // Assign water uniform refs to shader.uniforms via mutates
+  mutates.updateUniforms(shader.uniforms, state);
+
+  // Insert WaterParsFragment before the computeSpecular function (non-marker-based)
+  const computeSpecularMarker = "vec3 computeSpecular(";
+  const specularIdx = shader.fragmentShader.indexOf(computeSpecularMarker);
+  if (specularIdx !== -1) {
+    const beforeSpecular = shader.fragmentShader.substring(0, specularIdx);
+    const afterSpecular = shader.fragmentShader.substring(specularIdx);
+    shader.fragmentShader =
+      beforeSpecular + WaterParsFragment + "\n\n" + afterSpecular;
+  }
+
+  shader.fragmentShader = createModelBaseShaderReplacer(shader.fragmentShader)
+    // Add water uniform declarations after base's UNIFORM_END
+    .insertAfter(
+      MODEL_BASE_SHADER_MARKERS.fragment.UNIFORM_END,
+      `uniform sampler2D uWaterNormalMap;
+uniform samplerCube tSkyEnvMap;
+uniform float uWaterScaleNormal;
+uniform float uWaterSpeed;
+uniform float uShininess;
+uniform float uSpecularStrength;
+uniform float uApplyWaterNormal;
+uniform bool uSpecular;
+uniform float uIor;
+uniform float uTime;`,
+    )
+    // Replace normal block with water/non-water specular computation
+    .replaceBlock(
+      {
+        start: MODEL_BASE_SHADER_MARKERS.fragment.NORMAL_START,
+        end: MODEL_BASE_SHADER_MARKERS.fragment.NORMAL_END,
+      },
+      `vec3 origNormal = normal;
+vec3 specular;
+
+#ifdef WATER
+  specular = computeWaterSpecularSimple(
+    uWaterNormalMap,
+    vPosition.xy * uWaterScaleNormal,
+    uTime * uWaterSpeed,
+    vViewPosition,
+    uShininess,
+    uSpecularStrength,
+    diffuseColor.rgb,
+    normal
+  );
+#else
+  if(uSpecular) {
+    specular = computeSpecular(
+      vViewPosition,
+      origNormal,
+      uShininess,
+      uSpecularStrength,
+      uIor
+    );
+  }
+  #include <normal_fragment_maps>
+#endif`,
+    )
+    // Replace outgoing light block with env map + specular
+    .insertAfter(
+      MODEL_BASE_SHADER_MARKERS.fragment.OUTGOING_LIGHT_END,
+      `#if defined(WATER) && defined(USE_SKY_ENVMAP)
+  vec3 envColor = getSkyEnv(geometryNormal, tSkyEnvMap, vPosition);
+  outgoingLight += envColor * reflectivity;
+#endif
+outgoingLight += specular;`,
+    )
+    // Replace final normal block with water normal mixing
+    .replaceBlock(
+      {
+        start: MODEL_BASE_SHADER_MARKERS.fragment.FINAL_NORMAL_START,
+        end: MODEL_BASE_SHADER_MARKERS.fragment.FINAL_NORMAL_END,
+      },
+      `vec3 finalNormal = mix(origNormal, normalize(origNormal * 0.7 + normal), uApplyWaterNormal);`,
+    ).source;
+};

package/src/material/enhancer/model/modelWaterEnhancer/state.test.ts

@@ -0,0 +1,105 @@
+import { Texture } from "three";
+import { describe, expect, it } from "vitest";
+
+import { DEFAULT_WATER_STATE, updateWaterState } from "./state";
+import type { ModelWaterState } from "./types";
+
+/**
+ * Helper to create expected water state by merging with defaults.
+ */
+const createExpectedState = (
+  overrides: Partial<ModelWaterState> = {},
+): ModelWaterState => ({
+  ...DEFAULT_WATER_STATE,
+  ...overrides,
+});
+
+describe("modelWaterEnhancer/state", () => {
+  describe("updateWaterState", () => {
+    it("returns default state when given empty props", () => {
+      const result = updateWaterState({}, DEFAULT_WATER_STATE);
+      expect(result).toEqual(createExpectedState());
+    });
+
+    it("applies all props", () => {
+      const mockSkyEnvMap = new Texture();
+
+      const result = updateWaterState(
+        {
+          water: true,
+          waterScaleNormal: 0.5,
+          waterSpeed: 1.0,
+          shininess: 30,
+          specularStrength: 0.8,
+          applyWaterNormal: true,
+          specular: true,
+          ior: 1.5,
+          reflectivity: 0.6,
+          skyEnvMap: mockSkyEnvMap,
+        },
+        DEFAULT_WATER_STATE,
+      );
+
+      expect(result).toEqual(
+        createExpectedState({
+          useWater: true,
+          waterScaleNormal: 0.5,
+          waterSpeed: 1.0,
+          shininess: 30,
+          specularStrength: 0.8,
+          applyWaterNormal: true,
+          specular: true,
+          ior: 1.5,
+          reflectivity: 0.6,
+          skyEnvMap: mockSkyEnvMap,
+        }),
+      );
+    });
+
+    it("falls back to currentState for missing props", () => {
+      const currentState: ModelWaterState = {
+        ...DEFAULT_WATER_STATE,
+        useWater: true,
+        waterScaleNormal: 0.3,
+        shininess: 25,
+      };
+
+      const result = updateWaterState({ waterSpeed: 5.0 }, currentState);
+
+      expect(result.useWater).toBe(true);
+      expect(result.waterScaleNormal).toBe(0.3);
+      expect(result.shininess).toBe(25);
+      expect(result.waterSpeed).toBe(5.0);
+    });
+
+    it("keeps applyWaterNormal as boolean in state", () => {
+      // Boolean values stay as boolean in state (cast to number only in refs)
+      const result1 = updateWaterState(
+        { applyWaterNormal: true },
+        DEFAULT_WATER_STATE,
+      );
+      expect(result1.applyWaterNormal).toBe(true);
+
+      const result2 = updateWaterState(
+        { applyWaterNormal: false },
+        DEFAULT_WATER_STATE,
+      );
+      expect(result2.applyWaterNormal).toBe(false);
+    });
+
+    it("converts numeric applyWaterNormal to boolean (truthy check)", () => {
+      // Numeric values are converted to boolean via !!
+      const result1 = updateWaterState(
+        { applyWaterNormal: 0.5 },
+        DEFAULT_WATER_STATE,
+      );
+      expect(result1.applyWaterNormal).toBe(true); // truthy → true
+
+      const result2 = updateWaterState(
+        { applyWaterNormal: 0 },
+        DEFAULT_WATER_STATE,
+      );
+      expect(result2.applyWaterNormal).toBe(false); // falsy → false
+    });
+  });
+});

package/src/material/enhancer/model/modelWaterEnhancer/state.ts

@@ -0,0 +1,59 @@
+import type { ModelWaterOnlyProps, ModelWaterState } from "./types";
+
+export const DEFAULT_WATER_PROPS: Required<ModelWaterOnlyProps> = {
+  water: false,
+  waterScaleNormal: 0,
+  waterSpeed: 0,
+  shininess: 0,
+  specularStrength: 0,
+  applyWaterNormal: false,
+  specular: false,
+  ior: 1.33333,
+  reflectivity: 0,
+  skyEnvMap: null,
+  waterNormalMap: { value: null },
+  timeUniform: { value: 0 },
+  skyEnvMapUniform: { value: null },
+};
+
+/** Default state derived from DEFAULT_WATER_PROPS */
+export const DEFAULT_WATER_STATE: ModelWaterState = {
+  useWater: DEFAULT_WATER_PROPS.water,
+  skyEnvMap: DEFAULT_WATER_PROPS.skyEnvMap,
+  reflectivity: DEFAULT_WATER_PROPS.reflectivity,
+  waterScaleNormal: DEFAULT_WATER_PROPS.waterScaleNormal,
+  waterSpeed: DEFAULT_WATER_PROPS.waterSpeed,
+  shininess: DEFAULT_WATER_PROPS.shininess,
+  specularStrength: DEFAULT_WATER_PROPS.specularStrength,
+  applyWaterNormal: !!DEFAULT_WATER_PROPS.applyWaterNormal,
+  specular: DEFAULT_WATER_PROPS.specular,
+  ior: DEFAULT_WATER_PROPS.ior,
+};
+
+/**
+ * Update immutable state from props.
+ * Props override currentState values; missing props fall back to currentState.
+ * Pass DEFAULT_WATER_STATE as currentState for initial mount.
+ *
+ * @param props - The props to apply
+ * @param currentState - The current state to use as fallback (use DEFAULT_WATER_STATE for mount)
+ */
+export const updateWaterState = (
+  props: ModelWaterOnlyProps,
+  currentState: ModelWaterState,
+): ModelWaterState => ({
+  useWater: props.water ?? currentState.useWater,
+  skyEnvMap: props.skyEnvMap ?? currentState.skyEnvMap,
+  reflectivity: props.reflectivity ?? currentState.reflectivity,
+  waterScaleNormal: props.waterScaleNormal ?? currentState.waterScaleNormal,
+  waterSpeed: props.waterSpeed ?? currentState.waterSpeed,
+  shininess: props.shininess ?? currentState.shininess,
+  specularStrength: props.specularStrength ?? currentState.specularStrength,
+  // Keep boolean in state - cast to number only in refs
+  applyWaterNormal:
+    props.applyWaterNormal !== undefined
+      ? !!props.applyWaterNormal
+      : currentState.applyWaterNormal,
+  specular: props.specular ?? currentState.specular,
+  ior: props.ior ?? currentState.ior,
+});

package/src/material/enhancer/model/modelWaterEnhancer/types.ts

@@ -0,0 +1,141 @@
+import type { Texture } from "three";
+
+import type { UniformValue } from "../../../types";
+import type { Mutates } from "../../MaterialEnhancer";
+import type {
+  ModelBaseMutates,
+  ModelBaseProps,
+  ModelBaseState,
+} from "../modelBaseEnhancer";
+
+/**
+ * Water-only props (excluding base props).
+ */
+export type ModelWaterOnlyProps = {
+  water?: boolean;
+  waterScaleNormal?: number;
+  waterSpeed?: number;
+  shininess?: number;
+  specularStrength?: number;
+  applyWaterNormal?: number | boolean;
+  specular?: boolean;
+  ior?: number;
+  reflectivity?: number;
+
+  // Sky environment map texture value
+  skyEnvMap?: Texture | null;
+
+  // Water normal map texture (value-based, not ref-based)
+  // This ref identity doesn't change, so we assign the ref object itself
+  waterNormalMap?: UniformValue<Texture | null>;
+
+  // External uniform ref (ref-based, shared with CommonUniforms)
+  // This ref identity doesn't change, so we assign the ref object itself
+  timeUniform?: UniformValue<number>;
+
+  // External uniform ref for sky env map cubemap
+  skyEnvMapUniform?: UniformValue<Texture | null>;
+};
+
+/**
+ * Combined props for the model water enhancer.
+ * Props are explicitly separated into base and water sections for clarity.
+ */
+export type ModelWaterProps = {
+  base?: ModelBaseProps;
+  water?: ModelWaterOnlyProps;
+};
+
+/**
+ * Immutable state for the water enhancer.
+ * This state is always replaced as a whole (never mutated).
+ * Returned directly via states() - refresh after updates.
+ */
+export type ModelWaterState = Readonly<{
+  useWater: boolean;
+  skyEnvMap: Texture | null;
+  reflectivity: number;
+  waterScaleNormal: number;
+  waterSpeed: number;
+  shininess: number;
+  specularStrength: number;
+  applyWaterNormal: boolean;
+  specular: boolean;
+  ior: number;
+}>;
+
+/**
+ * Combined state for the model water enhancer.
+ * Includes both base state and water-specific state.
+ */
+export type ModelWaterCombinedStates = {
+  readonly base: ModelBaseState;
+  readonly water: ModelWaterState;
+};
+
+/**
+ * Combined mutation functions for the model water enhancer.
+ */
+export type ModelWaterCombinedMutates = {
+  readonly base: ModelBaseMutates;
+  readonly water: ModelWaterMutates;
+};
+
+/**
+ * Mutable references (uniforms) for the water enhancer.
+ *
+ * These are shared references with shader.uniforms and can be mutated directly
+ * for efficient GPU uniform updates without shader recompilation.
+ * Internal type - not exposed externally.
+ */
+export type ModelWaterRefs = {
+  // Internal refs (value-based updates)
+  reflectivity: UniformValue<number>;
+  uWaterNormalMap: UniformValue<Texture | null>;
+  cachedWaterNormalMap: UniformValue<Texture | null>;
+  uWaterScaleNormal: UniformValue<number>;
+  uWaterSpeed: UniformValue<number>;
+  uShininess: UniformValue<number>;
+  uSpecularStrength: UniformValue<number>;
+  uApplyWaterNormal: UniformValue<number>;
+  uSpecular: UniformValue<boolean>;
+  uIor: UniformValue<number>;
+
+  // External uniform refs (assigned as ref object, identity doesn't change)
+  uTime?: UniformValue<number>;
+  tSkyEnvMap?: UniformValue<Texture | null>;
+};
+
+export type ModelWaterUniforms = Partial<
+  Omit<ModelWaterRefs, "cachedWaterNormalMap">
+>;
+
+/**
+ * Mutation functions for the water enhancer (internal only).
+ */
+export type ModelWaterMutates = Mutates<
+  ModelWaterState,
+  ModelWaterUniforms,
+  {
+    /**
+     * Set the water normal map uniform ref.
+     * Assigns the external ref object (identity doesn't change after mount).
+     */
+    setWaterNormalMap: (
+      waterNormalMapUniform: UniformValue<Texture | null>,
+      useWater: boolean,
+    ) => void;
+    /**
+     * Set the time uniform ref.
+     * Assigns the external ref object (identity doesn't change after mount).
+     */
+    setTimeUniform: (timeUniform: UniformValue<number>) => void;
+    /**
+     * Set the sky env map uniform ref.
+     * Assigns the external ref object (identity doesn't change after mount).
+     */
+    setSkyEnvMapUniform: (
+      skyEnvMapUniform: UniformValue<Texture | null>,
+    ) => void;
+  }
+>;

package/src/material/enhancer/model/pntsEnhancer/index.test.ts

@@ -0,0 +1,96 @@
+import { PointsMaterial } from "three";
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { createPntsEnhancer } from ".";
+
+describe("pntsEnhancer", () => {
+  let enhancer: ReturnType<typeof createPntsEnhancer>;
+
+  beforeEach(() => {
+    enhancer = createPntsEnhancer(new PointsMaterial());
+  });
+
+  describe("lifecycle", () => {
+    it("states() should throw if called before mount", () => {
+      const freshEnhancer = createPntsEnhancer(new PointsMaterial());
+      expect(() => freshEnhancer.states()).toThrow(
+        "mount() must be called before states",
+      );
+    });
+
+    it("mutates() should throw if called before mount", () => {
+      const freshEnhancer = createPntsEnhancer(new PointsMaterial());
+      expect(() => freshEnhancer.mutates()).toThrow(
+        "mount() must be called before mutates",
+      );
+    });
+
+    it("update() should throw if called before mount", () => {
+      const freshEnhancer = createPntsEnhancer(new PointsMaterial());
+      expect(() => freshEnhancer.update({})).toThrow(
+        "mount() must be called before update",
+      );
+    });
+  });
+
+  describe("mount", () => {
+    it("should initialize state with provided props", () => {
+      enhancer.mount({
+        height: 100,
+        geodeticNormal: { x: 0.1, y: 0.2, z: 0.3 },
+      });
+
+      const state = enhancer.states();
+      expect(state.height).toBe(100);
+      expect(state.geodeticNormal).toEqual({ x: 0.1, y: 0.2, z: 0.3 });
+    });
+
+    it("should use defaults for missing props", () => {
+      enhancer.mount({});
+
+      const state = enhancer.states();
+      expect(state.height).toBe(0);
+      expect(state.geodeticNormal).toEqual({ x: 0, y: 0, z: 0 });
+    });
+  });
+
+  describe("update", () => {
+    it("should update state with new props", () => {
+      enhancer.mount({ height: 50 });
+      enhancer.update({ height: 200 });
+
+      const state = enhancer.states();
+      expect(state.height).toBe(200);
+    });
+
+    it("should preserve state for missing props", () => {
+      enhancer.mount({
+        height: 100,
+        geodeticNormal: { x: 1, y: 0, z: 0 },
+      });
+      enhancer.update({ height: 200 });
+
+      const state = enhancer.states();
+      expect(state.height).toBe(200);
+      expect(state.geodeticNormal).toEqual({ x: 1, y: 0, z: 0 });
+    });
+  });
+
+  describe("programCacheKey", () => {
+    it("should return empty string (no shader-affecting state)", () => {
+      enhancer.mount({});
+      expect(enhancer.programCacheKey()).toBe("");
+    });
+
+    it("should return same key regardless of state", () => {
+      enhancer.mount({ height: 100 });
+      const key1 = enhancer.programCacheKey();
+
+      const enhancer2 = createPntsEnhancer(new PointsMaterial());
+      enhancer2.mount({ height: 200 });
+      const key2 = enhancer2.programCacheKey();
+
+      expect(key1).toBe(key2);
+    });
+  });
+});