@triforge/particle-core 0.1.0

package/dist/core/BaseEmitter.d.ts

@@ -0,0 +1,50 @@
+import { Vector3, BufferGeometry } from 'three';
+import type { Particle } from './Particle.js';
+import type { SeededRandom } from './SeededRandom.js';
+export type EmitFrom = 'verts' | 'faces' | 'volume';
+export interface BaseEmitterOptions {
+    /** Velocity along face/vertex normal (Blender: Normal) */
+    normalVelocity?: number;
+    /** Velocity along surface tangent (Blender: Tangent) */
+    tangentVelocity?: number;
+    /** Tangent rotation offset in radians (Blender: Tangent Phase) */
+    tangentPhase?: number;
+    /** Velocity along emitter object X axis (Blender: Object Align X) */
+    objectVelocityX?: number;
+    /** Velocity along emitter object Y axis (Blender: Object Align Y) */
+    objectVelocityY?: number;
+    /** Velocity along emitter object Z axis (Blender: Object Align Z) */
+    objectVelocityZ?: number;
+    /** Fraction of emitter object velocity inherited (Blender: Object Velocity) */
+    objectInherit?: number;
+    /** Random velocity magnitude (Blender: Randomise) */
+    randomVelocity?: number;
+    /** Where on the mesh to emit from (Blender: Emit From) */
+    emitFrom?: EmitFrom;
+    /** Distribute evenly across surface area (Blender: Even Distribution) */
+    evenDistribution?: boolean;
+}
+/**
+ * Abstract base — knows how to sample a spawn point from a geometry
+ * and write initial position/velocity onto a Particle.
+ *
+ * Concrete subclasses: PointEmitter, MeshEmitter, EdgeEmitter.
+ */
+export declare abstract class BaseEmitter {
+    /** Blender-matched public parameters — GSAP / keyframe compatible */
+    parameters: Record<string, number>;
+    /**
+     * World-space velocity of the emitter object (set externally each frame).
+     * Blender: Velocity → Object Velocity — particles inherit this × objectInherit.
+     */
+    worldVelocity: Vector3;
+    constructor(opts?: BaseEmitterOptions);
+    /**
+     * Write spawn position and initial velocity onto the particle.
+     * Called by ParticleSystem each time a particle is born.
+     */
+    abstract spawn(particle: Particle, geometry: BufferGeometry | null, rng: SeededRandom): void;
+    /** Apply velocity parameters after spawn point is set */
+    protected applyVelocity(particle: Particle, normal: Vector3, tangent: Vector3, rng: SeededRandom): void;
+}
+//# sourceMappingURL=BaseEmitter.d.ts.map

package/dist/core/BaseEmitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseEmitter.d.ts","sourceRoot":"","sources":["../../src/core/BaseEmitter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGrD,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEnD,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,cAAc,CAAC,EAAI,MAAM,CAAA;IACzB,wDAAwD;IACxD,eAAe,CAAC,EAAG,MAAM,CAAA;IACzB,kEAAkE;IAClE,YAAY,CAAC,EAAM,MAAM,CAAA;IACzB,qEAAqE;IACrE,eAAe,CAAC,EAAG,MAAM,CAAA;IACzB,qEAAqE;IACrE,eAAe,CAAC,EAAG,MAAM,CAAA;IACzB,qEAAqE;IACrE,eAAe,CAAC,EAAG,MAAM,CAAA;IACzB,+EAA+E;IAC/E,aAAa,CAAC,EAAK,MAAM,CAAA;IACzB,qDAAqD;IACrD,cAAc,CAAC,EAAI,MAAM,CAAA;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,EAAU,QAAQ,CAAA;IAC3B,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED;;;;;GAKG;AACH,8BAAsB,WAAW;IAC/B,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAElC;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAgB;gBAE1B,IAAI,GAAE,kBAAuB;IAgBzC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CACZ,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,cAAc,GAAG,IAAI,EAC/B,GAAG,EAAE,YAAY,GAChB,IAAI;IAEP,yDAAyD;IACzD,SAAS,CAAC,aAAa,CACrB,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,YAAY,GAChB,IAAI;CA2BR"}

package/dist/core/BaseEmitter.js

