@navaramap/three 0.0.0

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

@@ -0,0 +1,52 @@
+import type { ModelBaseProps, ModelBaseState } from "./types";
+
+export const DEFAULT_BASE_PROPS: Required<
+  Omit<ModelBaseProps, "batchDataTexture">
+> = {
+  color: 0,
+  metalness: 0,
+  roughness: 0,
+  transparent: false,
+  opacity: 1.0,
+  depthWrite: true,
+  emissiveColor: 0,
+  emissiveIntensity: 0,
+  pickable: false,
+  effectIdsMask: 0,
+  batchColorEnabled: false,
+  useBatchTexture: false,
+  useBatchColorShow: false,
+};
+
+/** Default state derived from DEFAULT_BASE_PROPS */
+export const DEFAULT_BASE_STATE: ModelBaseState = {
+  pickable: DEFAULT_BASE_PROPS.pickable,
+  emissiveColor: DEFAULT_BASE_PROPS.emissiveColor,
+  emissiveIntensity: DEFAULT_BASE_PROPS.emissiveIntensity,
+  effectIdsMask: 0,
+  batchColorEnabled: DEFAULT_BASE_PROPS.batchColorEnabled,
+  useBatchTexture: DEFAULT_BASE_PROPS.useBatchTexture,
+  useBatchColorShow: DEFAULT_BASE_PROPS.useBatchColorShow,
+};
+
+/**
+ * Update immutable state from props.
+ * Props override currentState values; missing props fall back to currentState.
+ * Pass DEFAULT_BASE_STATE as currentState for initial mount.
+ *
+ * @param props - The props to apply
+ * @param currentState - The current state to use as fallback (use DEFAULT_BASE_STATE for mount)
+ */
+export const updateState = (
+  props: ModelBaseProps,
+  currentState: ModelBaseState,
+): ModelBaseState => ({
+  pickable: props.pickable ?? currentState.pickable,
+  emissiveColor: props.emissiveColor ?? currentState.emissiveColor,
+  emissiveIntensity: props.emissiveIntensity ?? currentState.emissiveIntensity,
+  effectIdsMask: props.effectIdsMask ?? currentState.effectIdsMask,
+  // Batch flags can only transition from false to true, never back
+  batchColorEnabled: props.batchColorEnabled ?? currentState.batchColorEnabled,
+  useBatchTexture: props.useBatchTexture ?? currentState.useBatchTexture,
+  useBatchColorShow: props.useBatchColorShow ?? currentState.useBatchColorShow,
+});

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

@@ -0,0 +1,89 @@
+import type { Texture } from "three";
+
+import type { UniformValue } from "../../../types";
+import type { BatchTextureFlags } from "../../batchTexture";
+import type { Mutates } from "../../MaterialEnhancer";
+
+type ModelBatchTextureFlags = Required<
+  Pick<BatchTextureFlags, "useBatchTexture" | "useBatchColorShow">
+>;
+
+/**
+ * Props for the model base enhancer.
+ */
+export type ModelBaseProps = {
+  // Basic material props
+  color?: number;
+  metalness?: number;
+  roughness?: number;
+
+  transparent?: boolean;
+  opacity?: number;
+  depthWrite?: boolean;
+
+  // Emissive (for selective effects)
+  emissiveColor?: number;
+  emissiveIntensity?: number;
+
+  // Picking
+  pickable?: boolean;
+
+  // Selective Effect
+  effectIdsMask?: number;
+
+  // Batch texture
+  batchDataTexture?: UniformValue<Texture | null>;
+
+  // When batchColorEnabled is true, material.color is set to white and actual colors come from batch texture
+  batchColorEnabled?: boolean;
+} & Partial<ModelBatchTextureFlags>;
+
+/**
+ * Immutable state for the model base enhancer.
+ * This state is always replaced as a whole (never mutated).
+ * Returned directly via states() - refresh after updates.
+ */
+export type ModelBaseState = Readonly<
+  {
+    pickable: boolean;
+    emissiveColor: number;
+    emissiveIntensity: number;
+    effectIdsMask: number;
+    // Batch texture state - when true, material.color is white and colors come from batch texture
+    batchColorEnabled: boolean;
+  } & ModelBatchTextureFlags
+>;
+
+/**
+ * Mutable references (uniforms) for the model base 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 ModelBaseRefs = {
+  nvr_uPickable: UniformValue<number>;
+  uEffectIdsMask: UniformValue<number>;
+  uEmissiveIntensity: UniformValue<number>;
+
+  // Optional uniforms
+  batchDataTexture?: UniformValue<Texture | null>;
+};
+
+export type ModelBaseUniforms = Partial<ModelBaseRefs>;
+
+/**
+ * Mutation functions for the model base enhancer.
+ * Includes `update(state)` to sync refs from state, plus additional methods.
+ */
+export type ModelBaseMutates = Mutates<
+  ModelBaseState,
+  ModelBaseUniforms,
+  {
+    /**
+     * Set the batch data texture ref.
+     * This is needed because batchDataTexture is an external ref passed via props.
+     */
+    setBatchDataTexture: (texture: UniformValue<Texture | null>) => void;
+  }
+>;

