@navaramap/three 0.0.0

package/src/material/enhancer/MaterialEnhancer.ts

@@ -0,0 +1,112 @@
+import {
+  MeshBasicMaterial,
+  MeshLambertMaterial,
+  MeshPhongMaterial,
+  MeshPhysicalMaterial,
+  MeshStandardMaterial,
+  PointsMaterial,
+  ShaderMaterial,
+  type Material,
+  type WebGLProgramParametersWithUniforms,
+} from "three";
+import { ShaderLib as ThreeShaderLib } from "three";
+
+// Re-export ShaderLib for convenience
+export const ShaderLib = ThreeShaderLib;
+
+// Mapping from shader names to their corresponding material classes
+type ShaderToMaterial = {
+  basic: MeshBasicMaterial;
+  lambert: MeshLambertMaterial;
+  phong: MeshPhongMaterial;
+  standard: MeshStandardMaterial;
+  physical: MeshPhysicalMaterial;
+  points: PointsMaterial;
+  shader: ShaderMaterial;
+};
+
+// All shader names that have material mappings
+export type ShaderName = keyof ShaderToMaterial;
+
+// Helper type: Extract material union from shader name array
+export type MaterialsFromShaders<S extends readonly ShaderName[]> =
+  ShaderToMaterial[S[number]];
+
+/**
+ * Type alias for shader uniforms.
+ */
+export type ShaderUniforms = WebGLProgramParametersWithUniforms["uniforms"];
+
+/**
+ * Generic Mutates type - refs must be updated by states.
+ * All mutates have:
+ * - `update(state)`: Syncs internal refs from state
+ * - `updateUniforms(uniforms, state)`: Assigns internal refs to shader.uniforms
+ * Additional methods can be added via the Methods type parameter.
+ */
+export type Mutates<
+  States,
+  Uniforms extends ShaderUniforms,
+  Methods extends Record<string, (...args: never[]) => void> = Record<
+    never,
+    never
+  >,
+> = {
+  update: (states: States) => void;
+  updateUniforms: (uniforms: Uniforms, states: States) => void;
+} & Methods;
+
+/**
+ * Core abstraction: Material enhancer with shader type constraints
+ *
+ * A MaterialEnhancer encapsulates a single material feature and declares which shaders it supports.
+ *
+ * The enhancer separates concerns into three categories:
+ * - **State** (immutable): Configuration flags and values that define behavior.
+ *   Always replaced as a whole when updated (never mutated). Returned directly via `states()`.
+ * - **Refs** (mutable, internal): Uniform value objects (`{ value: T }`) that are shared
+ *   references with shader.uniforms. Hidden inside mutates, synced from state via `mutates().update(state)`.
+ * - **Mutates** (mutation functions): Functions exposed via `mutates()` for controlled
+ *   mutation of internal refs. Always includes `update(state)` to sync refs from state.
+ *
+ * The material is passed to the factory function when creating the enhancer,
+ * and is exposed via the `material` property for composed enhancers to reference.
+ */
+export type MaterialEnhancer<
+  M extends Material,
+  Props,
+  States = unknown,
+  Mutates = unknown,
+  Shaders extends readonly ShaderName[] = readonly ShaderName[],
+> = {
+  /** The Three.js material being enhanced */
+  readonly material: M;
+  /** Declares which shaders this enhancer is compatible with */
+  readonly availableShaders: Shaders;
+  /** Called once during shader compilation - assigns internal refs to shader.uniforms */
+  transformShader: (shader: WebGLProgramParametersWithUniforms) => void;
+  /** Called once after creation - initializes internal state with props */
+  mount: (props: Props) => void;
+  /** Called on every props update - updates internal state and refs */
+  update: (props: Props) => void;
+  /** Get the current state directly (no getters - refresh after updates) */
+  states: () => States;
+  /** Get mutation functions for controlled updates to internal refs */
+  mutates: () => Mutates;
+  /** Returns cache key based on state affecting shader defines. Used with material.customProgramCacheKey */
+  programCacheKey: () => string;
+};
+
+/** Enhanced material wrapper */
+export type EnhancedMaterial<
+  M extends Material,
+  Props,
+  States = unknown,
+  Mutates = unknown,
+> = {
+  material: M;
+  mount: (props: Props) => void;
+  update: (props: Props) => void;
+  states: () => States;
+  mutates: () => Mutates;
+};