@@ -0,0 +1,53 @@
+import { Vector3 } from 'three';
+/**
+ * Abstract base — knows how to sample a spawn point from a geometry
+ * and write initial position/velocity onto a Particle.
+ *
+ * Concrete subclasses: PointEmitter, MeshEmitter, EdgeEmitter.
+ */
+export class BaseEmitter {
+    constructor(opts = {}) {
+        /**
+         * World-space velocity of the emitter object (set externally each frame).
+         * Blender: Velocity → Object Velocity — particles inherit this × objectInherit.
+         */
+        this.worldVelocity = new Vector3();
+        this.parameters = {
+            normalVelocity: opts.normalVelocity ?? 0,
+            tangentVelocity: opts.tangentVelocity ?? 0,
+            tangentPhase: opts.tangentPhase ?? 0,
+            objectVelocityX: opts.objectVelocityX ?? 0,
+            objectVelocityY: opts.objectVelocityY ?? 0,
+            objectVelocityZ: opts.objectVelocityZ ?? 0,
+            objectInherit: opts.objectInherit ?? 0,
+            randomVelocity: opts.randomVelocity ?? 0,
+            // emitFrom stored as 0=verts, 1=faces, 2=volume
+            emitFrom: opts.emitFrom === 'faces' ? 1 : opts.emitFrom === 'volume' ? 2 : 0,
+            evenDistribution: opts.evenDistribution ? 1 : 0,
+        };
+    }
+    /** Apply velocity parameters after spawn point is set */
+    applyVelocity(particle, normal, tangent, rng) {
+        const p = this.parameters;
+        // Normal component
+        particle.velocity.addScaledVector(normal, p.normalVelocity);
+        // Tangent component (rotated by tangentPhase)
+        const t = tangent.clone().applyAxisAngle(normal, p.tangentPhase);
+        particle.velocity.addScaledVector(t, p.tangentVelocity);
+        // Object-axis components
+        particle.velocity.x += p.objectVelocityX;
+        particle.velocity.y += p.objectVelocityY;
+        particle.velocity.z += p.objectVelocityZ;
+        // Random component
+        if (p.randomVelocity > 0) {
+            particle.velocity.x += rng.signed() * p.randomVelocity;
+            particle.velocity.y += rng.signed() * p.randomVelocity;
+            particle.velocity.z += rng.signed() * p.randomVelocity;
+        }
+        // Emitter object velocity inheritance (Blender: Object Velocity)
+        if (p.objectInherit !== 0) {
+            particle.velocity.addScaledVector(this.worldVelocity, p.objectInherit);
+        }
+    }
+}
+//# sourceMappingURL=BaseEmitter.js.map

package/dist/core/BaseEmitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseEmitter.js","sourceRoot":"","sources":["../../src/core/BaseEmitter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAkB,MAAM,OAAO,CAAA;AA8B/C;;;;;GAKG;AACH,MAAM,OAAgB,WAAW;IAU/B,YAAY,OAA2B,EAAE;QANzC;;;WAGG;QACH,kBAAa,GAAY,IAAI,OAAO,EAAE,CAAA;QAGpC,IAAI,CAAC,UAAU,GAAG;YAChB,cAAc,EAAI,IAAI,CAAC,cAAc,IAAK,CAAC;YAC3C,eAAe,EAAG,IAAI,CAAC,eAAe,IAAI,CAAC;YAC3C,YAAY,EAAM,IAAI,CAAC,YAAY,IAAO,CAAC;YAC3C,eAAe,EAAG,IAAI,CAAC,eAAe,IAAI,CAAC;YAC3C,eAAe,EAAG,IAAI,CAAC,eAAe,IAAI,CAAC;YAC3C,eAAe,EAAG,IAAI,CAAC,eAAe,IAAI,CAAC;YAC3C,aAAa,EAAK,IAAI,CAAC,aAAa,IAAM,CAAC;YAC3C,cAAc,EAAI,IAAI,CAAC,cAAc,IAAK,CAAC;YAC3C,gDAAgD;YAChD,QAAQ,EAAU,IAAI,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACpF,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAChD,CAAA;IACH,CAAC;IAYD,yDAAyD;IAC/C,aAAa,CACrB,QAAkB,EAClB,MAAe,EACf,OAAgB,EAChB,GAAiB;QAEjB,MAAM,CAAC,GAAG,IAAI,CAAC,UAAU,CAAA;QAEzB,mBAAmB;QACnB,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC,cAAc,CAAC,CAAA;QAE3D,8CAA8C;QAC9C,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC,YAAY,CAAC,CAAA;QAChE,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,eAAe,CAAC,CAAA;QAEvD,yBAAyB;QACzB,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,eAAe,CAAA;QACxC,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,eAAe,CAAA;QACxC,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,eAAe,CAAA;QAExC,mBAAmB;QACnB,IAAI,CAAC,CAAC,cAAc,GAAG,CAAC,EAAE,CAAC;YACzB,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,cAAc,CAAA;YACtD,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,cAAc,CAAA;YACtD,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,cAAc,CAAA;QACxD,CAAC;QAED,iEAAiE;QACjE,IAAI,CAAC,CAAC,aAAa,KAAK,CAAC,EAAE,CAAC;YAC1B,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,CAAA;QACxE,CAAC;IACH,CAAC;CACF"}

package/dist/core/BaseForce.d.ts

