@polarfront-lab/ionian 1.6.0 → 2.0.0

package/dist/ionian.js

@@ -206,6 +206,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 +222,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 +277,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 +325,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) {
@@ -334,6 +374,7 @@ class MeshSurfaceSampler {
   }
 }
 class DataTextureService {
+  // Cache the current atlas
   /**
    * Creates a new DataTextureManager instance.
    * @param eventEmitter
@@ -343,6 +384,7 @@ class DataTextureService {
     __publicField(this, "textureSize");
     __publicField(this, "dataTextures");
     __publicField(this, "eventEmitter");
+    __publicField(this, "currentAtlas", null);
     this.eventEmitter = eventEmitter;
     this.textureSize = textureSize;
     this.dataTextures = /* @__PURE__ */ new Map();
@@ -353,6 +395,10 @@ class DataTextureService {
     this.textureSize = textureSize;
     this.dataTextures.forEach((texture) => texture.dispose());
     this.dataTextures.clear();
+    if (this.currentAtlas) {
+      this.currentAtlas.dispose();
+      this.currentAtlas = null;
+    }
   }
   /**
    * Prepares a mesh for sampling.
@@ -360,23 +406,76 @@ class DataTextureService {
    * @param asset The asset to prepare.
    */
   async getDataTexture(asset) {
-    const texture = this.dataTextures.get(asset.name);
-    if (texture) {
-      return texture;
+    const cachedTexture = this.dataTextures.get(asset.uuid);
+    if (cachedTexture) {
+      return cachedTexture;
     }
     const meshData = parseMeshData(asset);
     const array = sampleMesh(meshData, this.textureSize);
     const dataTexture = createDataTexture(array, this.textureSize);
     dataTexture.name = asset.name;
+    this.dataTextures.set(asset.uuid, dataTexture);
     return dataTexture;
   }
   async dispose() {
+    this.dataTextures.forEach((texture) => texture.dispose());
     this.dataTextures.clear();
+    if (this.currentAtlas) {
+      this.currentAtlas.dispose();
+      this.currentAtlas = null;
+    }
     this.updateServiceState("disposed");
   }
   updateServiceState(serviceState) {
     this.eventEmitter.emit("serviceStateUpdated", { type: "data-texture", state: serviceState });
   }
+  /**
+   * Creates a Texture Atlas containing position data for a sequence of meshes.
+   * @param meshes An array of THREE.Mesh objects in the desired sequence.
+   * @param singleTextureSize The desired resolution (width/height) for each mesh's data within the atlas.
+   * @returns A Promise resolving to the generated DataTexture atlas.
+   */
+  async createSequenceDataTextureAtlas(meshes, singleTextureSize) {
+    this.updateServiceState("loading");
+    if (this.currentAtlas) {
+      this.currentAtlas.dispose();
+      this.currentAtlas = null;
+    }
+    const numMeshes = meshes.length;
+    if (numMeshes === 0) {
+      throw new Error("Mesh array cannot be empty.");
+    }
+    const atlasWidth = singleTextureSize * numMeshes;
+    const atlasHeight = singleTextureSize;
+    const atlasData = new Float32Array(atlasWidth * atlasHeight * 4);
+    try {
+      for (let i = 0; i < numMeshes; i++) {
+        const mesh = meshes[i];
+        const meshDataTexture = await this.getDataTexture(mesh);
+        const meshTextureData = meshDataTexture.image.data;
+        for (let y = 0; y < singleTextureSize; y++) {
+          for (let x = 0; x < singleTextureSize; x++) {
+            const sourceIndex = (y * singleTextureSize + x) * 4;
+            const targetX = x + i * singleTextureSize;
+            const targetIndex = (y * atlasWidth + targetX) * 4;
+            atlasData[targetIndex] = meshTextureData[sourceIndex];
+            atlasData[targetIndex + 1] = meshTextureData[sourceIndex + 1];
+            atlasData[targetIndex + 2] = meshTextureData[sourceIndex + 2];
+            atlasData[targetIndex + 3] = meshTextureData[sourceIndex + 3];
+          }
+        }
+      }
+      const atlasTexture = new THREE.DataTexture(atlasData, atlasWidth, atlasHeight, THREE.RGBAFormat, THREE.FloatType);
+      atlasTexture.needsUpdate = true;
+      atlasTexture.name = `atlas-${meshes.map((m) => m.name).join("-")}`;
+      this.currentAtlas = atlasTexture;
+      this.updateServiceState("ready");
+      return atlasTexture;
+    } catch (error) {
+      this.updateServiceState("error");
+      throw error;
+    }
+  }
 }
 function parseMeshData(mesh) {
   var _a;
@@ -722,32 +821,35 @@ class IntersectionService {
    * Creates a new IntersectionService instance.
    * @param eventEmitter The event emitter used for emitting events.
    * @param camera The camera used for raycasting.
-   * @param originGeometry The origin geometry.
-   * @param destinationGeometry The destination geometry.
    */
-  constructor(eventEmitter, camera, originGeometry, destinationGeometry) {
+  constructor(eventEmitter, camera) {
     __publicField(this, "active", true);
     __publicField(this, "raycaster", new THREE.Raycaster());
     __publicField(this, "mousePosition", new THREE.Vector2());
     __publicField(this, "camera");
-    __publicField(this, "originGeometry");
-    __publicField(this, "destinationGeometry");
-    __publicField(this, "progress", 0);
+    __publicField(this, "meshSequenceGeometries", []);
+    // ADDED: Store cloned geometries
+    __publicField(this, "meshSequenceUUIDs", []);
+    // ADDED: Track UUIDs to avoid redundant cloning
+    __publicField(this, "overallProgress", 0);
+    // ADDED: Store overall progress (0-1)
     __publicField(this, "intersectionMesh", new THREE.Mesh());
+    // Use a single mesh for intersection target
     __publicField(this, "geometryNeedsUpdate");
     __publicField(this, "eventEmitter");
     __publicField(this, "blendedGeometry");
+    // Keep for the final blended result
     __publicField(this, "intersection");
-    __publicField(this, "lastKnownOriginMeshID");
-    __publicField(this, "lastKnownDestinationMeshID");
     this.camera = camera;
-    this.originGeometry = originGeometry;
     this.eventEmitter = eventEmitter;
-    this.destinationGeometry = destinationGeometry;
     this.geometryNeedsUpdate = true;
   }
   setActive(active) {
     this.active = active;
+    if (!active) {
+      this.intersection = void 0;
+      this.eventEmitter.emit("interactionPositionUpdated", { position: { x: 0, y: 0, z: 0, w: 0 } });
+    }
   }
   getIntersectionMesh() {
     return this.intersectionMesh;
@@ -760,36 +862,40 @@ class IntersectionService {
     this.camera = camera;
   }
   /**
-   * Set the origin geometry.
-   * @param source
-   */
-  setOriginGeometry(source) {
-    if (this.lastKnownOriginMeshID === source.uuid) return;
-    if (this.originGeometry) this.originGeometry.dispose();
-    this.lastKnownOriginMeshID = source.uuid;
-    this.originGeometry = source.geometry.clone();
-    this.originGeometry.applyMatrix4(source.matrixWorld);
-    this.geometryNeedsUpdate = true;
-  }
-  /**
-   * Set the destination geometry.
-   * @param source
+   * Sets the sequence of meshes used for intersection calculations.
+   * Clones the geometries to avoid modifying originals.
+   * @param meshes An array of THREE.Mesh objects in sequence.
    */
-  setDestinationGeometry(source) {
-    if (this.lastKnownDestinationMeshID === source.uuid) return;
-    if (this.destinationGeometry) this.destinationGeometry.dispose();
-    this.lastKnownDestinationMeshID = source.uuid;
-    this.destinationGeometry = source.geometry.clone();
-    this.destinationGeometry.applyMatrix4(source.matrixWorld);
+  setMeshSequence(meshes) {
+    this.meshSequenceGeometries.forEach((geom) => geom.dispose());
+    this.meshSequenceGeometries = [];
+    this.meshSequenceUUIDs = [];
+    if (!meshes || meshes.length === 0) {
+      this.geometryNeedsUpdate = true;
+      return;
+    }
+    meshes.forEach((mesh) => {
+      if (mesh && mesh.geometry) {
+        const clonedGeometry = mesh.geometry.clone();
+        clonedGeometry.applyMatrix4(mesh.matrixWorld);
+        this.meshSequenceGeometries.push(clonedGeometry);
+        this.meshSequenceUUIDs.push(mesh.uuid);
+      } else {
+        console.warn("Invalid mesh provided to IntersectionService sequence.");
+      }
+    });
     this.geometryNeedsUpdate = true;
   }
   /**
-   * Set the progress of the morphing animation.
-   * @param progress
+   * Set the overall progress through the mesh sequence.
+   * @param progress Value between 0.0 (first mesh) and 1.0 (last mesh).
    */
-  setProgress(progress) {
-    this.progress = progress;
-    this.geometryNeedsUpdate = true;
+  setOverallProgress(progress) {
+    const newProgress = THREE.MathUtils.clamp(progress, 0, 1);
+    if (this.overallProgress !== newProgress) {
+      this.overallProgress = newProgress;
+      this.geometryNeedsUpdate = true;
+    }
   }
   /**
    * Set the mouse position.
@@ -803,22 +909,46 @@ class IntersectionService {
    * @returns The intersection point or undefined if no intersection was found.
    */
   calculate(instancedMesh) {
-    if (!this.active) return;
-    this.updateIntersectionMesh(instancedMesh);
-    if (!this.camera) return;
+    var _a, _b, _c;
+    if (!this.active || !this.camera || this.meshSequenceGeometries.length === 0) {
+      if (this.intersection) {
+        this.intersection = void 0;
+        this.eventEmitter.emit("interactionPositionUpdated", { position: { x: 0, y: 0, z: 0, w: 0 } });
+      }
+      return void 0;
+    }
     if (this.geometryNeedsUpdate) {
-      this.geometryNeedsUpdate = false;
+      if (this.blendedGeometry && this.blendedGeometry !== this.intersectionMesh.geometry) {
+        this.blendedGeometry.dispose();
+      }
       this.blendedGeometry = this.getBlendedGeometry();
+      this.geometryNeedsUpdate = false;
+      if (this.blendedGeometry) {
+        if (this.intersectionMesh.geometry !== this.blendedGeometry) {
+          if (this.intersectionMesh.geometry) this.intersectionMesh.geometry.dispose();
+          this.intersectionMesh.geometry = this.blendedGeometry;
+        }
+      } else {
+        if (this.intersectionMesh.geometry) this.intersectionMesh.geometry.dispose();
+        this.intersectionMesh.geometry = new THREE.BufferGeometry();
+      }
     }
-    if (this.blendedGeometry) {
-      this.intersection = this.getFirstIntersection(this.camera, instancedMesh);
-    } else {
-      this.intersection = void 0;
+    this.intersectionMesh.matrixWorld.copy(instancedMesh.matrixWorld);
+    let newIntersection = void 0;
+    if (this.blendedGeometry && this.blendedGeometry.attributes.position) {
+      newIntersection = this.getFirstIntersection(this.camera, this.intersectionMesh);
     }
-    if (this.intersection) {
-      this.eventEmitter.emit("interactionPositionUpdated", { position: this.intersection });
-    } else {
-      this.eventEmitter.emit("interactionPositionUpdated", { position: { x: 0, y: 0, z: 0, w: 0 } });
+    const hasChanged = ((_a = this.intersection) == null ? void 0 : _a.x) !== (newIntersection == null ? void 0 : newIntersection.x) || ((_b = this.intersection) == null ? void 0 : _b.y) !== (newIntersection == null ? void 0 : newIntersection.y) || ((_c = this.intersection) == null ? void 0 : _c.z) !== (newIntersection == null ? void 0 : newIntersection.z) || this.intersection && !newIntersection || !this.intersection && newIntersection;
+    if (hasChanged) {
+      this.intersection = newIntersection;
+      if (this.intersection) {
+        const worldPoint = new THREE.Vector3(this.intersection.x, this.intersection.y, this.intersection.z);
+        const localPoint = instancedMesh.worldToLocal(worldPoint.clone());
+        this.intersection.set(localPoint.x, localPoint.y, localPoint.z, 1);
+        this.eventEmitter.emit("interactionPositionUpdated", { position: this.intersection });
+      } else {
+        this.eventEmitter.emit("interactionPositionUpdated", { position: { x: 0, y: 0, z: 0, w: 0 } });
+      }
     }
     return this.intersection;
   }
@@ -827,8 +957,13 @@ class IntersectionService {
    */
   dispose() {
     var _a;
-    (_a = this.blendedGeometry) == null ? void 0 : _a.dispose();
-    this.intersectionMesh.geometry.dispose();
+    this.meshSequenceGeometries.forEach((geom) => geom.dispose());
+    this.meshSequenceGeometries = [];
+    this.meshSequenceUUIDs = [];
+    if (this.blendedGeometry && this.blendedGeometry !== this.intersectionMesh.geometry) {
+      this.blendedGeometry.dispose();
+    }
+    (_a = this.intersectionMesh.geometry) == null ? void 0 : _a.dispose();
   }
   updateIntersectionMesh(instancedMesh) {
     if (this.blendedGeometry) {
@@ -842,29 +977,50 @@ class IntersectionService {
     this.intersectionMesh.matrixAutoUpdate = false;
     this.intersectionMesh.updateMatrixWorld(true);
   }
-  getFirstIntersection(camera, instancedMesh) {
+  getFirstIntersection(camera, targetMesh) {
     this.raycaster.setFromCamera(this.mousePosition, camera);
-    const intersection = this.raycaster.intersectObject(this.intersectionMesh, false)[0];
-    if (intersection) {
-      const worldPoint = intersection.point.clone();
-      const localPoint = instancedMesh.worldToLocal(worldPoint);
-      return new THREE.Vector4(localPoint.x, localPoint.y, localPoint.z, 1);
+    const intersects = this.raycaster.intersectObject(targetMesh, false);
+    if (intersects.length > 0 && intersects[0].point) {
+      const worldPoint = intersects[0].point;
+      return new THREE.Vector4(worldPoint.x, worldPoint.y, worldPoint.z, 1);
     }
+    return void 0;
   }
   getBlendedGeometry() {
-    if (this.progress === 0) {
-      return this.originGeometry;
+    const numGeometries = this.meshSequenceGeometries.length;
+    if (numGeometries === 0) {
+      return void 0;
     }
-    if (this.progress === 1) {
-      return this.destinationGeometry;
+    if (numGeometries === 1) {
+      return this.meshSequenceGeometries[0];
     }
-    if (!this.originGeometry || !this.destinationGeometry) {
-      return;
+    const totalSegments = numGeometries - 1;
+    const progressPerSegment = 1 / totalSegments;
+    const scaledProgress = this.overallProgress * totalSegments;
+    let indexA = Math.floor(scaledProgress);
+    let indexB = indexA + 1;
+    indexA = THREE.MathUtils.clamp(indexA, 0, totalSegments);
+    indexB = THREE.MathUtils.clamp(indexB, 0, totalSegments);
+    let localProgress = 0;
+    if (progressPerSegment > 0) {
+      localProgress = scaledProgress - indexA;
     }
-    if (this.originGeometry === this.destinationGeometry) {
-      return this.originGeometry;
+    if (this.overallProgress >= 1) {
+      indexA = totalSegments;
+      indexB = totalSegments;
+      localProgress = 1;
     }
-    return this.blendGeometry(this.originGeometry, this.destinationGeometry, this.progress);
+    localProgress = THREE.MathUtils.clamp(localProgress, 0, 1);
+    const geomA = this.meshSequenceGeometries[indexA];
+    const geomB = this.meshSequenceGeometries[indexB];
+    if (!geomA || !geomB) {
+      console.error("IntersectionService: Invalid geometries found for blending at indices", indexA, indexB);
+      return this.meshSequenceGeometries[0];
+    }
+    if (indexA === indexB) {
+      return geomA;
+    }
+    return this.blendGeometry(geomA, geomB, localProgress);
   }
   blendGeometry(from, to, progress) {
     const blended = new THREE.BufferGeometry();
@@ -896,15 +1052,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;
   }
@@ -914,9 +1089,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 = [];
@@ -1087,179 +1264,283 @@ class GPUComputationRenderer {
     }
   }
 }
-const mixShader = `
-uniform sampler2D uPositionA;
-uniform sampler2D uPositionB;
-uniform float uProgress;
-
-void main() {
-    vec2 uv = gl_FragCoord.xy / resolution.xy;
-    vec3 positionA = texture2D(uPositionA, uv).xyz;
-    vec3 positionB = texture2D(uPositionB, uv).xyz;
-    vec3 mixedPosition = mix(positionA, positionB, uProgress);
-    gl_FragColor = vec4(mixedPosition, 1.0);
-}
-`;
 const positionShader = `
-uniform float uProgress;
 uniform vec4 uInteractionPosition;
 uniform float uTime;
 uniform float uTractionForce;
+uniform sampler2D uPositionAtlas;
+uniform float uOverallProgress; // (0.0 to 1.0)
+uniform int uNumMeshes;
+uniform float uSingleTextureSize;
 
 float rand(vec2 co) {
     return fract(sin(dot(co, vec2(12.9898, 78.233))) * 43758.5453);
 }
 
+// Helper function to get position from atlas
+vec3 getAtlasPosition(vec2 uv, int meshIndex) {
+    float atlasWidth = uSingleTextureSize * float(uNumMeshes);
+    float atlasHeight = uSingleTextureSize; // Assuming height is single texture size
+
+    // Calculate UV within the specific mesh's section of the atlas
+    float segmentWidthRatio = uSingleTextureSize / atlasWidth;
+    vec2 atlasUV = vec2(
+        uv.x * segmentWidthRatio + segmentWidthRatio * float(meshIndex),
+        uv.y // Assuming vertical layout doesn't change y
+    );
+
+    return texture2D(uPositionAtlas, atlasUV).xyz;
+}
+
 void main() {
+    // GPGPU UV calculation
+    vec2 uv = gl_FragCoord.xy / resolution.xy; // resolution is the size of the *output* texture (e.g., 256x256)
 
-    // in GPGPU, we calculate the uv on each fragment shader, not using the static varying passed over from the v shader.
-    vec2 uv = gl_FragCoord.xy / resolution.xy;
-    float offset = rand(uv);
+    vec3 currentPosition = texture2D(uCurrentPosition, uv).xyz;
+    vec3 currentVelocity = texture2D(uCurrentVelocity, uv).xyz;
 
-    vec3 position = texture2D(uCurrentPosition, uv).xyz;
-    vec3 velocity = texture2D(uCurrentVelocity, uv).xyz;
-    vec3 mixedPosition = texture2D(uMixedPosition, uv).xyz;
+    // --- Calculate Target Position from Atlas ---
+    vec3 targetPosition;
+    if (uNumMeshes <= 1) {
+        targetPosition = getAtlasPosition(uv, 0);
+    } else {
+        float totalSegments = float(uNumMeshes - 1);
+        float progressPerSegment = 1.0 / totalSegments;
+        float scaledProgress = uOverallProgress * totalSegments;
 
-    // particle attraction to original position.
-    vec3 direction = normalize(mixedPosition - position); // direction vector
-    float dist = length ( mixedPosition - position ); // distance from where it was supposed to be, and currently are.
+        int indexA = int(floor(scaledProgress));
+        // Clamp indexB to avoid going out of bounds
+        int indexB = min(indexA + 1, uNumMeshes - 1);
 
-    if (dist > 0.01) {
-        position = mix(position, mixedPosition, 0.1 * uTractionForce); // 0.1 ~ 0.001 (faster, slower)
+        // Ensure indexA is also within bounds (important if uOverallProgress is exactly 1.0)
+        indexA = min(indexA, uNumMeshes - 1);
+
+
+        float localProgress = fract(scaledProgress);
+
+        // Handle edge case where progress is exactly 1.0
+        if (uOverallProgress == 1.0) {
+             indexA = uNumMeshes - 1;
+             indexB = uNumMeshes - 1;
+             localProgress = 1.0; // or 0.0 depending on how you want to handle it
+        }
+
+
+        vec3 positionA = getAtlasPosition(uv, indexA);
+        vec3 positionB = getAtlasPosition(uv, indexB);
+
+        targetPosition = mix(positionA, positionB, localProgress);
+    }
+    // --- End Target Position Calculation ---
+
+    // Particle attraction to target position
+    vec3 direction = normalize(targetPosition - currentPosition);
+    float dist = length(targetPosition - currentPosition);
+
+    vec3 finalPosition = currentPosition;
+
+    // Apply attraction force (simplified mix)
+    if (dist > 0.01) { // Only apply if significantly far
+       finalPosition = mix(currentPosition, targetPosition, 0.1 * uTractionForce);
     }
 
-    position += velocity;
-    gl_FragColor = vec4(position, 1.0);
+    finalPosition += currentVelocity;
+    gl_FragColor = vec4(finalPosition, 1.0);
 }
 `;
 const velocityShader = `
-uniform float uProgress;
 uniform vec4 uInteractionPosition;
 uniform float uTime;
 uniform float uTractionForce;
 uniform float uMaxRepelDistance;
+uniform sampler2D uPositionAtlas;
+uniform float uOverallProgress;
+uniform int uNumMeshes;
+uniform float uSingleTextureSize;
 
 float rand(vec2 co) {
     return fract(sin(dot(co, vec2(12.9898, 78.233))) * 43758.5453);
 }
 
+// Helper function (same as in position shader)
+vec3 getAtlasPosition(vec2 uv, int meshIndex) {
+    float atlasWidth = uSingleTextureSize * float(uNumMeshes);
+    float atlasHeight = uSingleTextureSize;
+    float segmentWidthRatio = uSingleTextureSize / atlasWidth;
+    vec2 atlasUV = vec2(uv.x * segmentWidthRatio + segmentWidthRatio * float(meshIndex), uv.y);
+    return texture2D(uPositionAtlas, atlasUV).xyz;
+}
+
 void main() {
-    vec2 uv = gl_FragCoord.xy / resolution.xy;
+   vec2 uv = gl_FragCoord.xy / resolution.xy;
     float offset = rand(uv);
 
-    vec3 position = texture2D(uCurrentPosition, uv).xyz;
-    vec3 velocity = texture2D(uCurrentVelocity, uv).xyz;
-    vec3 mixedPosition = texture2D(uMixedPosition, uv).xyz;
+    vec3 currentPosition = texture2D(uCurrentPosition, uv).xyz;
+    vec3 currentVelocity = texture2D(uCurrentVelocity, uv).xyz;
+
+    // --- Calculate Target Position from Atlas (same logic as position shader) ---
+    vec3 targetPosition;
+     if (uNumMeshes <= 1) {
+        targetPosition = getAtlasPosition(uv, 0);
+    } else {
+        float totalSegments = float(uNumMeshes - 1);
+        float progressPerSegment = 1.0 / totalSegments;
+        float scaledProgress = uOverallProgress * totalSegments;
+        int indexA = int(floor(scaledProgress));
+        int indexB = min(indexA + 1, uNumMeshes - 1);
+        indexA = min(indexA, uNumMeshes - 1);
+        float localProgress = fract(scaledProgress);
+         if (uOverallProgress == 1.0) {
+             indexA = uNumMeshes - 1;
+             indexB = uNumMeshes - 1;
+             localProgress = 1.0;
+        }
+        vec3 positionA = getAtlasPosition(uv, indexA);
+        vec3 positionB = getAtlasPosition(uv, indexB);
+        targetPosition = mix(positionA, positionB, localProgress);
+    }
+    // --- End Target Position Calculation ---
 
-    velocity *= 0.9;
+    vec3 finalVelocity = currentVelocity * 0.9; // Dampening
 
-    // particle traction
-    vec3 direction = normalize(mixedPosition - position); // direction vector
-    float dist = length ( mixedPosition - position ); // distance from where it was supposed to be, and currently are.
+    // Particle traction force towards target (influences velocity)
+    vec3 direction = normalize(targetPosition - currentPosition);
+    float dist = length(targetPosition - currentPosition);
     if (dist > 0.01) {
-        position += direction * 0.1 * uTractionForce; // uTractionForce defaults to 0.1
+        // Add force proportional to distance and traction setting
+        finalVelocity += direction * dist * 0.01 * uTractionForce; // Adjust multiplier as needed
     }
 
-    // mouse repel force
-    float pointerDistance = distance(position, uInteractionPosition.xyz);
-    float mouseRepelModifier = clamp(uMaxRepelDistance - pointerDistance, 0.0, 1.0);
-    float normalizedDistance = pointerDistance / uMaxRepelDistance;
-    float repulsionStrength = (1.0 - normalizedDistance) * uInteractionPosition.w;
-    direction = normalize(position - uInteractionPosition.xyz);
-    velocity += (direction * 0.01 * repulsionStrength) * mouseRepelModifier;
+    // Mouse repel force
+    if (uInteractionPosition.w > 0.0) { // Check if interaction is active (w component)
+        float pointerDistance = distance(currentPosition, uInteractionPosition.xyz);
+        if (pointerDistance < uMaxRepelDistance) {
+            float mouseRepelModifier = smoothstep(uMaxRepelDistance, 0.0, pointerDistance); // Smoother falloff
+            vec3 repelDirection = normalize(currentPosition - uInteractionPosition.xyz);
+            // Apply force based on proximity and interaction strength (w)
+            finalVelocity += repelDirection * mouseRepelModifier * uInteractionPosition.w * 0.01; // Adjust multiplier
+        }
+    }
 
+    // Optional: Reset position if particle "dies" and respawns (lifespan logic)
     float lifespan = 20.0;
-    float age = mod(uTime + lifespan * offset, lifespan);
-
-    if (age < 0.1) {
-        position.xyz = mixedPosition;
+    float age = mod(uTime * 0.1 + lifespan * offset, lifespan); // Adjust time scale
+    if (age < 0.05) { // Small window for reset
+        finalVelocity = vec3(0.0); // Reset velocity on respawn
+        // Note: Resetting position directly here might cause jumps.
+        // It's often better handled in the position shader or by ensuring
+        // strong attraction force when dist is large.
     }
 
-    gl_FragColor = vec4(velocity, 1.0);
+
+    gl_FragColor = vec4(finalVelocity, 1.0);
 }
 `;
 class SimulationRenderer {
   /**
    * Creates a new SimulationRenderer instance.
-   * @param size The size of the simulation textures.
+   * @param size The size of the simulation textures (width/height).
    * @param webGLRenderer The WebGL renderer.
-   * @param initialPosition The initial position data texture. If not provided, a default sphere will be used.
+   * @param initialPosition The initial position data texture (optional, defaults to sphere).
    */
   constructor(size, webGLRenderer, initialPosition) {
     __publicField(this, "gpuComputationRenderer");
     __publicField(this, "webGLRenderer");
-    // calculations
-    __publicField(this, "positionDataTexture");
-    __publicField(this, "velocityDataTexture");
-    // GPUComputationRenderer variables
-    __publicField(this, "mixPositionsVar");
+    // GPGPU Variables
     __publicField(this, "velocityVar");
     __publicField(this, "positionVar");
+    // Input Data Textures (References)
+    __publicField(this, "initialPositionDataTexture");
+    // Used only for first init
+    __publicField(this, "initialVelocityDataTexture");
+    // Blank texture for init
+    __publicField(this, "positionAtlasTexture", null);
+    // Holds the current mesh sequence atlas
+    // Uniforms
     __publicField(this, "interactionPosition");
+    // Cache last known output textures
     __publicField(this, "lastKnownPositionDataTexture");
     __publicField(this, "lastKnownVelocityDataTexture");
-    __publicField(this, "lastKnownMixProgress");
-    __publicField(this, "initialDataTexture");
-    this.initialDataTexture = initialPosition ?? createSpherePoints(size);
-    this.positionDataTexture = this.initialDataTexture;
     this.webGLRenderer = webGLRenderer;
     this.gpuComputationRenderer = new GPUComputationRenderer(size, size, this.webGLRenderer);
-    this.lastKnownMixProgress = 0;
-    if (!webGLRenderer.capabilities.isWebGL2) {
+    if (!webGLRenderer.capabilities.isWebGL2 && webGLRenderer.extensions.get("OES_texture_float")) {
+      this.gpuComputationRenderer.setDataType(THREE.FloatType);
+    } else if (!webGLRenderer.capabilities.isWebGL2) {
       this.gpuComputationRenderer.setDataType(THREE.HalfFloatType);
     }
-    this.velocityDataTexture = createBlankDataTexture(size);
+    this.initialPositionDataTexture = initialPosition ?? createSpherePoints(size);
+    this.initialVelocityDataTexture = createBlankDataTexture(size);
     this.interactionPosition = new THREE.Vector4(0, 0, 0, 0);
-    this.mixPositionsVar = this.gpuComputationRenderer.addVariable("uMixedPosition", mixShader, this.positionDataTexture);
-    this.velocityVar = this.gpuComputationRenderer.addVariable("uCurrentVelocity", velocityShader, this.velocityDataTexture);
-    this.positionVar = this.gpuComputationRenderer.addVariable("uCurrentPosition", positionShader, this.positionDataTexture);
-    this.mixPositionsVar.material.uniforms.uProgress = { value: 0 };
-    this.mixPositionsVar.material.uniforms.uPositionA = { value: this.initialDataTexture };
-    this.mixPositionsVar.material.uniforms.uPositionB = { value: this.initialDataTexture };
+    this.velocityVar = this.gpuComputationRenderer.addVariable("uCurrentVelocity", velocityShader, this.initialVelocityDataTexture);
+    this.positionVar = this.gpuComputationRenderer.addVariable("uCurrentPosition", positionShader, this.initialPositionDataTexture);
     this.velocityVar.material.uniforms.uTime = { value: 0 };
     this.velocityVar.material.uniforms.uInteractionPosition = { value: this.interactionPosition };
-    this.velocityVar.material.uniforms.uCurrentPosition = { value: this.positionDataTexture };
+    this.velocityVar.material.uniforms.uCurrentPosition = { value: null };
     this.velocityVar.material.uniforms.uTractionForce = { value: 0.1 };
     this.velocityVar.material.uniforms.uMaxRepelDistance = { value: 0.3 };
+    this.velocityVar.material.uniforms.uPositionAtlas = { value: null };
+    this.velocityVar.material.uniforms.uOverallProgress = { value: 0 };
+    this.velocityVar.material.uniforms.uNumMeshes = { value: 1 };
+    this.velocityVar.material.uniforms.uSingleTextureSize = { value: size };
     this.positionVar.material.uniforms.uTime = { value: 0 };
-    this.positionVar.material.uniforms.uProgress = { value: 0 };
     this.positionVar.material.uniforms.uTractionForce = { value: 0.1 };
     this.positionVar.material.uniforms.uInteractionPosition = { value: this.interactionPosition };
-    this.positionVar.material.uniforms.uCurrentPosition = { value: this.positionDataTexture };
-    this.gpuComputationRenderer.setVariableDependencies(this.positionVar, [this.velocityVar, this.positionVar, this.mixPositionsVar]);
-    this.gpuComputationRenderer.setVariableDependencies(this.velocityVar, [this.velocityVar, this.positionVar, this.mixPositionsVar]);
-    const err = this.gpuComputationRenderer.init();
-    if (err) {
-      throw new Error("failed to initialize SimulationRenderer: " + err);
+    this.positionVar.material.uniforms.uCurrentPosition = { value: null };
+    this.positionVar.material.uniforms.uCurrentVelocity = { value: null };
+    this.positionVar.material.uniforms.uPositionAtlas = { value: null };
+    this.positionVar.material.uniforms.uOverallProgress = { value: 0 };
+    this.positionVar.material.uniforms.uNumMeshes = { value: 1 };
+    this.positionVar.material.uniforms.uSingleTextureSize = { value: size };
+    this.gpuComputationRenderer.setVariableDependencies(this.positionVar, [this.positionVar, this.velocityVar]);
+    this.gpuComputationRenderer.setVariableDependencies(this.velocityVar, [this.velocityVar, this.positionVar]);
+    const initError = this.gpuComputationRenderer.init();
+    if (initError !== null) {
+      throw new Error("Failed to initialize SimulationRenderer: " + initError);
     }
-    this.lastKnownVelocityDataTexture = this.getVelocityTexture();
-    this.lastKnownPositionDataTexture = this.getPositionTexture();
+    this.positionVar.material.uniforms.uPositionAtlas.value = this.initialPositionDataTexture;
+    this.positionVar.material.uniforms.uNumMeshes.value = 1;
+    this.velocityVar.material.uniforms.uNumMeshes.value = 1;
+    this.positionVar.material.uniforms.uSingleTextureSize.value = size;
+    this.velocityVar.material.uniforms.uSingleTextureSize.value = size;
+    this.positionVar.material.uniforms.uCurrentVelocity.value = this.gpuComputationRenderer.getCurrentRenderTarget(this.velocityVar).texture;
+    this.velocityVar.material.uniforms.uCurrentPosition.value = this.gpuComputationRenderer.getCurrentRenderTarget(this.positionVar).texture;
+    this.lastKnownVelocityDataTexture = this.gpuComputationRenderer.getCurrentRenderTarget(this.velocityVar).texture;
+    this.lastKnownPositionDataTexture = this.gpuComputationRenderer.getCurrentRenderTarget(this.positionVar).texture;
   }
   /**
-   * Sets the source data texture for morphing.
-   * @param texture The source data texture.
+   * Sets the mesh sequence position atlas texture and related uniforms.
+   * @param entry Information about the atlas texture.
    */
-  setMorphSourceDataTexture(texture) {
-    this.mixPositionsVar.material.uniforms.uPositionA.value = texture;
+  setPositionAtlas(entry) {
+    const expectedAtlasWidth = entry.singleTextureSize * entry.numMeshes;
+    if (entry.dataTexture.image.width !== expectedAtlasWidth || entry.dataTexture.image.height !== entry.singleTextureSize) {
+      console.error(
+        `SimulationRenderer: Atlas texture dimension mismatch! Expected ${expectedAtlasWidth}x${entry.singleTextureSize}, Got ${entry.dataTexture.image.width}x${entry.dataTexture.image.height}`
+      );
+    }
+    this.positionAtlasTexture = entry.dataTexture;
+    const numMeshes = entry.numMeshes > 0 ? entry.numMeshes : 1;
+    this.positionVar.material.uniforms.uPositionAtlas.value = this.positionAtlasTexture;
+    this.positionVar.material.uniforms.uNumMeshes.value = numMeshes;
+    this.positionVar.material.uniforms.uSingleTextureSize.value = entry.singleTextureSize;
+    this.velocityVar.material.uniforms.uPositionAtlas.value = this.positionAtlasTexture;
+    this.velocityVar.material.uniforms.uNumMeshes.value = numMeshes;
+    this.velocityVar.material.uniforms.uSingleTextureSize.value = entry.singleTextureSize;
+    this.positionVar.material.uniforms.uCurrentVelocity.value = this.gpuComputationRenderer.getCurrentRenderTarget(this.velocityVar).texture;
+    this.velocityVar.material.uniforms.uCurrentPosition.value = this.gpuComputationRenderer.getCurrentRenderTarget(this.positionVar).texture;
   }
   /**
-   * Sets the destination data texture for morphing.
-   * @param texture The destination data texture.
+   * Sets the overall progress for blending between meshes in the atlas.
+   * @param progress Value between 0.0 and 1.0.
    */
-  setMorphDestinationDataTexture(texture) {
-    this.mixPositionsVar.material.uniforms.uPositionB.value = texture;
+  setOverallProgress(progress) {
+    const clampedProgress = clamp(progress, 0, 1);
+    this.positionVar.material.uniforms.uOverallProgress.value = clampedProgress;
+    this.velocityVar.material.uniforms.uOverallProgress.value = clampedProgress;
   }
   setMaxRepelDistance(distance) {
     this.velocityVar.material.uniforms.uMaxRepelDistance.value = distance;
   }
-  /**
-   * Sets the progress of the morphing animation.
-   * @param progress The progress value, between 0 and 1.
-   */
-  setProgress(progress) {
-    this.lastKnownMixProgress = clamp(progress, 0, 1);
-    this.mixPositionsVar.material.uniforms.uProgress.value = this.lastKnownMixProgress;
-  }
   setVelocityTractionForce(force) {
     this.velocityVar.material.uniforms.uTractionForce.value = force;
   }
@@ -1273,36 +1554,31 @@ class SimulationRenderer {
    * Disposes the resources used by the simulation renderer.
    */
   dispose() {
-    this.mixPositionsVar.renderTargets.forEach((rtt) => rtt.dispose());
-    this.positionVar.renderTargets.forEach((rtt) => rtt.dispose());
-    this.velocityVar.renderTargets.forEach((rtt) => rtt.dispose());
-    this.positionDataTexture.dispose();
-    this.velocityDataTexture.dispose();
+    var _a, _b;
     this.gpuComputationRenderer.dispose();
+    (_a = this.initialPositionDataTexture) == null ? void 0 : _a.dispose();
+    (_b = this.initialVelocityDataTexture) == null ? void 0 : _b.dispose();
+    this.positionAtlasTexture = null;
   }
   /**
    * Computes the next step of the simulation.
-   * @param elapsedTime The elapsed time since the simulation started.
+   * @param deltaTime The time elapsed since the last frame, in seconds.
    */
-  compute(elapsedTime) {
-    this.velocityVar.material.uniforms.uTime.value = elapsedTime;
-    this.positionVar.material.uniforms.uTime.value = elapsedTime;
+  compute(deltaTime) {
+    this.velocityVar.material.uniforms.uTime.value += deltaTime;
+    this.positionVar.material.uniforms.uTime.value += deltaTime;
+    this.positionVar.material.uniforms.uCurrentVelocity.value = this.gpuComputationRenderer.getCurrentRenderTarget(this.velocityVar).texture;
+    this.velocityVar.material.uniforms.uCurrentPosition.value = this.gpuComputationRenderer.getCurrentRenderTarget(this.positionVar).texture;
     this.gpuComputationRenderer.compute();
+    this.lastKnownVelocityDataTexture = this.gpuComputationRenderer.getCurrentRenderTarget(this.velocityVar).texture;
+    this.lastKnownPositionDataTexture = this.gpuComputationRenderer.getCurrentRenderTarget(this.positionVar).texture;
   }
-  /**
-   * Gets the current velocity texture.
-   * @returns The current velocity texture.
-   */
+  /** Gets the current velocity texture (output from the last compute step). */
   getVelocityTexture() {
-    this.lastKnownVelocityDataTexture = this.gpuComputationRenderer.getCurrentRenderTarget(this.velocityVar).texture;
     return this.lastKnownVelocityDataTexture;
   }
-  /**
-   * Gets the current position texture.
-   * @returns The current position texture.
-   */
+  /** Gets the current position texture (output from the last compute step). */
   getPositionTexture() {
-    this.lastKnownPositionDataTexture = this.gpuComputationRenderer.getCurrentRenderTarget(this.positionVar).texture;
     return this.lastKnownPositionDataTexture;
   }
 }
@@ -1310,18 +1586,22 @@ class SimulationRendererService {
   constructor(eventEmitter, size, webGLRenderer) {
     __publicField(this, "state");
     __publicField(this, "textureSize");
-    __publicField(this, "dataTextureTransitionProgress");
+    __publicField(this, "overallProgress");
+    // ADDED: Store overall progress
     __publicField(this, "velocityTractionForce");
     __publicField(this, "positionalTractionForce");
     __publicField(this, "simulationRenderer");
     __publicField(this, "webGLRenderer");
     __publicField(this, "eventEmitter");
+    // Store atlas info
+    __publicField(this, "currentAtlasEntry", null);
+    // ADDED
     __publicField(this, "lastKnownVelocityDataTexture");
     __publicField(this, "lastKnownPositionDataTexture");
     this.eventEmitter = eventEmitter;
     this.webGLRenderer = webGLRenderer;
     this.textureSize = size;
-    this.dataTextureTransitionProgress = 0;
+    this.overallProgress = 0;
     this.velocityTractionForce = 0.1;
     this.positionalTractionForce = 0.1;
     this.updateServiceState("initializing");
@@ -1330,6 +1610,27 @@ class SimulationRendererService {
     this.lastKnownPositionDataTexture = this.simulationRenderer.getPositionTexture();
     this.updateServiceState("ready");
   }
+  /**
+   * Sets the position data texture atlas for the simulation.
+   * @param entry An object containing the atlas texture and related parameters.
+   */
+  setPositionAtlas(entry) {
+    const expectedWidth = entry.singleTextureSize * entry.numMeshes;
+    if (entry.dataTexture.image.width !== expectedWidth) {
+      this.eventEmitter.emit("invalidRequest", { message: `Atlas texture width mismatch.` });
+      return;
+    }
+    this.currentAtlasEntry = entry;
+    this.simulationRenderer.setPositionAtlas(entry);
+  }
+  /**
+   * Sets the overall progress for the mesh sequence transition.
+   * @param progress The progress value (0.0 to 1.0).
+   */
+  setOverallProgress(progress) {
+    this.overallProgress = progress;
+    this.simulationRenderer.setOverallProgress(this.overallProgress);
+  }
   setTextureSize(size) {
     this.updateServiceState("initializing");
     this.simulationRenderer.dispose();
@@ -1337,24 +1638,6 @@ class SimulationRendererService {
     this.simulationRenderer = new SimulationRenderer(size, this.webGLRenderer);
     this.updateServiceState("ready");
   }
-  setOriginDataTexture(entry) {
-    if (this.textureSize !== entry.textureSize) {
-      this.eventEmitter.emit("invalidRequest", { message: `Texture size mismatch: ${entry.textureSize} vs ${this.textureSize}` });
-    } else {
-      this.simulationRenderer.setMorphSourceDataTexture(entry.dataTexture);
-    }
-  }
-  setDestinationDataTexture(entry) {
-    if (this.textureSize !== entry.textureSize) {
-      this.eventEmitter.emit("invalidRequest", { message: `Texture size mismatch: ${entry.textureSize} vs ${this.textureSize}` });
-    } else {
-      this.simulationRenderer.setMorphDestinationDataTexture(entry.dataTexture);
-    }
-  }
-  setDataTextureTransitionProgress(progress) {
-    this.dataTextureTransitionProgress = progress;
-    this.simulationRenderer.setProgress(this.dataTextureTransitionProgress);
-  }
   setVelocityTractionForce(force) {
     this.velocityTractionForce = force;
     this.simulationRenderer.setVelocityTractionForce(this.velocityTractionForce);
@@ -1364,21 +1647,21 @@ class SimulationRendererService {
     this.simulationRenderer.setPositionalTractionForce(this.positionalTractionForce);
   }
   compute(elapsedTime) {
+    if (this.state !== "ready") return;
     this.simulationRenderer.compute(elapsedTime);
+    this.lastKnownVelocityDataTexture = this.simulationRenderer.getVelocityTexture();
+    this.lastKnownPositionDataTexture = this.simulationRenderer.getPositionTexture();
   }
   getVelocityTexture() {
-    if (this.state === "ready") this.lastKnownVelocityDataTexture = this.simulationRenderer.getVelocityTexture();
     return this.lastKnownVelocityDataTexture;
   }
   getPositionTexture() {
-    if (this.state === "ready") this.lastKnownPositionDataTexture = this.simulationRenderer.getPositionTexture();
     return this.lastKnownPositionDataTexture;
   }
   dispose() {
     this.updateServiceState("disposed");
     this.simulationRenderer.dispose();
-    this.lastKnownVelocityDataTexture.dispose();
-    this.lastKnownPositionDataTexture.dispose();
+    this.currentAtlasEntry = null;
   }
   updateServiceState(serviceState) {
     this.state = serviceState;
@@ -1495,7 +1778,6 @@ class ParticlesEngine {
    */
   constructor(params) {
     __publicField(this, "simulationRendererService");
-    __publicField(this, "eventEmitter");
     __publicField(this, "renderer");
     __publicField(this, "scene");
     __publicField(this, "serviceStates");
@@ -1506,6 +1788,9 @@ class ParticlesEngine {
     __publicField(this, "transitionService");
     __publicField(this, "engineState");
     __publicField(this, "intersectionService");
+    __publicField(this, "meshSequenceAtlasTexture", null);
+    // ADDED: To store the generated atlas
+    __publicField(this, "eventEmitter");
     const { scene, renderer, camera, textureSize, useIntersection = true } = params;
     this.eventEmitter = new DefaultEventEmitter();
     this.serviceStates = this.getInitialServiceStates();
@@ -1522,7 +1807,6 @@ class ParticlesEngine {
     this.scene.add(this.instancedMeshManager.getMesh());
     this.intersectionService = new IntersectionService(this.eventEmitter, camera);
     if (!useIntersection) this.intersectionService.setActive(false);
-    this.eventEmitter.on("transitionProgressed", this.handleTransitionProgress.bind(this));
     this.eventEmitter.on("interactionPositionUpdated", this.handleInteractionPositionUpdated.bind(this));
   }
   /**
@@ -1530,48 +1814,14 @@ class ParticlesEngine {
    * @param elapsedTime The elapsed time since the last frame.
    */
   render(elapsedTime) {
+    const dt = elapsedTime / 1e3;
+    this.transitionService.compute(dt);
     this.intersectionService.calculate(this.instancedMeshManager.getMesh());
-    this.transitionService.compute(elapsedTime);
-    this.simulationRendererService.compute(elapsedTime);
-    this.instancedMeshManager.update(elapsedTime);
+    this.simulationRendererService.compute(dt);
+    this.instancedMeshManager.update(dt);
     this.instancedMeshManager.updateVelocityTexture(this.simulationRendererService.getVelocityTexture());
     this.instancedMeshManager.updatePositionTexture(this.simulationRendererService.getPositionTexture());
   }
-  setOriginDataTexture(meshID, override = false) {
-    if (override) this.eventEmitter.emit("transitionCancelled", { type: "data-texture" });
-    const mesh = this.assetService.getMesh(meshID);
-    if (!mesh) {
-      this.eventEmitter.emit("invalidRequest", { message: `Mesh with id "${meshID}" does not exist` });
-      return;
-    }
-    this.dataTextureManager.getDataTexture(mesh).then((dataTexture) => {
-      this.engineState.originMeshID = meshID;
-      this.simulationRendererService.setOriginDataTexture({ dataTexture, textureSize: this.engineState.textureSize });
-      this.intersectionService.setOriginGeometry(mesh);
-    });
-  }
-  setDestinationDataTexture(meshID, override = false) {
-    if (override) this.eventEmitter.emit("transitionCancelled", { type: "data-texture" });
-    const mesh = this.assetService.getMesh(meshID);
-    if (!mesh) {
-      this.eventEmitter.emit("invalidRequest", { message: `Mesh with id "${meshID}" does not exist` });
-      return;
-    }
-    this.dataTextureManager.getDataTexture(mesh).then((texture) => {
-      this.engineState.destinationMeshID = meshID;
-      this.simulationRendererService.setDestinationDataTexture({
-        dataTexture: texture,
-        textureSize: this.engineState.textureSize
-      });
-      this.intersectionService.setDestinationGeometry(mesh);
-    });
-  }
-  setDataTextureTransitionProgress(progress, override = false) {
-    if (override) this.eventEmitter.emit("transitionCancelled", { type: "data-texture" });
-    this.engineState.dataTextureTransitionProgress = progress;
-    this.simulationRendererService.setDataTextureTransitionProgress(progress);
-    this.intersectionService.setProgress(progress);
-  }
   setOriginMatcap(matcapID, override = false) {
     if (override) this.eventEmitter.emit("transitionCancelled", { type: "matcap" });
     this.engineState.originMatcapID = matcapID;
@@ -1607,40 +1857,31 @@ class ParticlesEngine {
     }
   }
   setMatcapProgress(progress, override = false) {
+    const clampedProgress = clamp(progress, 0, 1);
     if (override) this.eventEmitter.emit("transitionCancelled", { type: "matcap" });
-    this.engineState.matcapTransitionProgress = progress;
-    this.instancedMeshManager.setProgress(progress);
+    this.engineState.matcapTransitionProgress = clampedProgress;
+    this.instancedMeshManager.setProgress(clampedProgress);
   }
+  // --- Update setTextureSize ---
   async setTextureSize(size) {
+    if (this.engineState.textureSize === size) {
+      return;
+    }
     this.engineState.textureSize = size;
     this.dataTextureManager.setTextureSize(size);
     this.simulationRendererService.setTextureSize(size);
     this.instancedMeshManager.resize(size);
-    const originMesh = this.assetService.getMesh(this.engineState.originMeshID);
-    if (!originMesh) {
-      this.eventEmitter.emit("invalidRequest", { message: `Mesh with id "${this.engineState.originMeshID}" does not exist` });
-      return;
+    if (this.engineState.meshSequence.length > 0) {
+      await this.setMeshSequence(this.engineState.meshSequence);
     }
-    const destinationMesh = this.assetService.getMesh(this.engineState.destinationMeshID);
-    if (!destinationMesh) {
-      this.eventEmitter.emit("invalidRequest", { message: `Mesh with id "${this.engineState.destinationMeshID}" does not exist` });
-      return;
+    if (this.engineState.meshSequence.length > 0) {
+      await this.setMeshSequence(this.engineState.meshSequence);
     }
-    this.dataTextureManager.getDataTexture(originMesh).then(
-      (texture) => this.simulationRendererService.setOriginDataTexture({
-        dataTexture: texture,
-        textureSize: size
-      })
-    );
-    this.dataTextureManager.getDataTexture(destinationMesh).then(
-      (texture) => this.simulationRendererService.setDestinationDataTexture({
-        dataTexture: texture,
-        textureSize: size
-      })
-    );
-    this.simulationRendererService.setDataTextureTransitionProgress(this.engineState.dataTextureTransitionProgress);
     this.simulationRendererService.setVelocityTractionForce(this.engineState.velocityTractionForce);
     this.simulationRendererService.setPositionalTractionForce(this.engineState.positionalTractionForce);
+    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);
@@ -1663,7 +1904,7 @@ class ParticlesEngine {
     this.engineState.useIntersect = use;
     if (!use) {
       this.engineState.pointerPosition = { x: -99999999, y: -99999999 };
-      this.intersectionService.setPointerPosition(this.engineState.pointerPosition);
+      this.simulationRendererService.setInteractionPosition({ x: 0, y: 0, z: 0, w: 0 });
     }
   }
   setPointerPosition(position) {
@@ -1687,50 +1928,170 @@ class ParticlesEngine {
     this.engineState.maxRepelDistance = distance;
     this.simulationRendererService.setMaxRepelDistance(distance);
   }
-  scheduleMeshTransition(originMeshID, destinationMeshID, easing = linear, duration = 1e3, override = false) {
-    this.transitionService.enqueue(
-      "data-texture",
-      { easing, duration },
-      {
-        onTransitionBegin: () => {
-          this.setOriginDataTexture(originMeshID, override);
-          this.setDestinationDataTexture(destinationMeshID, override);
-          this.setDataTextureTransitionProgress(0);
-        }
+  /**
+   * Sets the sequence of meshes for particle transitions.
+   * This will generate a texture atlas containing position data for all meshes.
+   * @param meshIDs An array of registered mesh IDs in the desired sequence order.
+   */
+  async setMeshSequence(meshIDs) {
+    if (!meshIDs || meshIDs.length < 1) {
+      this.eventEmitter.emit("invalidRequest", { message: "Mesh sequence must contain at least one mesh ID." });
+      this.engineState.meshSequence = [];
+      this.intersectionService.setMeshSequence([]);
+      return;
+    }
+    this.engineState.meshSequence = meshIDs;
+    this.engineState.overallProgress = 0;
+    const meshes = meshIDs.map((id) => this.assetService.getMesh(id)).filter((mesh) => mesh !== null);
+    if (meshes.length !== meshIDs.length) {
+      const missing = meshIDs.filter((id) => !this.assetService.getMesh(id));
+      console.warn(`Could not find meshes for IDs: ${missing.join(", ")}. Proceeding with ${meshes.length} found meshes.`);
+      this.eventEmitter.emit("invalidRequest", { message: `Could not find meshes for IDs: ${missing.join(", ")}` });
+      if (meshes.length < 1) {
+        this.engineState.meshSequence = [];
+        this.intersectionService.setMeshSequence([]);
+        return;
       }
-    );
+      this.engineState.meshSequence = meshes.map((m) => m.name);
+    }
+    try {
+      this.meshSequenceAtlasTexture = await this.dataTextureManager.createSequenceDataTextureAtlas(meshes, this.engineState.textureSize);
+      this.simulationRendererService.setPositionAtlas({
+        dataTexture: this.meshSequenceAtlasTexture,
+        textureSize: this.engineState.textureSize,
+        // Pass the size of the *output* GPGPU texture
+        numMeshes: this.engineState.meshSequence.length,
+        // Use the potentially updated count
+        singleTextureSize: this.engineState.textureSize
+        // Size of one mesh's data within atlas
+      });
+      this.simulationRendererService.setOverallProgress(this.engineState.overallProgress);
+      this.intersectionService.setMeshSequence(meshes);
+      this.intersectionService.setOverallProgress(this.engineState.overallProgress);
+    } catch (error) {
+      console.error("Failed during mesh sequence setup:", error);
+      this.meshSequenceAtlasTexture = null;
+    }
+  }
+  /**
+   * Sets the overall progress through the mesh sequence.
+   * @param progress A value between 0.0 (first mesh) and 1.0 (last mesh).
+   * @param override If true, cancels any ongoing mesh sequence transition before setting the value. Defaults to true.
+   */
+  setOverallProgress(progress, override = true) {
+    if (override) {
+      this.eventEmitter.emit("transitionCancelled", { type: "mesh-sequence" });
+    }
+    const clampedProgress = clamp(progress, 0, 1);
+    this.engineState.overallProgress = clampedProgress;
+    this.simulationRendererService.setOverallProgress(clampedProgress);
+    this.intersectionService.setOverallProgress(clampedProgress);
   }
-  scheduleMatcapTransition(originMatcapID, destinationMatcapID, easing = linear, duration = 1e3, override = false) {
+  // --- 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: () => {
-          this.setOriginMatcap(originMatcapID, override);
-          this.setDestinationMatcap(destinationMatcapID, override);
-          this.setMatcapProgress(0);
-        }
+          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) {
+  scheduleTextureTransition(origin, destination, options = {}) {
     const easing = (options == null ? void 0 : options.easing) ?? linear;
     const duration = (options == null ? void 0 : options.duration) ?? 1e3;
-    if (options == null ? void 0 : options.override) {
-      this.eventEmitter.emit("transitionCancelled", { type: "matcap" });
-    }
+    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);
         }
       }
     );
   }
+  /**
+   * Schedules a smooth transition for the overall mesh sequence progress.
+   * @param targetProgress The final progress value (0.0 to 1.0) to transition to.
+   * @param duration Duration of the transition in milliseconds.
+   * @param easing Easing function to use.
+   * @param options Transition options (onBegin, onProgress, onFinished, onCancelled).
+   * @param override If true, cancels any ongoing mesh sequence transitions.
+   */
+  scheduleMeshSequenceTransition(targetProgress, duration = 1e3, easing = linear, options = {}, override = true) {
+    if (override) this.eventEmitter.emit("transitionCancelled", { type: "mesh-sequence" });
+    const startProgress = this.engineState.overallProgress;
+    const progressDiff = targetProgress - startProgress;
+    const handleProgressUpdate = (transitionProgress) => {
+      var _a;
+      const currentOverallProgress = startProgress + progressDiff * transitionProgress;
+      this.setOverallProgress(currentOverallProgress, false);
+      (_a = options.onTransitionProgress) == null ? void 0 : _a.call(options, currentOverallProgress);
+    };
+    const transitionDetail = { duration, easing };
+    const transitionOptions = {
+      ...options,
+      onTransitionProgress: handleProgressUpdate,
+      onTransitionBegin: options.onTransitionBegin,
+      onTransitionFinished: () => {
+        var _a;
+        this.setOverallProgress(targetProgress, false);
+        (_a = options.onTransitionFinished) == null ? void 0 : _a.call(options);
+      },
+      onTransitionCancelled: options.onTransitionCancelled
+    };
+    this.transitionService.enqueue("mesh-sequence", transitionDetail, transitionOptions);
+  }
   handleServiceStateUpdated({ type, state }) {
     this.serviceStates[type] = state;
   }
@@ -1749,23 +2110,37 @@ class ParticlesEngine {
   getTextures() {
     return this.assetService.getTextures();
   }
+  getTextureSize() {
+    return this.engineState.textureSize;
+  }
+  getUseIntersect() {
+    return this.engineState.useIntersect;
+  }
+  getEngineStateSnapshot() {
+    return { ...this.engineState };
+  }
   /**
    * Disposes the resources used by the engine.
    */
   dispose() {
-    this.scene.remove(this.instancedMeshManager.getMesh());
-    this.simulationRendererService.dispose();
-    this.instancedMeshManager.dispose();
-    this.intersectionService.dispose();
-    this.assetService.dispose();
-    this.dataTextureManager.dispose();
+    var _a, _b, _c, _d, _e, _f;
+    if (this.scene && this.instancedMeshManager) {
+      this.scene.remove(this.instancedMeshManager.getMesh());
+    }
+    (_a = this.simulationRendererService) == null ? void 0 : _a.dispose();
+    (_b = this.instancedMeshManager) == null ? void 0 : _b.dispose();
+    (_c = this.intersectionService) == null ? void 0 : _c.dispose();
+    (_d = this.assetService) == null ? void 0 : _d.dispose();
+    (_e = this.dataTextureManager) == null ? void 0 : _e.dispose();
+    (_f = this.eventEmitter) == null ? void 0 : _f.dispose();
   }
   initialEngineState(params) {
     return {
       textureSize: params.textureSize,
-      originMeshID: "",
-      destinationMeshID: "",
-      dataTextureTransitionProgress: 0,
+      meshSequence: [],
+      // ADDED
+      overallProgress: 0,
+      // ADDED
       originMatcapID: "",
       destinationMatcapID: "",
       matcapTransitionProgress: 0,
@@ -1786,16 +2161,6 @@ class ParticlesEngine {
       asset: "created"
     };
   }
-  handleTransitionProgress({ type, progress }) {
-    switch (type) {
-      case "data-texture":
-        this.setDataTextureTransitionProgress(progress);
-        break;
-      case "matcap":
-        this.setMatcapProgress(progress);
-        break;
-    }
-  }
   handleInteractionPositionUpdated({ position }) {
     this.simulationRendererService.setInteractionPosition(position);
   }