package/src/material/enhancer/ShaderReplacer.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  ShaderReplacer,
+  createShaderReplacer,
+  type ShaderMarkers,
+} from "./ShaderReplacer";
+
+const MARKERS = {
+  vertex: {
+    START: "// MARKER_START",
+    END: "// MARKER_END",
+  },
+  fragment: {},
+} satisfies ShaderMarkers;
+
+type TestMarkers = typeof MARKERS;
+
+describe("ShaderReplacer", () => {
+  const baseSource = [
+    "line1",
+    MARKERS.vertex.START,
+    "content",
+    MARKERS.vertex.END,
+    "line2",
+  ].join("\n");
+
+  describe("insertBefore", () => {
+    it("should insert code before the marker and preserve the marker", () => {
+      const replacer = new ShaderReplacer<TestMarkers>(baseSource);
+      replacer.insertBefore(MARKERS.vertex.START, "inserted");
+
+      expect(replacer.source).toContain(`inserted\n${MARKERS.vertex.START}`);
+    });
+
+    it("should throw when marker is not found", () => {
+      const replacer = new ShaderReplacer<TestMarkers>("no markers here");
+      expect(() =>
+        replacer.insertBefore(MARKERS.vertex.START, "code"),
+      ).toThrow();
+    });
+  });
+
+  describe("insertAfter", () => {
+    it("should insert code after the marker and preserve the marker", () => {
+      const replacer = new ShaderReplacer<TestMarkers>(baseSource);
+      replacer.insertAfter(MARKERS.vertex.END, "inserted");
+
+      expect(replacer.source).toContain(`${MARKERS.vertex.END}\ninserted`);
+    });
+
+    it("should throw when marker is not found", () => {
+      const replacer = new ShaderReplacer<TestMarkers>("no markers here");
+      expect(() => replacer.insertAfter(MARKERS.vertex.END, "code")).toThrow();
+    });
+  });
+
+  describe("replaceBlock", () => {
+    it("should replace content between markers and preserve markers", () => {
+      const replacer = new ShaderReplacer<TestMarkers>(baseSource);
+      replacer.replaceBlock(
+        { start: MARKERS.vertex.START, end: MARKERS.vertex.END },
+        "REPLACED",
+      );
+
+      expect(replacer.source).toContain(`${MARKERS.vertex.START}
+REPLACED
+${MARKERS.vertex.END}`);
+      expect(replacer.source).not.toContain("content");
+    });
+
+    it("should throw when start marker is not found", () => {
+      const replacer = new ShaderReplacer<TestMarkers>("no markers here");
+      expect(() =>
+        replacer.replaceBlock(
+          { start: MARKERS.vertex.START, end: MARKERS.vertex.END },
+          "code",
+        ),
+      ).toThrow("start marker");
+    });
+
+    it("should throw when end marker is not found", () => {
+      const source = `before\n${MARKERS.vertex.START}\nno end`;
+      const replacer = new ShaderReplacer<TestMarkers>(source);
+      expect(() =>
+        replacer.replaceBlock(
+          { start: MARKERS.vertex.START, end: MARKERS.vertex.END },
+          "code",
+        ),
+      ).toThrow("end marker");
+    });
+  });
+
+  describe("chaining", () => {
+    it("should support chaining multiple operations", () => {
+      const replacer = new ShaderReplacer<TestMarkers>(baseSource);
+      const result = replacer
+        .insertBefore(MARKERS.vertex.START, "before_start")
+        .insertAfter(MARKERS.vertex.END, "after_end");
+
+      expect(result).toBe(replacer);
+      expect(replacer.source).toContain("before_start");
+      expect(replacer.source).toContain("after_end");
+    });
+  });
+
+  describe("createShaderReplacer", () => {
+    it("should create a ShaderReplacer instance", () => {
+      const replacer = createShaderReplacer<TestMarkers>(baseSource);
+      expect(replacer).toBeInstanceOf(ShaderReplacer);
+      expect(replacer.source).toBe(baseSource);
+    });
+  });
+});

package/src/material/enhancer/ShaderReplacer.ts