@@ -0,0 +1,21 @@
+import type { Particle } from './Particle.js';
+/**
+ * Abstract base for all force field effectors.
+ * Each force receives a particle and a dt, and mutates particle.velocity.
+ *
+ * Concrete subclasses: GravityForce, WindForce, VortexForce, DragForce,
+ * TurbulenceForce, MagneticForce, HarmonicForce, ChargeForce,
+ * LennardJonesForce, TextureForce, DragFieldForce.
+ */
+export declare abstract class BaseForce {
+    /** Whether this force is currently active */
+    enabled: boolean;
+    /** Blender-matched public parameters — GSAP / keyframe compatible */
+    abstract parameters: Record<string, number>;
+    /**
+     * Apply force to a single particle for one timestep.
+     * Mutates particle.velocity only — never position.
+     */
+    abstract apply(particle: Particle, dt: number): void;
+}
+//# sourceMappingURL=BaseForce.d.ts.map

package/dist/core/BaseForce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseForce.d.ts","sourceRoot":"","sources":["../../src/core/BaseForce.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE7C;;;;;;;GAOG;AACH,8BAAsB,SAAS;IAC7B,6CAA6C;IAC7C,OAAO,UAAO;IAEd,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAE3C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;CACrD"}

package/dist/core/BaseForce.js

@@ -0,0 +1,15 @@
+/**
+ * Abstract base for all force field effectors.
+ * Each force receives a particle and a dt, and mutates particle.velocity.
+ *
+ * Concrete subclasses: GravityForce, WindForce, VortexForce, DragForce,
+ * TurbulenceForce, MagneticForce, HarmonicForce, ChargeForce,
+ * LennardJonesForce, TextureForce, DragFieldForce.
+ */
+export class BaseForce {
+    constructor() {
+        /** Whether this force is currently active */
+        this.enabled = true;
+    }
+}
+//# sourceMappingURL=BaseForce.js.map

package/dist/core/BaseForce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseForce.js","sourceRoot":"","sources":["../../src/core/BaseForce.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,OAAgB,SAAS;IAA/B;QACE,6CAA6C;QAC7C,YAAO,GAAG,IAAI,CAAA;IAUhB,CAAC;CAAA"}

package/dist/core/BaseRenderer.d.ts

@@ -0,0 +1,96 @@
+import type { Object3D } from 'three';
+import type { SeededRandom } from './SeededRandom.js';
+/**
+ * Structural interface satisfied by both Particle and the pre-allocated
+ * child draw-buffer entries.  Renderers iterate this instead of Particle[]
+ * so children (which are not real pool particles) can pass through the same
+ * draw loop.
+ */
+export interface ParticleLike {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    velocity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    size: number;
+    normalised: number;
+    alive: boolean;
+    lifetime: number;
+    age: number;
+    emitterIndex: number;
+}
+/** Pre-allocated draw-buffer entry — also carries the parent pool index. */
+interface DrawEntry extends ParticleLike {
+    poolIdx: number;
+}
+/**
+ * Abstract base for all particle renderers.
+ * A renderer owns a Three.js Object3D and updates it each tick
+ * from the live particle array.
+ *
+ * Concrete subclasses: BillboardRenderer, InstanceRenderer, LineRenderer.
+ */
+export declare abstract class BaseRenderer {
+    /** The Three.js object to add to the scene */
+    abstract readonly object3D: Object3D;
+    /**
+     * Show or hide the particle helper geometry.
+     * In Blender this is the viewport dot/sphere representation —
+     * hidden in final renders. Set false to see only the resulting
+     * mesh/material assigned to the particles, not the placeholders.
+     */
+    get visible(): boolean;
+    set visible(v: boolean);
+    /**
+     * Called once per frame with the full particle pool.
+     * Update GPU buffers here — no allocations allowed inside this method.
+     *
+     * params and childRng are optional so that legacy callers (unit tests) that
+     * pass only (particles, aliveCount) still work — children are disabled when
+     * params is omitted or params.childCount is 0.
+     */
+    abstract update(particles: ParticleLike[], aliveCount: number, params?: Record<string, number>, childRng?: SeededRandom): void;
+    /** Free GPU resources */
+    abstract dispose(): void;
+    /**
+     * Pre-allocated draw buffer — filled each frame by expandWithChildren().
+     * Concrete constructors must call _allocDrawBuf(maxCount) to initialise it.
+     */
+    protected _drawBuf: DrawEntry[];
+    /**
+     * Pre-allocated alive-particle scratch list — filled inside expandWithChildren
+     * for the interpolated pass without heap allocations.
+     */
+    protected _aliveBuf: ParticleLike[];
+    /**
+     * Allocate both pre-allocated buffers.
+     * Call once from each concrete renderer's constructor, passing maxCount.
+     */
+    protected _allocDrawBuf(max: number): void;
+    /**
+     * Expand the particle pool with children and write the result into _drawBuf.
+     * Returns the number of entries written (≤ maxCount).
+     *
+     * When childCount === 0 or childType === 0 this copies only alive parents —
+     * the caller's draw loop then iterates _drawBuf[0..n] instead of pool,
+     * skipping dead slots for free.
+     *
+     * childType:  0 = none (parents only)
+     *             1 = simple   (random sphere scatter)
+     *             2 = interpolated (between consecutive parents)
+     */
+    protected expandWithChildren(pool: ParticleLike[], _aliveCount: number, childCount: number, childType: number, childSpread: number, rng: SeededRandom | null, maxCount: number): number;
+    private _copyToEntry;
+}
+export {};
+//# sourceMappingURL=BaseRenderer.d.ts.map