package/src/material/enhancer/model/modelMaterialEnhancer.ts

@@ -0,0 +1,91 @@
+/**
+ * Model Material Enhancer - Composed from Base + Water enhancers
+ *
+ * This module provides the full model material functionality by using
+ * the water enhancer factory which internally composes with the base enhancer.
+ */
+
+import type { MaterialEnhancer } from "../MaterialEnhancer";
+
+import {
+  createModelBaseEnhancer,
+  type ModelBaseMutates,
+  type ModelBaseProps,
+  type ModelBaseState,
+} from "./modelBaseEnhancer";
+import {
+  createModelWaterEnhancer,
+  type ModelWaterCombinedMutates,
+  type ModelWaterCombinedStates,
+  type ModelWaterOnlyProps,
+  type ModelWaterProps,
+  type ModelWaterState,
+  type AVAILABLE_SHADERS as WATER_AVAILABLE_SHADERS,
+  type SupportedMaterial as WaterSupportedMaterial,
+} from "./modelWaterEnhancer";
+
+/**
+ * Combined props for the model material enhancer.
+ * Props are explicitly separated into base and water sections for clarity.
+ */
+export type ModelMaterialProps = {
+  base?: ModelBaseProps;
+  water?: ModelWaterOnlyProps;
+};
+
+// Shaders this enhancer supports
+type AVAILABLE_SHADERS = typeof WATER_AVAILABLE_SHADERS;
+type SupportedMaterial = WaterSupportedMaterial;
+
+/**
+ * Factory function to create the model material enhancer.
+ *
+ * This creates a new enhancer instance with its own internal state.
+ *
+ * @param material - The Three.js material to enhance
+ *
+ * @example
+ * ```typescript
+ * const material = new MeshStandardMaterial();
+ * const enhancer = createModelMaterialEnhancer(material);
+ *
+ * // Mount with separated base and water props
+ * enhancer.mount({
+ *   base: { color: 0xff0000, metalness: 0.5 },
+ *   water: { water: true, waterScaleNormal: 0.01 },
+ * });
+ *
+ * // Get state directly via states() - refresh after updates
+ * const { base, water } = enhancer.states();
+ *
+ * // Update props (then call states() again to get fresh state)
+ * enhancer.update({ base: { height: 100 } });
+ *
+ * // Use transformShader for onBeforeCompile
+ * material.onBeforeCompile = enhancer.transformShader;
+ * ```
+ */
+export function createModelMaterialEnhancer(
+  material: SupportedMaterial,
+): MaterialEnhancer<
+  SupportedMaterial,
+  ModelMaterialProps,
+  ModelWaterCombinedStates,
+  ModelWaterCombinedMutates,
+  AVAILABLE_SHADERS
+> {
+  const baseEnhancer = createModelBaseEnhancer(material);
+  return createModelWaterEnhancer(baseEnhancer);
+}
+
+// Re-export types for convenience
+export type {
+  ModelBaseMutates,
+  ModelBaseProps,
+  ModelBaseState,
+  ModelWaterCombinedMutates,
+  ModelWaterCombinedStates,
+  ModelWaterOnlyProps,
+  ModelWaterProps,
+  ModelWaterState,
+};

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