@@ -0,0 +1,97 @@
+import { replaceOrThrow } from "../../utils/replacer";
+
+/**
+ * Common type for organizing shader markers by shader stage.
+ */
+export type ShaderMarkers = {
+  readonly vertex: Record<string, string>;
+  readonly fragment: Record<string, string>;
+};
+
+type PickMarker<Markers extends ShaderMarkers, Key extends keyof Markers> = {
+  [VK in keyof Markers[Key]]: Markers[Key][VK];
+}[keyof Markers[Key]];
+
+type PickMarkers<Markers extends ShaderMarkers> =
+  | PickMarker<Markers, "vertex">
+  | PickMarker<Markers, "fragment">;
+
+/**
+ * A type-safe shader string replacer that restricts operations to declared markers.
+ *
+ * Each enhancer level declares its own markers and exposes a factory function
+ * that returns a ShaderReplacer typed to those markers. Composing enhancers
+ * use the parent's factory to safely modify shader code at known insertion points.
+ *
+ * @template Markers - Union of allowed marker strings
+ */
+export class ShaderReplacer<
+  AllMarkers extends ShaderMarkers,
+  Markers extends string = PickMarkers<AllMarkers>,
+> {
+  private _source: string;
+
+  constructor(source: string) {
+    this._source = source;
+  }
+
+  get source(): string {
+    return this._source;
+  }
+
+  /**
+   * Insert code before the target marker.
+   * The target marker is preserved.
+   */
+  insertBefore(marker: Markers, code: string): this {
+    this._source = replaceOrThrow(this._source, marker, `${code}\n${marker}`);
+    return this;
+  }
+
+  /**
+   * Insert code after the target marker.
+   * The target marker is preserved.
+   */
+  insertAfter(marker: Markers, code: string): this {
+    this._source = replaceOrThrow(this._source, marker, `${marker}\n${code}`);
+    return this;
+  }
+
+  /**
+   * Replace the content between start and end markers with the given code.
+   * The markers themselves are preserved.
+   */
+  replaceBlock(
+    position: { readonly start: Markers; readonly end: Markers },
+    code: string,
+  ): this {
+    const { start, end } = position;
+
+    const startIdx = this._source.indexOf(start);
+    if (startIdx === -1) {
+      throw new Error(`Failed to find start marker "${start}" in shader code.`);
+    }
+    const endIdx = this._source.indexOf(end);
+    if (endIdx === -1) {
+      throw new Error(`Failed to find end marker "${end}" in shader code.`);
+    }
+    this._source =
+      this._source.substring(0, startIdx) +
+      start +
+      "\n" +
+      code +
+      "\n" +
+      end +
+      this._source.substring(endIdx + end.length);
+    return this;
+  }
+}
+
+/**
+ * Create a ShaderReplacer typed to the given marker union.
+ */
+export function createShaderReplacer<AllMarkers extends ShaderMarkers>(
+  source: string,
+) {
+  return new ShaderReplacer<AllMarkers>(source);
+}

package/src/material/enhancer/batchTexture.ts

@@ -0,0 +1,8 @@
+export type BatchTextureFlags = {
+  useBatchTexture?: boolean;
+  useBatchColorShow?: boolean; // Note: opacity is bundled with show in COLOR_SHOW's alpha channel
+  useBatchHeight?: boolean;
+  useBatchExtrudedHeight?: boolean;
+  useBatchLineWidth?: boolean;
+  useBatchSize?: boolean;
+};

package/src/material/enhancer/index.ts