package/dist/core/BaseRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseRenderer.d.ts","sourceRoot":"","sources":["../../src/core/BaseRenderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AACrC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAErD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/C,QAAQ,EAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/C,QAAQ,EAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/C,IAAI,EAAQ,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAO,OAAO,CAAA;IACnB,QAAQ,EAAI,MAAM,CAAA;IAClB,GAAG,EAAS,MAAM,CAAA;IAClB,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,4EAA4E;AAC5E,UAAU,SAAU,SAAQ,YAAY;IACtC,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;GAMG;AACH,8BAAsB,YAAY;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAEpC;;;;;OAKG;IACH,IAAI,OAAO,IAAI,OAAO,CAAiC;IACvD,IAAI,OAAO,CAAC,CAAC,EAAE,OAAO,EAA+B;IAErD;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CACb,SAAS,EAAE,YAAY,EAAE,EACzB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,QAAQ,CAAC,EAAE,YAAY,GACtB,IAAI;IAEP,yBAAyB;IACzB,QAAQ,CAAC,OAAO,IAAI,IAAI;IAIxB;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAK;IAEpC;;;OAGG;IACH,SAAS,CAAC,SAAS,EAAE,YAAY,EAAE,CAAK;IAExC;;;OAGG;IACH,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAiB1C;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,kBAAkB,CAC1B,IAAI,EAAS,YAAY,EAAE,EAC3B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAG,MAAM,EACnB,SAAS,EAAI,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAU,YAAY,GAAG,IAAI,EAChC,QAAQ,EAAK,MAAM,GAClB,MAAM;IAkHT,OAAO,CAAC,YAAY;CAkBrB"}

package/dist/core/BaseRenderer.js