@@ -0,0 +1,71 @@
+import { MeshStandardMaterial } from "three";
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { createModelBaseEnhancer } from "../modelBaseEnhancer";
+
+import { createModelWaterEnhancer } from ".";
+
+describe("modelWaterEnhancer", () => {
+  let enhancer: ReturnType<typeof createModelWaterEnhancer>;
+
+  beforeEach(() => {
+    const baseEnhancer = createModelBaseEnhancer(new MeshStandardMaterial());
+    enhancer = createModelWaterEnhancer(baseEnhancer);
+  });
+
+  describe("lifecycle", () => {
+    it("states() should throw if called before mount", () => {
+      const freshMaterial = new MeshStandardMaterial();
+      const baseEnhancer = createModelBaseEnhancer(freshMaterial);
+      const freshEnhancer = createModelWaterEnhancer(baseEnhancer);
+
+      expect(() => freshEnhancer.states()).toThrow(
+        "mount() must be called before states",
+      );
+    });
+  });
+
+  describe("programCacheKey", () => {
+    it("should combine base cache key with water-specific state", () => {
+      enhancer.mount({
+        base: { useBatchTexture: true },
+        water: { water: true },
+      });
+
+      const cacheKey = enhancer.programCacheKey();
+
+      expect(cacheKey).toContain('"useBatchTexture":true');
+      expect(cacheKey).toContain('"useWater":true');
+    });
+
+    it("should return different cache keys when useWater differs", () => {
+      enhancer.mount({ water: { water: false } });
+      const cacheKey1 = enhancer.programCacheKey();
+
+      const enhancer2 = createModelWaterEnhancer(
+        createModelBaseEnhancer(new MeshStandardMaterial()),
+      );
+      enhancer2.mount({ water: { water: true } });
+      const cacheKey2 = enhancer2.programCacheKey();
+
+      expect(cacheKey1).not.toBe(cacheKey2);
+    });
+
+    it("should return same cache key for same shader-affecting states with different non-affecting states", () => {
+      enhancer.mount({
+        water: { water: true, waterSpeed: 1.0, shininess: 10 },
+      });
+      const cacheKey1 = enhancer.programCacheKey();
+
+      const enhancer2 = createModelWaterEnhancer(
+        createModelBaseEnhancer(new MeshStandardMaterial()),
+      );
+      enhancer2.mount({
+        water: { water: true, waterSpeed: 5.0, shininess: 50 },
+      });
+      const cacheKey2 = enhancer2.programCacheKey();
+
+      expect(cacheKey1).toBe(cacheKey2);
+    });
+  });
+});

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