@@ -0,0 +1,46 @@
+export { ShaderLib } from "./MaterialEnhancer";
+export type {
+  EnhancedMaterial,
+  MaterialEnhancer,
+  MaterialsFromShaders,
+  Mutates,
+  ShaderName,
+} from "./MaterialEnhancer";
+
+// Polygon enhancers
+export { createPolygonMaterialEnhancer } from "./polygon";
+export type { PolygonMaterialProps } from "./polygon";
+
+// Shadow map depth enhancers
+export { createShadowMapDepthEnhancer } from "./shadowMap";
+export type {
+  ShadowMapDepthProps,
+  ShadowMapDepthSupportedMaterial,
+} from "./shadowMap";
+
+// Polyline enhancers
+export { createPolylineMaterialEnhancer } from "./polyline";
+export type {
+  PolylineMaterialProps,
+  PolylineBaseMutates,
+  PolylineBaseProps,
+  PolylineBaseState,
+} from "./polyline";
+
+// InstancedSprite enhancers
+export { createInstancedSpriteMaterialEnhancer } from "./instancedSprite";
+export type { InstancedSpriteMaterialProps } from "./instancedSprite";
+export type {
+  InstancedSpriteBaseMutates,
+  InstancedSpriteBaseProps,
+  InstancedSpriteBaseState,
+} from "./instancedSprite";
+
+// SdfText enhancers
+export { createSdfTextMaterialEnhancer } from "./sdfText";
+export type { SdfTextMaterialProps } from "./sdfText";
+export type {
+  SdfTextBaseMutates,
+  SdfTextBaseProps,
+  SdfTextBaseState,
+} from "./sdfText";

package/src/material/enhancer/instancedSprite/index.ts

@@ -0,0 +1,7 @@
+export { createInstancedSpriteMaterialEnhancer } from "./instancedSpriteMaterialEnhancer";
+export type { InstancedSpriteMaterialProps } from "./instancedSpriteMaterialEnhancer";
+export type {
+  InstancedSpriteBaseMutates,
+  InstancedSpriteBaseProps,
+  InstancedSpriteBaseState,
+} from "./instancedSpriteMaterialEnhancer";

package/src/material/enhancer/instancedSprite/instancedSpriteBaseEnhancer/index.test.ts