@@ -0,0 +1,190 @@
+/**
+ * Abstract base for all particle renderers.
+ * A renderer owns a Three.js Object3D and updates it each tick
+ * from the live particle array.
+ *
+ * Concrete subclasses: BillboardRenderer, InstanceRenderer, LineRenderer.
+ */
+export class BaseRenderer {
+    constructor() {
+        // ── Children expansion infrastructure ────────────────────────────────────
+        /**
+         * Pre-allocated draw buffer — filled each frame by expandWithChildren().
+         * Concrete constructors must call _allocDrawBuf(maxCount) to initialise it.
+         */
+        this._drawBuf = [];
+        /**
+         * Pre-allocated alive-particle scratch list — filled inside expandWithChildren
+         * for the interpolated pass without heap allocations.
+         */
+        this._aliveBuf = [];
+    }
+    /**
+     * Show or hide the particle helper geometry.
+     * In Blender this is the viewport dot/sphere representation —
+     * hidden in final renders. Set false to see only the resulting
+     * mesh/material assigned to the particles, not the placeholders.
+     */
+    get visible() { return this.object3D.visible; }
+    set visible(v) { this.object3D.visible = v; }
+    /**
+     * Allocate both pre-allocated buffers.
+     * Call once from each concrete renderer's constructor, passing maxCount.
+     */
+    _allocDrawBuf(max) {
+        this._drawBuf = Array.from({ length: max }, () => ({
+            position: { x: 0, y: 0, z: 0 },
+            velocity: { x: 0, y: 0, z: 0 },
+            rotation: { x: 0, y: 0, z: 0 },
+            size: 1,
+            normalised: 0,
+            alive: true,
+            lifetime: 1,
+            age: 0,
+            emitterIndex: 0,
+            poolIdx: 0,
+        }));
+        // _aliveBuf only needs room for alive particles, worst case = max
+        this._aliveBuf = new Array(max);
+    }
+    /**
+     * Expand the particle pool with children and write the result into _drawBuf.
+     * Returns the number of entries written (≤ maxCount).
+     *
+     * When childCount === 0 or childType === 0 this copies only alive parents —
+     * the caller's draw loop then iterates _drawBuf[0..n] instead of pool,
+     * skipping dead slots for free.
+     *
+     * childType:  0 = none (parents only)
+     *             1 = simple   (random sphere scatter)
+     *             2 = interpolated (between consecutive parents)
+     */
+    expandWithChildren(pool, _aliveCount, childCount, childType, childSpread, rng, maxCount) {
+        const cc = Math.round(Math.max(0, childCount));
+        const ct = Math.round(childType);
+        // ── No children — copy alive parents only ─────────────────────────────
+        if (cc === 0 || ct === 0) {
+            let n = 0;
+            for (let pi = 0; pi < pool.length; pi++) {
+                const p = pool[pi];
+                if (!p.alive)
+                    continue;
+                if (n >= maxCount)
+                    break;
+                this._copyToEntry(this._drawBuf[n], p, pi);
+                n++;
+            }
+            return n;
+        }
+        // ── Build alive list (no allocations — writes into _aliveBuf) ─────────
+        let an = 0;
+        for (let pi = 0; pi < pool.length; pi++) {
+            const p = pool[pi];
+            if (p.alive) {
+                this._aliveBuf[an] = p;
+                // stash pool index in the drawbuf slot we'll use later; easiest to
+                // track it separately via a parallel index trick below
+                an++;
+            }
+        }
+        // Also need pool indices for each alive particle — re-scan is cheap
+        let n = 0;
+        if (ct === 1) {
+            // ── Simple children — random sphere around each parent ───────────────
+            // Re-scan pool to preserve pool indices without extra allocation
+            let ai = 0;
+            for (let pi = 0; pi < pool.length; pi++) {
+                const p = pool[pi];
+                if (!p.alive)
+                    continue;
+                if (n >= maxCount)
+                    break;
+                // Write parent
+                this._copyToEntry(this._drawBuf[n], p, pi);
+                n++;
+                ai++;
+                // Write children
+                for (let ci = 0; ci < cc; ci++) {
+                    if (n >= maxCount)
+                        break;
+                    const d = this._drawBuf[n];
+                    this._copyToEntry(d, p, pi);
+                    if (childSpread > 0 && rng !== null) {
+                        // Uniform sphere placement — 3 rng calls per child, no loops
+                        const theta = rng.next() * 6.283185307;
+                        const phi = Math.acos(1 - 2 * rng.next());
+                        const r = childSpread * Math.cbrt(rng.next());
+                        d.position.x = p.position.x + r * Math.sin(phi) * Math.cos(theta);
+                        d.position.y = p.position.y + r * Math.sin(phi) * Math.sin(theta);
+                        d.position.z = p.position.z + r * Math.cos(phi);
+                    }
+                    n++;
+                }
+            }
+        }
+        else {
+            // ── Interpolated children — lerp between consecutive alive parents ───
+            if (an === 0)
+                return 0;
+            let ai = 0;
+            for (let pi = 0; pi < pool.length; pi++) {
+                const p = pool[pi];
+                if (!p.alive)
+                    continue;
+                if (n >= maxCount)
+                    break;
+                // Write parent
+                this._copyToEntry(this._drawBuf[n], p, pi);
+                n++;
+                const nextAi = (ai + 1) % an;
+                const p1 = this._aliveBuf[nextAi];
+                // Write children interpolated between p and p1
+                for (let ci = 0; ci < cc; ci++) {
+                    if (n >= maxCount)
+                        break;
+                    const t = (ci + 1) / (cc + 1);
+                    const d = this._drawBuf[n];
+                    d.position.x = p.position.x + (p1.position.x - p.position.x) * t;
+                    d.position.y = p.position.y + (p1.position.y - p.position.y) * t;
+                    d.position.z = p.position.z + (p1.position.z - p.position.z) * t;
+                    d.velocity.x = p.velocity.x + (p1.velocity.x - p.velocity.x) * t;
+                    d.velocity.y = p.velocity.y + (p1.velocity.y - p.velocity.y) * t;
+                    d.velocity.z = p.velocity.z + (p1.velocity.z - p.velocity.z) * t;
+                    d.rotation.x = p.rotation.x;
+                    d.rotation.y = p.rotation.y;
+                    d.rotation.z = p.rotation.z;
+                    d.size = p.size + (p1.size - p.size) * t;
+                    d.normalised = p.normalised + (p1.normalised - p.normalised) * t;
+                    d.alive = true;
+                    d.lifetime = p.lifetime;
+                    d.age = p.age;
+                    d.emitterIndex = p.emitterIndex;
+                    d.poolIdx = pi;
+                    n++;
+                }
+                ai++;
+            }
+        }
+        return n;
+    }
+    // ── Private helpers ───────────────────────────────────────────────────────
+    _copyToEntry(d, p, poolIdx) {
+        d.position.x = p.position.x;
+        d.position.y = p.position.y;
+        d.position.z = p.position.z;
+        d.velocity.x = p.velocity.x;
+        d.velocity.y = p.velocity.y;
+        d.velocity.z = p.velocity.z;
+        d.rotation.x = p.rotation.x;
+        d.rotation.y = p.rotation.y;
+        d.rotation.z = p.rotation.z;
+        d.size = p.size;
+        d.normalised = p.normalised;
+        d.alive = true;
+        d.lifetime = p.lifetime;
+        d.age = p.age;
+        d.emitterIndex = p.emitterIndex;
+        d.poolIdx = poolIdx;
+    }
+}
+//# sourceMappingURL=BaseRenderer.js.map