@@ -0,0 +1,175 @@
+import { defaults } from "lodash-es";
+import type { WebGLProgramParametersWithUniforms } from "three";
+import invariant from "tiny-invariant";
+
+import type { MaterialEnhancer } from "../../MaterialEnhancer";
+import type {
+  ModelBaseMutates,
+  ModelBaseProps,
+  ModelBaseState,
+  SupportedMaterial,
+} from "../modelBaseEnhancer";
+
+import {
+  AVAILABLE_SHADERS,
+  type SupportedMaterial as WaterSupportedMaterial,
+} from "./material";
+import { applyWaterMaterialConfig } from "./material";
+import { createWaterMutates } from "./mutates";
+import { transformWaterShader } from "./shader";
+import {
+  DEFAULT_WATER_PROPS,
+  DEFAULT_WATER_STATE,
+  updateWaterState,
+} from "./state";
+import type {
+  ModelWaterCombinedMutates,
+  ModelWaterCombinedStates,
+  ModelWaterMutates,
+  ModelWaterOnlyProps,
+  ModelWaterProps,
+  ModelWaterState,
+} from "./types";
+
+/**
+ * Factory function to create a model water enhancer.
+ *
+ * @param baseEnhancer - The base model enhancer to compose with (material is obtained from this)
+ * @returns A new MaterialEnhancer with combined base + water functionality
+ */
+export function createModelWaterEnhancer(
+  baseEnhancer: MaterialEnhancer<
+    SupportedMaterial,
+    ModelBaseProps,
+    ModelBaseState,
+    ModelBaseMutates,
+    typeof AVAILABLE_SHADERS
+  >,
+): MaterialEnhancer<
+  WaterSupportedMaterial,
+  ModelWaterProps,
+  ModelWaterCombinedStates,
+  ModelWaterCombinedMutates,
+  typeof AVAILABLE_SHADERS
+> {
+  const { material } = baseEnhancer;
+  // Internal state - immutable, always replaced as a whole
+  let state: ModelWaterState | null = null;
+  // Internal mutates object (refs are hidden inside)
+  let mutates: ModelWaterMutates | null = null;
+
+  return {
+    material: material as WaterSupportedMaterial,
+    availableShaders: AVAILABLE_SHADERS,
+
+    transformShader: (shader: WebGLProgramParametersWithUniforms): void => {
+      invariant(
+        state && mutates,
+        "mount() must be called before transformShader",
+      );
+      // First apply base transformations
+      baseEnhancer.transformShader(shader);
+      // Then apply water transformations
+      transformWaterShader(shader, state, mutates);
+    },
+
+    mount: (props: ModelWaterProps): void => {
+      // Mount base enhancer first with base props
+      baseEnhancer.mount(props.base ?? {});
+
+      // Initialize water state and mutates with water props
+      const waterProps = props.water ?? {};
+      const mergedWaterProps = defaults({}, waterProps, DEFAULT_WATER_PROPS);
+      state = updateWaterState(mergedWaterProps, DEFAULT_WATER_STATE);
+      // Create mutates (refs are created inside with default values)
+      mutates = createWaterMutates();
+      mutates.update(state);
+      // Handle external refs (identity doesn't change after mount)
+      if (waterProps.waterNormalMap) {
+        mutates.setWaterNormalMap(waterProps.waterNormalMap, state.useWater);
+      }
+      if (waterProps.timeUniform) {
+        mutates.setTimeUniform(waterProps.timeUniform);
+      }
+      if (waterProps.skyEnvMapUniform) {
+        mutates.setSkyEnvMapUniform(waterProps.skyEnvMapUniform);
+      }
+
+      // Apply material configuration (side effect)
+      applyWaterMaterialConfig(
+        material as WaterSupportedMaterial,
+        state,
+        false,
+      );
+    },
+
+    update: (props: ModelWaterProps): void => {
+      // Update base enhancer first with base props
+      if (props.base) {
+        baseEnhancer.update(props.base);
+      }
+
+      invariant(state && mutates, "mount() must be called before update");
+
+      // Update water state and refs with water props
+      if (props.water) {
+        const prevUseWater = state.useWater;
+        state = updateWaterState(props.water, state);
+        mutates.update(state);
+        // Handle external refs (identity doesn't change, only set once)
+        if (props.water.timeUniform) {
+          mutates.setTimeUniform(props.water.timeUniform);
+        }
+        if (props.water.skyEnvMapUniform) {
+          mutates.setSkyEnvMapUniform(props.water.skyEnvMapUniform);
+        }
+
+        // Apply material configuration (side effect)
+        applyWaterMaterialConfig(
+          material as WaterSupportedMaterial,
+          state,
+          prevUseWater,
+        );
+      }
+    },
+
+    states: (): ModelWaterCombinedStates => {
+      invariant(state, "mount() must be called before states");
+      return {
+        base: baseEnhancer.states(),
+        water: state,
+      };
+    },
+
+    mutates: (): ModelWaterCombinedMutates => {
+      invariant(mutates, "mount() must be called before mutates");
+      return {
+        base: baseEnhancer.mutates(),
+        water: mutates,
+      };
+    },
+
+    programCacheKey: (): string => {
+      invariant(state, "mount() must be called before programCacheKey");
+      // Combine base cache key with water-specific state
+      return (
+        baseEnhancer.programCacheKey() +
+        JSON.stringify({
+          useWater: state.useWater,
+        })
+      );
+    },
+  };
+}
+
+// Re-export public types
+export type {
+  ModelWaterCombinedMutates,
+  ModelWaterCombinedStates,
+  ModelWaterMutates,
+  ModelWaterOnlyProps,
+  ModelWaterProps,
+  ModelWaterState,
+  AVAILABLE_SHADERS,
+  SupportedMaterial,
+};

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