@@ -0,0 +1,214 @@
+import { ShaderMaterial } from "three";
+import type { Texture } from "three";
+import { beforeEach, describe, expect, it } from "vitest";
+
+import type { InstancedSpriteBaseProps } from "./types";
+
+import { createInstancedSpriteBaseEnhancer } from "./index";
+
+describe("instancedSpriteBaseEnhancer", () => {
+  let enhancer: ReturnType<typeof createInstancedSpriteBaseEnhancer>;
+
+  beforeEach(() => {
+    enhancer = createInstancedSpriteBaseEnhancer(new ShaderMaterial());
+  });
+
+  describe("lifecycle", () => {
+    it("transformShader() should throw if called before mount", () => {
+      const freshEnhancer = createInstancedSpriteBaseEnhancer(
+        new ShaderMaterial(),
+      );
+
+      const shader = {
+        uniforms: {},
+        vertexShader: "",
+        fragmentShader: "",
+        defines: {},
+      } as any;
+
+      expect(() => freshEnhancer.transformShader(shader)).toThrow(
+        "mount() must be called before transformShader",
+      );
+    });
+
+    it("states() should throw if called before mount", () => {
+      const freshEnhancer = createInstancedSpriteBaseEnhancer(
+        new ShaderMaterial(),
+      );
+
+      expect(() => freshEnhancer.states()).toThrow(
+        "mount() must be called before states",
+      );
+    });
+
+    it("mutates() should throw if called before mount", () => {
+      const freshEnhancer = createInstancedSpriteBaseEnhancer(
+        new ShaderMaterial(),
+      );
+
+      expect(() => freshEnhancer.mutates()).toThrow(
+        "mount() must be called before mutates",
+      );
+    });
+
+    it("update() should throw if called before mount", () => {
+      const freshEnhancer = createInstancedSpriteBaseEnhancer(
+        new ShaderMaterial(),
+      );
+
+      expect(() => freshEnhancer.update({})).toThrow(
+        "mount() must be called before update",
+      );
+    });
+
+    it("programCacheKey() should throw if called before mount", () => {
+      const freshEnhancer = createInstancedSpriteBaseEnhancer(
+        new ShaderMaterial(),
+      );
+
+      expect(() => freshEnhancer.programCacheKey()).toThrow(
+        "mount() must be called before programCacheKey",
+      );
+    });
+
+    it("should initialize state on mount", () => {
+      const props: InstancedSpriteBaseProps = {
+        scale: 50,
+        center: [0.5, 0.5],
+        pickable: true,
+      };
+
+      enhancer.mount(props);
+
+      const state = enhancer.states();
+      expect(state.scale).toBe(50);
+      expect(state.center).toEqual([0.5, 0.5]);
+      expect(state.pickable).toBe(true);
+      expect(state.useRTE).toBe(false);
+      expect(state.billboard).toBe(false);
+    });
+
+    it("should update state on update", () => {
+      enhancer.mount({ scale: 50 });
+
+      const stateBefore = enhancer.states();
+      expect(stateBefore.scale).toBe(50);
+
+      enhancer.update({ scale: 200 });
+
+      const stateAfter = enhancer.states();
+      expect(stateAfter.scale).toBe(200);
+    });
+
+    it("should allow transformShader after mount", () => {
+      enhancer.mount({ scale: 50 });
+
+      const shader = {
+        uniforms: {} as any,
+        vertexShader: "",
+        fragmentShader: "",
+        defines: {},
+      } as any;
+
+      // Should not throw
+      expect(() => enhancer.transformShader(shader)).not.toThrow();
+
+      // Should have assigned uniforms
+      expect(shader.uniforms.uScale).toBeDefined();
+      expect(shader.uniforms.uCenter).toBeDefined();
+      expect(shader.uniforms.nvr_uPickable).toBeDefined();
+    });
+
+    it("should update material properties on mount", () => {
+      const material = new ShaderMaterial();
+      const e = createInstancedSpriteBaseEnhancer(material);
+      e.mount({ transparent: false, depthTest: false });
+
+      expect(material.transparent).toBe(false);
+      expect(material.depthTest).toBe(false);
+    });
+
+    it("should update material properties on update", () => {
+      const material = new ShaderMaterial();
+      const e = createInstancedSpriteBaseEnhancer(material);
+      e.mount({});
+      e.update({ transparent: false });
+
+      expect(material.transparent).toBe(false);
+    });
+
+    it("should update texture and atlasSize together without replacing uTexture ref", () => {
+      enhancer.mount({ billboard: true });
+
+      const shader = {
+        uniforms: {} as any,
+        vertexShader: "",
+        fragmentShader: "",
+        defines: {},
+      } as any;
+      enhancer.transformShader(shader);
+
+      const initialTextureUniform = shader.uniforms.uTexture;
+      expect(initialTextureUniform).toBeDefined();
+
+      const nextTexture = {
+        image: {
+          width: 1,
+          height: 1,
+          data: new Uint8Array([0, 0, 0, 0]),
+        },
+      } as unknown as Texture;
+
+      enhancer.update({
+        texture: { value: nextTexture },
+        atlasSize: [512, 512],
+      });
+
+      expect(shader.uniforms.uTexture).toBe(initialTextureUniform);
+      expect(shader.uniforms.uTexture.value).toBe(nextTexture);
+      expect(shader.uniforms.uAtlasSize.value.x).toBe(512);
+      expect(shader.uniforms.uAtlasSize.value.y).toBe(512);
+      expect(enhancer.states().atlasSize).toEqual([512, 512]);
+    });
+  });
+
+  describe("programCacheKey", () => {
+    it("should return cache key based on shader-affecting state", () => {
+      enhancer.mount({
+        useRTE: true,
+        billboard: true,
+      });
+
+      const cacheKey = enhancer.programCacheKey();
+      const parsed = JSON.parse(cacheKey);
+
+      expect(parsed).toEqual({
+        useRTE: true,
+        billboard: true,
+        userDataDefines: undefined,
+      });
+    });
+
+    it("should return different cache keys for different shader-affecting states", () => {
+      enhancer.mount({ useRTE: false, billboard: false });
+      const cacheKey1 = enhancer.programCacheKey();
+
+      const enhancer2 = createInstancedSpriteBaseEnhancer(new ShaderMaterial());
+      enhancer2.mount({ useRTE: true, billboard: false });
+      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({ useRTE: true, billboard: true, scale: 50 });
+      const cacheKey1 = enhancer.programCacheKey();
+
+      const enhancer2 = createInstancedSpriteBaseEnhancer(new ShaderMaterial());
+      enhancer2.mount({ useRTE: true, billboard: true, scale: 200 });
+      const cacheKey2 = enhancer2.programCacheKey();
+
+      expect(cacheKey1).toBe(cacheKey2);
+    });
+  });
+});