package/dist/core/BaseRenderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseRenderer.js","sourceRoot":"","sources":["../../src/core/BaseRenderer.ts"],"names":[],"mappings":"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"}

package/dist/core/DeflectorCollider.d.ts

@@ -0,0 +1,46 @@
+import { BufferGeometry, Vector3 } from 'three';
+export interface DeflectorColliderOptions {
+    friction?: number;
+    damping?: number;
+    stiffness?: number;
+}
+/**
+ * DeflectorCollider — mesh surface that bounces or kills particles on contact.
+ * (Blender: Physics → Collision panel)
+ *
+ * buildBVH() precomputes a flat triangle list (vertex A + face normal per tri).
+ * Called automatically on first use.
+ */
+export declare class DeflectorCollider {
+    /** All scalar inputs — GSAP / keyframe compatible (Blender-matched names) */
+    parameters: {
+        friction: number;
+        damping: number;
+        stiffness: number;
+    };
+    private _triangles;
+    private _triCount;
+    private _geometry;
+    private _built;
+    constructor(geometry: BufferGeometry, opts?: DeflectorColliderOptions);
+    /** Precompute triangle planes from geometry. Called automatically on first use. */
+    buildBVH(): void;
+    /**
+     * Find the closest triangle plane to (px, py, pz).
+     * Returns true if any triangle is within parameters.stiffness × 0.5 world units.
+     */
+    closestPoint(px: number, py: number, pz: number, out: {
+        point: Vector3;
+        normal: Vector3;
+        dist: number;
+    }): boolean;
+    /**
+     * Test whether the particle segment (prev → curr) crosses any triangle plane.
+     * radius (default 0) offsets the plane by the particle's collision radius so
+     * particles bounce before touching the surface (Blender: Size Deflect).
+     * Writes face normal and contact point to outNormal/outPoint on hit.
+     * Returns true if a crossing was detected.
+     */
+    checkCrossing(prevX: number, prevY: number, prevZ: number, currX: number, currY: number, currZ: number, outNormal: Vector3, outPoint: Vector3, radius?: number): boolean;
+}
+//# sourceMappingURL=DeflectorCollider.d.ts.map

package/dist/core/DeflectorCollider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeflectorCollider.d.ts","sourceRoot":"","sources":["../../src/core/DeflectorCollider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAE/C,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAG,MAAM,CAAA;IAClB,OAAO,CAAC,EAAI,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAC5B,6EAA6E;IAC7E,UAAU,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAEpE,OAAO,CAAC,UAAU,CAAoC;IACtD,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,MAAM,CAAQ;gBAEV,QAAQ,EAAE,cAAc,EAAE,IAAI,GAAE,wBAA6B;IASzE,mFAAmF;IACnF,QAAQ,IAAI,IAAI;IA8ChB;;;OAGG;IACH,YAAY,CACV,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAClC,GAAG,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GACrD,OAAO;IA2BV;;;;;;OAMG;IACH,aAAa,CACX,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAC3C,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAC3C,SAAS,EAAE,OAAO,EAClB,QAAQ,EAAG,OAAO,EAClB,MAAM,SAAI,GACT,OAAO;CAyBX"}

package/dist/core/DeflectorCollider.js