@@ -0,0 +1,48 @@
+import { MeshStandardMaterial } from "three";
+import { describe, expect, it } from "vitest";
+
+import { applyWaterMaterialConfig } from "./material";
+import { DEFAULT_WATER_STATE } from "./state";
+import type { ModelWaterState } from "./types";
+
+describe("modelWaterEnhancer/material", () => {
+  describe("applyWaterMaterialConfig", () => {
+    it("should trigger material.needsUpdate when water flag changes", () => {
+      const material = new MeshStandardMaterial();
+      const state: ModelWaterState = {
+        ...DEFAULT_WATER_STATE,
+        useWater: true,
+      };
+
+      let needsUpdateCalled = false;
+      Object.defineProperty(material, "needsUpdate", {
+        set: (value: boolean) => {
+          if (value) needsUpdateCalled = true;
+        },
+        configurable: true,
+      });
+
+      applyWaterMaterialConfig(material, state, false);
+      expect(needsUpdateCalled).toBe(true);
+    });
+
+    it("should not trigger material.needsUpdate when water flag stays the same", () => {
+      const material = new MeshStandardMaterial();
+      const state: ModelWaterState = {
+        ...DEFAULT_WATER_STATE,
+        useWater: true,
+      };
+
+      let needsUpdateCalled = false;
+      Object.defineProperty(material, "needsUpdate", {
+        set: (value: boolean) => {
+          if (value) needsUpdateCalled = true;
+        },
+        configurable: true,
+      });
+
+      applyWaterMaterialConfig(material, state, true);
+      expect(needsUpdateCalled).toBe(false);
+    });
+  });
+});

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

@@ -0,0 +1,25 @@
+import type { MaterialsFromShaders, ShaderName } from "../../MaterialEnhancer";
+
+import type { ModelWaterState } from "./types";
+
+// Shaders this enhancer supports
+export const AVAILABLE_SHADERS = [
+  "standard",
+  "physical",
+] satisfies ShaderName[];
+export type SupportedMaterial = MaterialsFromShaders<typeof AVAILABLE_SHADERS>;
+
+/**
+ * Apply water-related material configuration.
+ * Side effect function - mutates material directly.
+ */
+export const applyWaterMaterialConfig = (
+  material: SupportedMaterial,
+  state: ModelWaterState,
+  prevUseWater: boolean,
+): void => {
+  // Trigger shader recompilation if water flag changed
+  if (state.useWater !== prevUseWater) {
+    material.needsUpdate = true;
+  }
+};

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

@@ -0,0 +1,89 @@
+import type { Texture } from "three";
+import { describe, expect, it } from "vitest";
+
+import type { ShaderUniforms } from "../../MaterialEnhancer";
+
+import { createWaterMutates } from "./mutates";
+import { DEFAULT_WATER_STATE } from "./state";
+import type { ModelWaterState } from "./types";
+
+describe("modelWaterEnhancer/mutates", () => {
+  describe("setWaterNormalMap", () => {
+    it("should set uWaterNormalMap when useWater is true", () => {
+      const mutates = createWaterMutates();
+      const mockTexture = {} as Texture;
+      const waterNormalMapUniform = { value: mockTexture };
+      const state: ModelWaterState = { ...DEFAULT_WATER_STATE, useWater: true };
+
+      mutates.setWaterNormalMap(waterNormalMapUniform, true);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uWaterNormalMap?.value).toBe(mockTexture);
+    });
+
+    it("should set uWaterNormalMap to null when useWater is false", () => {
+      const mutates = createWaterMutates();
+      const mockTexture = {} as Texture;
+      const waterNormalMapUniform = { value: mockTexture };
+      const state: ModelWaterState = {
+        ...DEFAULT_WATER_STATE,
+        useWater: false,
+      };
+
+      mutates.setWaterNormalMap(waterNormalMapUniform, false);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uWaterNormalMap?.value).toBe(null);
+    });
+  });
+
+  describe("update", () => {
+    it("should keep uWaterNormalMap when useWater is true", () => {
+      const mutates = createWaterMutates();
+      const mockTexture = {} as Texture;
+      const waterNormalMapUniform = { value: mockTexture };
+
+      // First set the water normal map with useWater false
+      mutates.setWaterNormalMap(waterNormalMapUniform, false);
+
+      // Then update with useWater true
+      const state: ModelWaterState = {
+        ...DEFAULT_WATER_STATE,
+        useWater: true,
+      };
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      mutates.update(state);
+
+      expect(uniforms.uWaterNormalMap?.value).toBe(mockTexture);
+    });
+
+    it("should clear uWaterNormalMap when useWater becomes false", () => {
+      const mutates = createWaterMutates();
+      const mockTexture = {} as Texture;
+      const waterNormalMapUniform = { value: mockTexture };
+
+      // First set the water normal map with useWater true
+      mutates.setWaterNormalMap(waterNormalMapUniform, true);
+
+      // Then update with useWater false
+      const state: ModelWaterState = {
+        ...DEFAULT_WATER_STATE,
+        useWater: false,
+      };
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      mutates.update(state);
+
+      expect(uniforms.uWaterNormalMap?.value).toBe(null);
+    });
+  });
+});