@polarfront-lab/ionian 1.7.0 → 3.0.0

package/dist/ionian.js

@@ -92,10 +92,12 @@ class AssetService {
     __publicField(this, "gltfLoader", new GLTFLoader());
     __publicField(this, "textureLoader", new THREE.TextureLoader());
     __publicField(this, "dracoLoader", new DRACOLoader());
-    __publicField(this, "solidColorTexture", new THREE.DataTexture(new Uint8Array([127, 127, 127, 255]), 1, 1, THREE.RGBAFormat));
+    __publicField(this, "solidColorTextures", /* @__PURE__ */ new Map());
+    __publicField(this, "fallbackTexture", new THREE.DataTexture(new Uint8Array([127, 127, 127, 255]), 1, 1, THREE.RGBAFormat));
     this.eventEmitter = eventEmitter;
     this.dracoLoader.setDecoderPath("https://www.gstatic.com/draco/versioned/decoders/1.5.7/");
     this.gltfLoader.setDRACOLoader(this.dracoLoader);
+    this.fallbackTexture.name = "default-fallback-texture";
     this.updateServiceState("ready");
   }
   /**
@@ -116,19 +118,32 @@ class AssetService {
     }
     this.eventEmitter.emit("assetRegistered", { id });
   }
-  setSolidColor(color) {
-    this.changeColor(color);
-  }
-  getSolidColorTexture() {
-    return this.solidColorTexture;
-  }
   getMesh(id) {
     return this.meshes.get(id) ?? null;
   }
-  getMatcap(id) {
+  getMatcapTexture(id) {
     const texture = this.textures.get(id);
     if (!texture) this.eventEmitter.emit("invalidRequest", { message: `texture with id "${id}" not found. using solid color texture instead...` });
-    return texture ?? this.solidColorTexture;
+    return texture ?? this.fallbackTexture;
+  }
+  getSolidColorTexture(colorValue) {
+    const colorKey = new THREE.Color(colorValue).getHexString();
+    let texture = this.solidColorTextures.get(colorKey);
+    if (texture) {
+      return texture;
+    }
+    try {
+      const texture2 = this.createSolidColorDataTexture(new THREE.Color(colorValue));
+      this.solidColorTextures.set(colorKey, texture2);
+      return texture2;
+    } catch (error) {
+      console.error(`Invalid color value provided to getSolidColorTexture: ${colorValue}`, error);
+      this.eventEmitter.emit("invalidRequest", { message: `Invalid color value: ${colorValue}. Using fallback texture.` });
+      return this.fallbackTexture;
+    }
+  }
+  getFallbackTexture() {
+    return this.fallbackTexture;
   }
   getMeshIDs() {
     return Array.from(this.meshes.keys());
@@ -142,8 +157,29 @@ class AssetService {
   getTextures() {
     return Array.from(this.textures.values());
   }
-  hasMatcap(id) {
-    return this.textures.has(id);
+  createSolidColorDataTexture(color, size = 16) {
+    const col = new THREE.Color(color);
+    const width = size;
+    const height = size;
+    const data = new Uint8Array(width * height * 4);
+    const r = Math.floor(col.r * 255);
+    const g = Math.floor(col.g * 255);
+    const b = Math.floor(col.b * 255);
+    for (let i = 0; i < width * height; i++) {
+      const index = i * 4;
+      data[index] = r;
+      data[index + 1] = g;
+      data[index + 2] = b;
+      data[index + 3] = 255;
+    }
+    const texture = new THREE.DataTexture(data, width, height, THREE.RGBAFormat);
+    texture.type = THREE.UnsignedByteType;
+    texture.wrapS = THREE.RepeatWrapping;
+    texture.wrapT = THREE.RepeatWrapping;
+    texture.minFilter = THREE.NearestFilter;
+    texture.magFilter = THREE.NearestFilter;
+    texture.needsUpdate = true;
+    return texture;
   }
   /**
    * Loads a mesh asynchronously.
@@ -191,11 +227,9 @@ class AssetService {
     this.meshes.clear();
     this.textures.forEach((texture) => texture.dispose());
     this.textures.clear();
-  }
-  changeColor(color) {
-    const actual = new THREE.Color(color);
-    this.solidColorTexture = new THREE.DataTexture(new Uint8Array([actual.r, actual.g, actual.b, 255]), 1, 1, THREE.RGBAFormat);
-    this.solidColorTexture.needsUpdate = true;
+    this.solidColorTextures.forEach((texture) => texture.dispose());
+    this.solidColorTextures.clear();
+    this.fallbackTexture.dispose();
   }
   updateServiceState(serviceState) {
     this.serviceState = serviceState;
@@ -206,6 +240,11 @@ const _face = new Triangle();
 const _color = new Vector3();
 const _uva = new Vector2(), _uvb = new Vector2(), _uvc = new Vector2();
 class MeshSurfaceSampler {
+  /**
+   * Constructs a mesh surface sampler.
+   *
+   * @param {Mesh} mesh - Surface mesh from which to sample.
+   */
   constructor(mesh) {
     this.geometry = mesh.geometry;
     this.randomFunction = Math.random;
@@ -217,10 +256,27 @@ class MeshSurfaceSampler {
     this.weightAttribute = null;
     this.distribution = null;
   }
+  /**
+   * Specifies a vertex attribute to be used as a weight when sampling from the surface.
+   * Faces with higher weights are more likely to be sampled, and those with weights of
+   * zero will not be sampled at all. For vector attributes, only .x is used in sampling.
+   *
+   * If no weight attribute is selected, sampling is randomly distributed by area.
+   *
+   * @param {string} name - The attribute name.
+   * @return {MeshSurfaceSampler} A reference to this sampler.
+   */
   setWeightAttribute(name) {
     this.weightAttribute = name ? this.geometry.getAttribute(name) : null;
     return this;
   }
+  /**
+   * Processes the input geometry and prepares to return samples. Any configuration of the
+   * geometry or sampler must occur before this method is called. Time complexity is O(n)
+   * for a surface with n faces.
+   *
+   * @return {MeshSurfaceSampler} A reference to this sampler.
+   */
   build() {
     const indexAttribute = this.indexAttribute;
     const positionAttribute = this.positionAttribute;
@@ -255,19 +311,37 @@ class MeshSurfaceSampler {
     this.distribution = distribution;
     return this;
   }
+  /**
+   * Allows to set a custom random number generator. Default is `Math.random()`.
+   *
+   * @param {Function} randomFunction - A random number generator.
+   * @return {MeshSurfaceSampler} A reference to this sampler.
+   */
   setRandomGenerator(randomFunction) {
     this.randomFunction = randomFunction;
     return this;
   }
+  /**
+   * Selects a random point on the surface of the input geometry, returning the
+   * position and optionally the normal vector, color and UV Coordinate at that point.
+   * Time complexity is O(log n) for a surface with n faces.
+   *
+   * @param {Vector3} targetPosition - The target object holding the sampled position.
+   * @param {Vector3} targetNormal - The target object holding the sampled normal.
+   * @param {Color} targetColor - The target object holding the sampled color.
+   * @param {Vector2} targetUV -  The target object holding the sampled uv coordinates.
+   * @return {MeshSurfaceSampler} A reference to this sampler.
+   */
   sample(targetPosition, targetNormal, targetColor, targetUV) {
-    const faceIndex = this.sampleFaceIndex();
-    return this.sampleFace(faceIndex, targetPosition, targetNormal, targetColor, targetUV);
+    const faceIndex = this._sampleFaceIndex();
+    return this._sampleFace(faceIndex, targetPosition, targetNormal, targetColor, targetUV);
   }
-  sampleFaceIndex() {
+  // private
+  _sampleFaceIndex() {
     const cumulativeTotal = this.distribution[this.distribution.length - 1];
-    return this.binarySearch(this.randomFunction() * cumulativeTotal);
+    return this._binarySearch(this.randomFunction() * cumulativeTotal);
   }
-  binarySearch(x) {
+  _binarySearch(x) {
     const dist = this.distribution;
     let start = 0;
     let end = dist.length - 1;
@@ -285,7 +359,7 @@ class MeshSurfaceSampler {
     }
     return index;
   }
-  sampleFace(faceIndex, targetPosition, targetNormal, targetColor, targetUV) {
+  _sampleFace(faceIndex, targetPosition, targetNormal, targetColor, targetUV) {
     let u = this.randomFunction();
     let v = this.randomFunction();
     if (u + v > 1) {
@@ -471,7 +545,6 @@ function sampleMesh(meshData, size) {
 }
 const instanceFragmentShader = `
 varying vec2 vUv;
-uniform sampler2D uTexture;
 
 uniform sampler2D uOriginTexture;
 uniform sampler2D uDestinationTexture;
@@ -485,11 +558,11 @@ void main() {
     vec3 y = cross( viewDir, x );
     vec2 uv = vec2( dot( x, vNormal ), dot( y, vNormal ) ) * 0.495 + 0.5; // 0.495 to remove artifacts caused by undersized matcap disks
 
-    vec4 sourceMatcap = texture2D( uOriginTexture, uv );
-    vec4 targetMatcap = texture2D( uDestinationTexture, uv );
+    vec4 textureA = texture2D( uOriginTexture, uv );
+    vec4 textureB = texture2D( uDestinationTexture, uv );
 
-    vec4 matcap = mix(sourceMatcap, targetMatcap, uProgress);
-    gl_FragColor = matcap;
+    vec4 finalColor = mix(textureA, textureB, uProgress);
+    gl_FragColor = finalColor;
 }
 `;
 const instanceVertexShader = `
@@ -545,11 +618,9 @@ class InstancedMeshManager {
   constructor(initialSize) {
     __publicField(this, "size");
     __publicField(this, "mesh");
-    __publicField(this, "matcapMaterial");
+    __publicField(this, "shaderMaterial");
     __publicField(this, "fallbackGeometry");
     __publicField(this, "uniforms");
-    __publicField(this, "originColor");
-    __publicField(this, "destinationColor");
     __publicField(this, "geometries");
     __publicField(this, "uvRefsCache");
     __publicField(this, "previousScale");
@@ -557,8 +628,6 @@ class InstancedMeshManager {
     this.geometries = /* @__PURE__ */ new Map();
     this.uvRefsCache = /* @__PURE__ */ new Map();
     this.previousScale = { x: 1, y: 1, z: 1 };
-    this.originColor = "grey";
-    this.destinationColor = "grey";
     this.uniforms = {
       uTime: { value: 0 },
       uProgress: { value: 0 },
@@ -567,15 +636,14 @@ class InstancedMeshManager {
       uOriginTexture: { value: null },
       uDestinationTexture: { value: null }
     };
-    this.matcapMaterial = new THREE.ShaderMaterial({
+    this.shaderMaterial = new THREE.ShaderMaterial({
       uniforms: this.uniforms,
       vertexShader: instanceVertexShader,
       fragmentShader: instanceFragmentShader
     });
-    this.setOriginColor(this.originColor);
-    this.setDestinationColor(this.destinationColor);
     this.fallbackGeometry = new THREE.BoxGeometry(1e-3, 1e-3, 1e-3);
-    this.mesh = this.createInstancedMesh(initialSize, this.fallbackGeometry, this.matcapMaterial);
+    this.mesh = this.createInstancedMesh(initialSize, this.fallbackGeometry, this.shaderMaterial);
+    this.mesh.material = this.shaderMaterial;
   }
   /**
    * Gets the instanced mesh.
@@ -594,22 +662,10 @@ class InstancedMeshManager {
       material.uniforms.uTime.value = elapsedTime;
     }
   }
-  /**
-   * Sets the matcap texture.
-   * @param matcap The matcap texture to set.
-   */
-  setOriginMatcap(matcap) {
-    this.disposeSolidColorOriginTexture();
-    this.matcapMaterial.uniforms.uOriginTexture.value = matcap;
-  }
-  setDestinationMatcap(matcap) {
-    this.disposeSolidColorDestinationTexture();
-    this.matcapMaterial.uniforms.uDestinationTexture.value = matcap;
-  }
-  setProgress(float) {
-    float = Math.max(0, float);
-    float = Math.min(1, float);
-    this.matcapMaterial.uniforms.uProgress.value = float;
+  updateTextureInterpolation(textureA, textureB, progress) {
+    this.uniforms.uOriginTexture.value = textureA;
+    this.uniforms.uDestinationTexture.value = textureB;
+    this.uniforms.uProgress.value = progress;
   }
   setGeometrySize(size) {
     this.mesh.geometry.scale(1 / this.previousScale.x, 1 / this.previousScale.y, 1 / this.previousScale.z);
@@ -620,7 +676,7 @@ class InstancedMeshManager {
    * Use the matcap material for the instanced mesh.
    */
   useMatcapMaterial() {
-    this.mesh.material = this.matcapMaterial;
+    this.mesh.material = this.shaderMaterial;
   }
   /**
    * Use the specified geometry for the instanced mesh.
@@ -637,14 +693,14 @@ class InstancedMeshManager {
    * @param texture The velocity texture to update with.
    */
   updateVelocityTexture(texture) {
-    this.matcapMaterial.uniforms.uVelocity.value = texture;
+    this.shaderMaterial.uniforms.uVelocity.value = texture;
   }
   /**
    * Updates the position texture.
    * @param texture The position texture to update with.
    */
   updatePositionTexture(texture) {
-    this.matcapMaterial.uniforms.uTexture.value = texture;
+    this.shaderMaterial.uniforms.uTexture.value = texture;
   }
   /**
    * Resizes or replaces the instanced mesh.
@@ -664,9 +720,7 @@ class InstancedMeshManager {
   dispose() {
     this.mesh.dispose();
     this.geometries.forEach((geometry) => geometry.dispose());
-    this.disposeSolidColorOriginTexture();
-    this.disposeSolidColorDestinationTexture();
-    this.matcapMaterial.dispose();
+    this.shaderMaterial.dispose();
     this.uvRefsCache.clear();
     this.geometries.clear();
   }
@@ -690,16 +744,6 @@ class InstancedMeshManager {
     }
     previous == null ? void 0 : previous.dispose();
   }
-  setOriginColor(color) {
-    this.disposeSolidColorOriginTexture();
-    this.originColor = color;
-    this.uniforms.uOriginTexture.value = this.createSolidColorDataTexture(color);
-  }
-  setDestinationColor(color) {
-    this.disposeSolidColorDestinationTexture();
-    this.destinationColor = color;
-    this.uniforms.uDestinationTexture.value = this.createSolidColorDataTexture(color);
-  }
   /**
    * Gets the UV references for the specified size.
    * @param size The size for which to generate UV references.
@@ -735,46 +779,6 @@ class InstancedMeshManager {
     const count = size * size;
     return new THREE.InstancedMesh(geometry, material, count);
   }
-  createSolidColorDataTexture(color, size = 16) {
-    const col = new THREE.Color(color);
-    const width = size;
-    const height = size;
-    const data = new Uint8Array(width * height * 4);
-    const r = Math.floor(col.r * 255);
-    const g = Math.floor(col.g * 255);
-    const b = Math.floor(col.b * 255);
-    for (let i = 0; i < width * height; i++) {
-      const index = i * 4;
-      data[index] = r;
-      data[index + 1] = g;
-      data[index + 2] = b;
-      data[index + 3] = 255;
-    }
-    const texture = new THREE.DataTexture(data, width, height, THREE.RGBAFormat);
-    texture.type = THREE.UnsignedByteType;
-    texture.wrapS = THREE.RepeatWrapping;
-    texture.wrapT = THREE.RepeatWrapping;
-    texture.minFilter = THREE.NearestFilter;
-    texture.magFilter = THREE.NearestFilter;
-    texture.needsUpdate = true;
-    return texture;
-  }
-  disposeSolidColorOriginTexture() {
-    if (this.originColor) {
-      this.originColor = null;
-      if (this.uniforms.uOriginTexture.value) {
-        this.uniforms.uOriginTexture.value.dispose();
-      }
-    }
-  }
-  disposeSolidColorDestinationTexture() {
-    if (this.destinationColor) {
-      this.destinationColor = null;
-      if (this.uniforms.uDestinationTexture.value) {
-        this.uniforms.uDestinationTexture.value.dispose();
-      }
-    }
-  }
 }
 class IntersectionService {
   /**
@@ -1012,15 +1016,34 @@ class FullscreenTriangleGeometry extends BufferGeometry {
 }
 const _geometry = new FullscreenTriangleGeometry();
 class FullScreenQuad {
+  /**
+   * Constructs a new full screen quad.
+   *
+   * @param {?Material} material - The material to render te full screen quad with.
+   */
   constructor(material) {
     this._mesh = new Mesh(_geometry, material);
   }
+  /**
+   * Frees the GPU-related resources allocated by this instance. Call this
+   * method whenever the instance is no longer used in your app.
+   */
   dispose() {
     this._mesh.geometry.dispose();
   }
+  /**
+   * Renders the full screen quad.
+   *
+   * @param {WebGLRenderer} renderer - The renderer.
+   */
   render(renderer) {
     renderer.render(this._mesh, _camera);
   }
+  /**
+   * The quad's material.
+   *
+   * @type {?Material}
+   */
   get material() {
     return this._mesh.material;
   }
@@ -1030,9 +1053,11 @@ class FullScreenQuad {
 }
 class GPUComputationRenderer {
   /**
-   * @param {number} sizeX Computation problem size is always 2d: sizeX * sizeY elements.
-  	 * @param {number} sizeY Computation problem size is always 2d: sizeX * sizeY elements.
-  	 * @param {WebGLRenderer} renderer The renderer
+   * Constructs a new GPU computation renderer.
+   *
+   * @param {number} sizeX - Computation problem size is always 2d: sizeX * sizeY elements.
+  	 * @param {number} sizeY - Computation problem size is always 2d: sizeX * sizeY elements.
+  	 * @param {WebGLRenderer} renderer - The renderer.
    */
   constructor(sizeX, sizeY, renderer) {
     this.variables = [];
@@ -1742,10 +1767,10 @@ class ParticlesEngine {
     this.dataTextureManager = new DataTextureService(this.eventEmitter, textureSize);
     this.simulationRendererService = new SimulationRendererService(this.eventEmitter, textureSize, this.renderer);
     this.instancedMeshManager = new InstancedMeshManager(textureSize);
-    this.instancedMeshManager.useMatcapMaterial();
     this.scene.add(this.instancedMeshManager.getMesh());
     this.intersectionService = new IntersectionService(this.eventEmitter, camera);
     if (!useIntersection) this.intersectionService.setActive(false);
+    this.setOverallProgress(0, false);
     this.eventEmitter.on("interactionPositionUpdated", this.handleInteractionPositionUpdated.bind(this));
   }
   /**
@@ -1761,45 +1786,10 @@ class ParticlesEngine {
     this.instancedMeshManager.updateVelocityTexture(this.simulationRendererService.getVelocityTexture());
     this.instancedMeshManager.updatePositionTexture(this.simulationRendererService.getPositionTexture());
   }
-  setOriginMatcap(matcapID, override = false) {
-    if (override) this.eventEmitter.emit("transitionCancelled", { type: "matcap" });
-    this.engineState.originMatcapID = matcapID;
-    this.instancedMeshManager.setOriginMatcap(this.assetService.getMatcap(matcapID));
-  }
-  setDestinationMatcap(matcapID, override = false) {
-    if (override) this.eventEmitter.emit("transitionCancelled", { type: "matcap" });
-    this.engineState.destinationMatcapID = matcapID;
-    this.instancedMeshManager.setDestinationMatcap(this.assetService.getMatcap(matcapID));
-  }
-  setOriginColor(color, override = false) {
-    if (override) this.eventEmitter.emit("transitionCancelled", { type: "matcap" });
-    this.instancedMeshManager.setOriginColor(color);
-  }
-  setDestinationColor(color, override = false) {
-    if (override) this.eventEmitter.emit("transitionCancelled", { type: "matcap" });
-    this.instancedMeshManager.setDestinationColor(color);
-  }
-  setOriginTexture(id, override = false) {
-    if (override) this.eventEmitter.emit("transitionCancelled", { type: "matcap" });
-    if (typeof id === "string" && this.assetService.hasMatcap(id)) {
-      this.setOriginMatcap(id);
-    } else {
-      this.setOriginColor(id);
-    }
-  }
-  setDestinationTexture(id, override = false) {
-    if (override) this.eventEmitter.emit("transitionCancelled", { type: "matcap" });
-    if (typeof id === "string" && this.assetService.hasMatcap(id)) {
-      this.setDestinationMatcap(id);
-    } else {
-      this.setDestinationColor(id);
-    }
-  }
-  setMatcapProgress(progress, override = false) {
-    const clampedProgress = clamp(progress, 0, 1);
-    if (override) this.eventEmitter.emit("transitionCancelled", { type: "matcap" });
-    this.engineState.matcapTransitionProgress = clampedProgress;
-    this.instancedMeshManager.setProgress(clampedProgress);
+  setTextureSequence(sequence) {
+    this.engineState.textureSequence = sequence;
+    this.eventEmitter.emit("textureSequenceUpdated", { sequence });
+    this.setOverallProgress(0, false);
   }
   // --- Update setTextureSize ---
   async setTextureSize(size) {
@@ -1821,10 +1811,8 @@ class ParticlesEngine {
     this.simulationRendererService.setMaxRepelDistance(this.engineState.maxRepelDistance);
     this.simulationRendererService.setOverallProgress(this.engineState.overallProgress);
     this.intersectionService.setOverallProgress(this.engineState.overallProgress);
-    this.instancedMeshManager.setOriginMatcap(this.assetService.getMatcap(this.engineState.originMatcapID));
-    this.instancedMeshManager.setDestinationMatcap(this.assetService.getMatcap(this.engineState.destinationMatcapID));
-    this.instancedMeshManager.setProgress(this.engineState.matcapTransitionProgress);
     this.instancedMeshManager.setGeometrySize(this.engineState.instanceGeometryScale);
+    this.setOverallProgress(this.engineState.overallProgress, false);
   }
   registerMesh(id, mesh) {
     this.assetService.register(id, mesh);
@@ -1907,6 +1895,7 @@ class ParticlesEngine {
       this.simulationRendererService.setOverallProgress(this.engineState.overallProgress);
       this.intersectionService.setMeshSequence(meshes);
       this.intersectionService.setOverallProgress(this.engineState.overallProgress);
+      this.setOverallProgress(0, false);
     } catch (error) {
       console.error("Failed during mesh sequence setup:", error);
       this.meshSequenceAtlasTexture = null;
@@ -1925,79 +1914,8 @@ class ParticlesEngine {
     this.engineState.overallProgress = clampedProgress;
     this.simulationRendererService.setOverallProgress(clampedProgress);
     this.intersectionService.setOverallProgress(clampedProgress);
-  }
-  // --- Transition scheduling methods remain the same ---
-  scheduleMatcapTransition(originMatcapID, destinationMatcapID, easing = linear, duration = 1e3, override = false, options = {}) {
-    if (override) this.eventEmitter.emit("transitionCancelled", { type: "matcap" });
-    const handleProgressUpdate = (transitionProgress) => {
-      var _a;
-      this.setMatcapProgress(transitionProgress, false);
-      (_a = options.onTransitionProgress) == null ? void 0 : _a.call(options, transitionProgress);
-    };
-    this.transitionService.enqueue(
-      "matcap",
-      { easing, duration },
-      {
-        ...options,
-        onTransitionProgress: handleProgressUpdate,
-        onTransitionBegin: () => {
-          var _a;
-          this.setOriginMatcap(originMatcapID, false);
-          this.setDestinationMatcap(destinationMatcapID, false);
-          this.setMatcapProgress(0, false);
-          (_a = options.onTransitionBegin) == null ? void 0 : _a.call(options);
-        },
-        onTransitionFinished: () => {
-          var _a;
-          this.setMatcapProgress(1, false);
-          (_a = options.onTransitionFinished) == null ? void 0 : _a.call(options);
-        },
-        onTransitionCancelled: options.onTransitionCancelled
-      }
-    );
-  }
-  scheduleTextureTransition(origin, destination, options = {}) {
-    const easing = (options == null ? void 0 : options.easing) ?? linear;
-    const duration = (options == null ? void 0 : options.duration) ?? 1e3;
-    const userCallbacks = {
-      // Extract user callbacks
-      onTransitionBegin: options == null ? void 0 : options.onTransitionBegin,
-      onTransitionProgress: options == null ? void 0 : options.onTransitionProgress,
-      onTransitionFinished: options == null ? void 0 : options.onTransitionFinished,
-      onTransitionCancelled: options == null ? void 0 : options.onTransitionCancelled
-    };
-    if (options == null ? void 0 : options.override) this.eventEmitter.emit("transitionCancelled", { type: "matcap" });
-    const handleProgressUpdate = (transitionProgress) => {
-      var _a;
-      this.setMatcapProgress(transitionProgress, false);
-      (_a = userCallbacks.onTransitionProgress) == null ? void 0 : _a.call(userCallbacks, transitionProgress);
-    };
-    this.transitionService.enqueue(
-      "matcap",
-      // Still uses matcap type internally
-      { easing, duration },
-      {
-        ...userCallbacks,
-        // Pass user callbacks
-        onTransitionProgress: handleProgressUpdate,
-        onTransitionBegin: () => {
-          var _a;
-          this.setOriginTexture(origin);
-          this.setDestinationTexture(destination);
-          this.setMatcapProgress(0);
-          (_a = userCallbacks.onTransitionBegin) == null ? void 0 : _a.call(userCallbacks);
-        },
-        onTransitionFinished: () => {
-          var _a;
-          this.setMatcapProgress(1);
-          (_a = userCallbacks.onTransitionFinished) == null ? void 0 : _a.call(userCallbacks);
-        },
-        onTransitionCancelled: () => {
-          var _a;
-          (_a = userCallbacks.onTransitionCancelled) == null ? void 0 : _a.call(userCallbacks);
-        }
-      }
-    );
+    const { textureA, textureB, localProgress } = this.calculateTextureInterpolation(progress);
+    this.instancedMeshManager.updateTextureInterpolation(textureA, textureB, localProgress);
   }
   /**
    * Schedules a smooth transition for the overall mesh sequence progress.
@@ -2080,9 +1998,7 @@ class ParticlesEngine {
       // ADDED
       overallProgress: 0,
       // ADDED
-      originMatcapID: "",
-      destinationMatcapID: "",
-      matcapTransitionProgress: 0,
+      textureSequence: [],
       velocityTractionForce: 0.1,
       positionalTractionForce: 0.1,
       maxRepelDistance: 0.3,
@@ -2103,6 +2019,47 @@ class ParticlesEngine {
   handleInteractionPositionUpdated({ position }) {
     this.simulationRendererService.setInteractionPosition(position);
   }
+  calculateTextureInterpolation(progress) {
+    const sequence = this.engineState.textureSequence;
+    const numItems = sequence.length;
+    if (numItems === 0) {
+      const defaultTex = this.assetService.getFallbackTexture();
+      return { textureA: defaultTex, textureB: defaultTex, localProgress: 0 };
+    }
+    if (numItems === 1) {
+      const tex = this.getTextureForSequenceItem(sequence[0]);
+      return { textureA: tex, textureB: tex, localProgress: 0 };
+    }
+    const totalSegments = numItems - 1;
+    const progressPerSegment = 1 / totalSegments;
+    const scaledProgress = progress * totalSegments;
+    let indexA = Math.floor(scaledProgress);
+    let indexB = indexA + 1;
+    indexA = Math.max(0, Math.min(indexA, totalSegments));
+    indexB = Math.max(0, Math.min(indexB, totalSegments));
+    let localProgress = 0;
+    if (progressPerSegment > 0) {
+      localProgress = (progress - indexA * progressPerSegment) / progressPerSegment;
+    }
+    if (progress >= 1) {
+      indexA = totalSegments;
+      indexB = totalSegments;
+      localProgress = 1;
+    }
+    localProgress = Math.max(0, Math.min(localProgress, 1));
+    const itemA = sequence[indexA];
+    const itemB = sequence[indexB];
+    const textureA = this.getTextureForSequenceItem(itemA);
+    const textureB = this.getTextureForSequenceItem(itemB);
+    return { textureA, textureB, localProgress };
+  }
+  getTextureForSequenceItem(item) {
+    if (item.type === "matcap") {
+      return this.assetService.getMatcapTexture(item.id);
+    } else {
+      return this.assetService.getSolidColorTexture(item.value);
+    }
+  }
 }
 export {
   ParticlesEngine