@@ -0,0 +1,113 @@
+import { Vector3 } from 'three';
+/**
+ * DeflectorCollider — mesh surface that bounces or kills particles on contact.
+ * (Blender: Physics → Collision panel)
+ *
+ * buildBVH() precomputes a flat triangle list (vertex A + face normal per tri).
+ * Called automatically on first use.
+ */
+export class DeflectorCollider {
+    constructor(geometry, opts = {}) {
+        this._triangles = new Float32Array(0); // [ax,ay,az,nx,ny,nz] per tri
+        this._triCount = 0;
+        this._built = false;
+        this._geometry = geometry;
+        this.parameters = {
+            friction: opts.friction ?? 0,
+            damping: opts.damping ?? 0.5,
+            stiffness: opts.stiffness ?? 1,
+        };
+    }
+    /** Precompute triangle planes from geometry. Called automatically on first use. */
+    buildBVH() {
+        const geo = this._geometry;
+        const pos = geo.getAttribute('position');
+        const idx = geo.getIndex();
+        if (!pos)
+            return;
+        let triCount;
+        let getVerts;
+        if (idx) {
+            triCount = Math.floor(idx.count / 3);
+            getVerts = (i) => [idx.getX(i * 3), idx.getX(i * 3 + 1), idx.getX(i * 3 + 2)];
+        }
+        else {
+            triCount = Math.floor(pos.count / 3);
+            getVerts = (i) => [i * 3, i * 3 + 1, i * 3 + 2];
+        }
+        // 6 floats per triangle: vertex A (x,y,z) + face normal (x,y,z)
+        this._triangles = new Float32Array(triCount * 6);
+        this._triCount = triCount;
+        const vA = new Vector3(), vB = new Vector3(), vC = new Vector3();
+        const e1 = new Vector3(), e2 = new Vector3();
+        for (let i = 0; i < triCount; i++) {
+            const [a, b, c] = getVerts(i);
+            vA.fromBufferAttribute(pos, a);
+            vB.fromBufferAttribute(pos, b);
+            vC.fromBufferAttribute(pos, c);
+            e1.subVectors(vB, vA);
+            e2.subVectors(vC, vA);
+            const n = new Vector3().crossVectors(e1, e2).normalize();
+            const o = i * 6;
+            this._triangles[o] = vA.x;
+            this._triangles[o + 1] = vA.y;
+            this._triangles[o + 2] = vA.z;
+            this._triangles[o + 3] = n.x;
+            this._triangles[o + 4] = n.y;
+            this._triangles[o + 5] = n.z;
+        }
+        this._built = true;
+    }
+    /**
+     * Find the closest triangle plane to (px, py, pz).
+     * Returns true if any triangle is within parameters.stiffness × 0.5 world units.
+     */
+    closestPoint(px, py, pz, out) {
+        if (!this._built)
+            this.buildBVH();
+        const threshold = this.parameters.stiffness * 0.5;
+        let minDist = Infinity;
+        let found = false;
+        for (let i = 0; i < this._triCount; i++) {
+            const o = i * 6;
+            const ax = this._triangles[o], ay = this._triangles[o + 1], az = this._triangles[o + 2];
+            const nx = this._triangles[o + 3], ny = this._triangles[o + 4], nz = this._triangles[o + 5];
+            const d = (px - ax) * nx + (py - ay) * ny + (pz - az) * nz;
+            const dist = Math.abs(d);
+            if (dist < threshold && dist < minDist) {
+                minDist = dist;
+                out.point.set(px - d * nx, py - d * ny, pz - d * nz);
+                out.normal.set(nx, ny, nz);
+                out.dist = dist;
+                found = true;
+            }
+        }
+        return found;
+    }
+    /**
+     * Test whether the particle segment (prev → curr) crosses any triangle plane.
+     * radius (default 0) offsets the plane by the particle's collision radius so
+     * particles bounce before touching the surface (Blender: Size Deflect).
+     * Writes face normal and contact point to outNormal/outPoint on hit.
+     * Returns true if a crossing was detected.
+     */
+    checkCrossing(prevX, prevY, prevZ, currX, currY, currZ, outNormal, outPoint, radius = 0) {
+        if (!this._built)
+            this.buildBVH();
+        for (let i = 0; i < this._triCount; i++) {
+            const o = i * 6;
+            const ax = this._triangles[o], ay = this._triangles[o + 1], az = this._triangles[o + 2];
+            const nx = this._triangles[o + 3], ny = this._triangles[o + 4], nz = this._triangles[o + 5];
+            const dPrev = (prevX - ax) * nx + (prevY - ay) * ny + (prevZ - az) * nz;
+            const dCurr = (currX - ax) * nx + (currY - ay) * ny + (currZ - az) * nz;
+            if (dPrev >= radius && dCurr < radius) {
+                outNormal.set(nx, ny, nz);
+                // Project current position back to the offset contact plane
+                outPoint.set(currX - (dCurr - radius) * nx, currY - (dCurr - radius) * ny, currZ - (dCurr - radius) * nz);
+                return true;
+            }
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=DeflectorCollider.js.map

package/dist/core/DeflectorCollider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeflectorCollider.js","sourceRoot":"","sources":["../../src/core/DeflectorCollider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,OAAO,EAAE,MAAM,OAAO,CAAA;AAQ/C;;;;;;GAMG;AACH,MAAM,OAAO,iBAAiB;IAS5B,YAAY,QAAwB,EAAE,OAAiC,EAAE;QALjE,eAAU,GAAiB,IAAI,YAAY,CAAC,CAAC,CAAC,CAAA,CAAE,8BAA8B;QAC9E,cAAS,GAAG,CAAC,CAAA;QAEb,WAAM,GAAG,KAAK,CAAA;QAGpB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAA;QACzB,IAAI,CAAC,UAAU,GAAG;YAChB,QAAQ,EAAG,IAAI,CAAC,QAAQ,IAAK,CAAC;YAC9B,OAAO,EAAI,IAAI,CAAC,OAAO,IAAM,GAAG;YAChC,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,CAAC;SAC/B,CAAA;IACH,CAAC;IAED,mFAAmF;IACnF,QAAQ;QACN,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAA;QAC1B,MAAM,GAAG,GAAG,GAAG,CAAC,YAAY,CAAC,UAAU,CAAC,CAAA;QACxC,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAA;QAC1B,IAAI,CAAC,GAAG;YAAE,OAAM;QAEhB,IAAI,QAAgB,CAAA;QACpB,IAAI,QAAiD,CAAA;QAErD,IAAI,GAAG,EAAE,CAAC;YACR,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAA;YACpC,QAAQ,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;QAC/E,CAAC;aAAM,CAAC;YACN,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAA;YACpC,QAAQ,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAA;QACjD,CAAC;QAED,gEAAgE;QAChE,IAAI,CAAC,UAAU,GAAG,IAAI,YAAY,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAA;QAChD,IAAI,CAAC,SAAS,GAAI,QAAQ,CAAA;QAE1B,MAAM,EAAE,GAAG,IAAI,OAAO,EAAE,EAAE,EAAE,GAAG,IAAI,OAAO,EAAE,EAAE,EAAE,GAAG,IAAI,OAAO,EAAE,CAAA;QAChE,MAAM,EAAE,GAAI,IAAI,OAAO,EAAE,EAAE,EAAE,GAAI,IAAI,OAAO,EAAE,CAAA;QAE9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;YAClC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;YAC7B,EAAE,CAAC,mBAAmB,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;YAC9B,EAAE,CAAC,mBAAmB,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;YAC9B,EAAE,CAAC,mBAAmB,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;YAE9B,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;YACrB,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;YACrB,MAAM,CAAC,GAAG,IAAI,OAAO,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,SAAS,EAAE,CAAA;YAExD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YACf,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,GAAO,EAAE,CAAC,CAAC,CAAA;YAC7B,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;YAC7B,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;YAC7B,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;YAC5B,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;YAC5B,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;QAC9B,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;IACpB,CAAC;IAED;;;OAGG;IACH,YAAY,CACV,EAAU,EAAE,EAAU,EAAE,EAAU,EAClC,GAAsD;QAEtD,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,IAAI,CAAC,QAAQ,EAAE,CAAA;QAEjC,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,GAAG,GAAG,CAAA;QACjD,IAAI,OAAO,GAAG,QAAQ,CAAA;QACtB,IAAI,KAAK,GAAK,KAAK,CAAA;QAEnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,MAAM,CAAC,GAAI,CAAC,GAAG,CAAC,CAAA;YAChB,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;YAC3F,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;YAE3F,MAAM,CAAC,GAAM,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,CAAA;YAC7D,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;YAExB,IAAI,IAAI,GAAG,SAAS,IAAI,IAAI,GAAG,OAAO,EAAE,CAAC;gBACvC,OAAO,GAAG,IAAI,CAAA;gBACd,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,GAAG,EAAE,EAAE,EAAE,GAAG,CAAC,GAAG,EAAE,EAAE,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,CAAA;gBACpD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;gBAC1B,GAAG,CAAC,IAAI,GAAG,IAAI,CAAA;gBACf,KAAK,GAAG,IAAI,CAAA;YACd,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAA;IACd,CAAC;IAED;;;;;;OAMG;IACH,aAAa,CACX,KAAa,EAAE,KAAa,EAAE,KAAa,EAC3C,KAAa,EAAE,KAAa,EAAE,KAAa,EAC3C,SAAkB,EAClB,QAAkB,EAClB,MAAM,GAAG,CAAC;QAEV,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,IAAI,CAAC,QAAQ,EAAE,CAAA;QAEjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,MAAM,CAAC,GAAI,CAAC,GAAG,CAAC,CAAA;YAChB,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;YAC3F,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;YAE3F,MAAM,KAAK,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC,GAAG,EAAE,CAAA;YACvE,MAAM,KAAK,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC,GAAG,EAAE,CAAA;YAEvE,IAAI,KAAK,IAAI,MAAM,IAAI,KAAK,GAAG,MAAM,EAAE,CAAC;gBACtC,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;gBACzB,4DAA4D;gBAC5D,QAAQ,CAAC,GAAG,CACV,KAAK,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,EAAE,EAC7B,KAAK,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,EAAE,EAC7B,KAAK,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,EAAE,CAC9B,CAAA;gBACD,OAAO,IAAI,CAAA;YACb,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAA;IACd,CAAC;CACF"}