sparcoon 0.9.1 → 0.9.3

package/dist/emitter/FXEmitter.js

@@ -1,37 +1,28 @@
 import { Object3D, Quaternion, Vector3 } from "three";
 import { FXWorld } from "../world/FXWorld.js";
 import { FXObjectMotionTracker } from "./FXObjectMotion.Internal.js";
-import { FX_AGE, FX_CORE_LIFECYCLE, FX_CORE_LIFECYCLE_STRIDE, FX_CORE_POSITION, FX_CORE_POSITION_STRIDE, } from "../coreLayout.js";
-import { FXInstancedParticle } from "../instancedParticle/FXInstancedParticle.js";
 import { resolveGeometrySource } from "../instancedParticle/primitiveGeometry.js";
 import { assertValidNonNegativeNumber, assertValidPositiveInteger, assertValidPositiveNumber, } from "../miscellaneous/asserts.js";
 import { FXArtifactMaterial } from "../render/FXArtifactMaterial.js";
-import { FXSimulationHolder } from "./FXSimulationHolder.js";
+import { FXGPUEmitterDriver } from "./FXGPUEmitterDriver.Internal.js";
+import { FXJSEmitterDriver } from "./FXJSEmitterDriver.Internal.js";
 import { EMITTER_DEFAULT_CAPACITY_STEP, EMITTER_DEFAULT_CAST_SHADOW, EMITTER_DEFAULT_EXPECTED_CAPACITY, EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT, EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION, EMITTER_DEFAULT_RECEIVE_SHADOW, EMITTER_DEFAULT_SORT_FRACTION, } from "./FXEmitter.Internal.js";
-// User attribute `name` -> mesh property-buffer key `fx_<name>`.
-const ATTRIBUTE_BUFFER_PREFIX = "fx_";
-// GLSL type of a float attribute, indexed by component count.
-const GLSL_TYPE_BY_COMPONENTS = ["", "float", "vec2", "vec3", "vec4"];
-const CORE_POSITION_TYPE = {
-    glslTypeName: "vec3",
-    bufferSize: FX_CORE_POSITION_STRIDE,
-    instantiable: true,
-};
-const CORE_LIFECYCLE_TYPE = {
-    glslTypeName: "vec2",
-    bufferSize: FX_CORE_LIFECYCLE_STRIDE,
-    instantiable: true,
-};
 /**
  * Particle emitter - one instanced billboard/mesh draw call, per-particle state driven by a
  * precompiled behavior artifact and appearance by a precompiled render artifact spliced into a
  * Three material. Built and ticked by {@link FXEffect} through an {@link FXWorld}. Not exported from
  * the package (the runtime path is running artifacts, not hand-building emitters); reached only as
  * the live handle returned by {@link FXEffect.getEmitter}.
+ *
+ * A thin facade over one {@link FXEmitterDriver} (JS or GPU - see `FXEmitterDriver.Internal.ts`),
+ * chosen once by {@link fromArtifacts} and never switched mid-playback. This class itself owns only
+ * what is genuinely backend-independent: play/burst/stop/prewarm scheduling, sort-fraction timing,
+ * object motion tracking, and the render material - the material itself CAN be replaced in place,
+ * by {@link applyRenderArtifact}, without touching the driver or its particle state.
  */
 export class FXEmitter extends Object3D {
     /** @internal Use {@link FXEmitter.fromArtifacts}. */
-    constructor(material, simulation, options = {}, baseGeometry, world) {
+    constructor(driver, material, options, world) {
         super();
         this.nextHandler = 0;
         this.pendingBursts = [];
@@ -52,38 +43,22 @@ export class FXEmitter extends Object3D {
         this.motionScaleScratch = new Vector3();
         this.motionTracker = new FXObjectMotionTracker();
         this.destroyed = false;
-        this.kernelBuffersCacheVersion = -1;
         this.onRendering = (deltaTime) => {
             this.tick(deltaTime);
-            if (this.sortCamera !== undefined && this.mesh.instanceCount > 0) {
-                // `sortFraction` is public, so clamp here too: a direct assignment above 1 would grow the accumulator unbounded.
-                this.sortingAccumulator += Math.min(Math.max(this.sortFraction, 0), 1);
-                if (this.sortingAccumulator >= 1) {
-                    this.sortingAccumulator -= 1;
-                    // Sort in world space to match the shader's `p_cameraDistance`, correct under any transform.
-                    this.sortCamera.getWorldPosition(this.sortingCameraWorldPosition);
-                    this.mesh.updateWorldMatrix(true, false);
-                    this.mesh.sortByDistance(this.sortingCameraWorldPosition, this.mesh.matrixWorld);
-                }
+            if (this.sortCamera === undefined) {
+                return;
+            }
+            // `sortFraction` is public, so clamp here too: a direct assignment above 1 would grow the accumulator unbounded.
+            this.sortingAccumulator += Math.min(Math.max(this.sortFraction, 0), 1);
+            if (this.sortingAccumulator >= 1) {
+                this.sortingAccumulator -= 1;
+                this.sortCamera.getWorldPosition(this.sortingCameraWorldPosition);
+                this.driver.sortByDistance(this.sortingCameraWorldPosition);
             }
         };
         this.world = world;
-        if (options.expectedCapacity !== undefined) {
-            // Sizes the Float32Array buffers - a fractional length is a RangeError.
-            assertValidPositiveInteger(options.expectedCapacity, "FXEmitter.constructor.options.expectedCapacity");
-        }
-        if (options.capacityStep !== undefined) {
-            assertValidPositiveInteger(options.capacityStep, "FXEmitter.constructor.options.capacityStep");
-        }
-        this.material = material;
-        this.simulation = simulation;
-        // Property set = the two core buffers plus one `fx_<name>` per attribute, known before the mesh
-        // and Three material are built so `a_<name>`/`p_<name>` are declared up front. A cross-artifact
-        // width disagreement fails fast here.
-        const components = this.attributeComponents();
-        this.collectedProperties = this.buildCollectedProperties(components);
-        const threeMaterial = material.buildThreeMaterial(this.collectedProperties);
-        this.mesh = new FXInstancedParticle(this.collectedProperties, options.expectedCapacity ?? EMITTER_DEFAULT_EXPECTED_CAPACITY, options.capacityStep ?? EMITTER_DEFAULT_CAPACITY_STEP, threeMaterial, baseGeometry);
+        this.driver = driver;
+        this.artifactMaterial = material;
         if (options.receiveShadow ?? EMITTER_DEFAULT_RECEIVE_SHADOW) {
             this.mesh.receiveShadow = true;
         }
@@ -92,7 +67,7 @@ export class FXEmitter extends Object3D {
         // false on the mesh, so the shadow pass's frustum check is a no-op just like the color pass.
         if (options.castShadow ?? EMITTER_DEFAULT_CAST_SHADOW) {
             this.mesh.castShadow = true;
-            this.mesh.customDepthMaterial = material.buildThreeDepthMaterial(this.collectedProperties);
+            this.mesh.customDepthMaterial = material.buildThreeDepthMaterial(this.driver.varyings);
         }
         this.sortCamera = options.sortCamera;
         this.sortFraction = EMITTER_DEFAULT_SORT_FRACTION;
@@ -103,11 +78,20 @@ export class FXEmitter extends Object3D {
         this.add(this.mesh);
         this.world.registerObject(this);
     }
+    /** Exact live count for a JS-driven emitter; for a GPU-driven one, there is no CPU-visible live
+     *  count to report - `capacity` is the honest upper bound reported instead. */
     get particleCount() {
-        return this.mesh.instanceCount;
+        return this.driver.particleCount;
     }
+    /** The buffer's current allocated size - grows over time for a JS-driven emitter, fixed at
+     *  construction for a GPU-driven one (no capacityStep growth path there). */
     get particleCapacity() {
-        return this.mesh.instanceCapacity;
+        return this.driver.particleCapacity;
+    }
+    // The active driver's own mesh - a thin passthrough, not a second source of truth (this.driver.mesh
+    // is authoritative; nothing caches or duplicates it here).
+    get mesh() {
+        return this.driver.mesh;
     }
     /**
      * Builds an emitter into `world` from a precompiled effect - the low-level building block behind
@@ -116,10 +100,34 @@ export class FXEmitter extends Object3D {
      * runtime path is running whole projects through `FXEffect`.
      */
     static fromArtifacts(render, behavior, options = {}, world = FXWorld.getDefault()) {
+        if (options.expectedCapacity !== undefined) {
+            // Sizes the Float32Array buffers - a fractional length is a RangeError. Doubles as the
+            // fixed GPU capacity when a GPU kernel is present (no capacityStep growth for that path).
+            assertValidPositiveInteger(options.expectedCapacity, "FXEmitter.constructor.options.expectedCapacity");
+        }
+        if (options.capacityStep !== undefined) {
+            assertValidPositiveInteger(options.capacityStep, "FXEmitter.constructor.options.capacityStep");
+        }
         const material = new FXArtifactMaterial(render, options.textures);
-        const holder = new FXSimulationHolder(behavior);
         const baseGeometry = resolveGeometrySource(render.geometry, options.geometries ?? {});
-        return new FXEmitter(material, holder, options, baseGeometry, world);
+        const capacity = options.expectedCapacity ?? EMITTER_DEFAULT_EXPECTED_CAPACITY;
+        // The one place this emitter's backend is chosen, ever (never switched mid-playback). A real
+        // driver-level failure (program link, buffer/VAO setup) despite "Try GPU simulation" having
+        // compiled and the live render tier already being "standard" falls back to the mandatory JS
+        // artifact in place, no reload loop, matching the editor's sceneCoordinator.ts own forced-
+        // WebGL1-creation-failure fallback shape on the render side.
+        let driver;
+        if (options.gpuKernel !== undefined && options.renderer !== undefined) {
+            try {
+                driver = new FXGPUEmitterDriver(options.gpuKernel, options.renderer, material, capacity, baseGeometry);
+            }
+            catch (error) {
+                console.warn("FXEmitter: GPU (transform-feedback) behavior setup failed at runtime; falling back " +
+                    "to the JS behavior artifact for this emitter.", error);
+            }
+        }
+        driver ?? (driver = new FXJSEmitterDriver(behavior, material, capacity, options.capacityStep ?? EMITTER_DEFAULT_CAPACITY_STEP, baseGeometry));
+        return new FXEmitter(driver, material, options, world);
     }
     /**
      * @internal Ticks this emitter one frame. Driven by {@link FXWorld.update}, which advances the
@@ -127,12 +135,12 @@ export class FXEmitter extends Object3D {
      */
     onWorldTick(deltaTime, elapsedTime) {
         this.onRendering(deltaTime);
-        this.material.setElapsedTime(elapsedTime);
-        this.material.setDeltaTime(deltaTime);
+        this.artifactMaterial.setElapsedTime(elapsedTime);
+        this.artifactMaterial.setDeltaTime(deltaTime);
         // emitterTransform.velocity/angularVelocity are always length 3 (see its declaration) -
         // computed once per tick in onRendering -> tick.
-        this.material.setObjectVelocity(this.emitterTransform.velocity);
-        this.material.setObjectAngularVelocity(this.emitterTransform.angularVelocity);
+        this.artifactMaterial.setObjectVelocity(this.emitterTransform.velocity);
+        this.artifactMaterial.setObjectAngularVelocity(this.emitterTransform.angularVelocity);
     }
     /** Unregisters, removes from the scene, disposes mesh and material. Idempotent. */
     destroy() {
@@ -141,18 +149,20 @@ export class FXEmitter extends Object3D {
         }
         this.destroyed = true;
         this.world.unregisterObject(this);
-        // Drop scheduled work and the buffer cache so nothing references the mesh's buffers after teardown.
+        // Drop scheduled work so nothing references the driver's buffers after teardown.
         this.pendingBursts.length = 0;
         this.activePlays.length = 0;
-        this.kernelBuffersCache = undefined;
-        // The material owns no per-emitter GPU resources; the mesh teardown disposes the instanced
-        // geometry and the mounted material.
-        this.material.destroy();
-        this.mesh.destroy();
+        // The material owns no per-emitter GPU resources; the driver teardown disposes the instanced
+        // geometry and the mounted material (plus, for a GPU-driven emitter, the compiled program+VAO).
+        this.artifactMaterial.destroy();
+        this.driver.destroy();
         this.removeFromParent();
     }
     /**
-     * Spawns `count` particles immediately, or after `options.delay`.
+     * Spawns `count` particles immediately, or after `options.delay`. An immediate burst seeds its
+     * particles from this emitter's pose and parameter values at the moment of the call, on either
+     * backend - so moving the emitter between two bursts of one frame spawns them in two places.
+     * A delayed burst spawns from the pose and values of the tick it expires on.
      * @returns Handler for {@link stop} to cancel a pending delayed burst.
      */
     burst(count, options = {}) {
@@ -243,18 +253,38 @@ export class FXEmitter extends Object3D {
             remaining -= deltaTime;
         }
     }
-    /** Kills all live particles and cancels all active plays and pending bursts. */
+    /**
+     * Kills all live particles and cancels all active plays and pending bursts. For a GPU-driven
+     * emitter this is a known-narrower reset (see the mesh's own `drop()` doc comment): there is no
+     * CPU-visible per-particle state to instantly zero, so already-alive particles keep aging out
+     * naturally rather than vanishing on this call's own frame - only the spawn cursor and pending
+     * schedule reset immediately.
+     */
     reset() {
         if (this.destroyed) {
             return;
         }
         this.pendingBursts.length = 0;
         this.activePlays.length = 0;
-        this.mesh.drop();
+        this.driver.reset();
         // A restarted effect should not report a teleport spike from wherever the emitter was last
         // posed - drop the velocity/angular-velocity baseline along with the particles.
         this.motionTracker.reset();
     }
+    /**
+     * For a timeline that loops back to its start - {@link FXEffect}'s own, or a tool's that drives
+     * the emitter itself: cancels the active plays and pending bursts, as {@link stop} does, and
+     * forgets the motion baseline - the pose jumps from the lap's end to its start, which is no
+     * motion - but leaves live particles to finish their lives, so the loop runs on seamlessly.
+     * Unlike {@link reset}, which clears them.
+     */
+    loopTimeline() {
+        if (this.destroyed) {
+            return;
+        }
+        this.stop();
+        this.motionTracker.reset();
+    }
     /**
      * Scrubs live parameter values into uniform/binding slots by name, picked up next frame - the
      * runtime's value channel for a non-structural edit. Unknown name = safe no-op; never recompiles.
@@ -265,48 +295,45 @@ export class FXEmitter extends Object3D {
             return;
         }
         if (values.uniforms !== undefined) {
-            this.material.applyUniformValues(values.uniforms);
+            this.artifactMaterial.applyUniformValues(values.uniforms);
         }
         if (values.bindings !== undefined) {
-            this.simulation?.applyBindingValues(values.bindings);
+            this.driver.applyBindingValues(values.bindings);
         }
     }
     /**
-     * Merged attribute set (name -> component count): union of the behavior's writes and the render's
-     * reads. Throws on a cross-artifact width disagreement rather than sizing a buffer wrong.
+     * Swaps only this emitter's render half in place - a new shader, geometry primitive/mesh, or
+     * shadow flags - leaving the behavior driver, particle buffers, instance count, and playback
+     * schedule completely untouched (unlike a structural edit that reaches {@link fromArtifacts},
+     * this never resets a running effect). The editor calls this instead of rebuilding whenever a
+     * graph edit only changed the render half.
+     *
+     * @throws If the new render artifact's attribute reads disagree with this emitter's already-
+     * allocated buffers (a genuine layout change - see {@link FXEmitterDriver.applyRenderArtifact}).
+     * This emitter is left exactly as it was before the call in that case; the caller must fall back
+     * to a fresh {@link fromArtifacts} instead, since only a new driver can safely resize buffers.
      */
-    attributeComponents() {
-        const components = new Map();
-        const add = (name, count) => {
-            const existing = components.get(name);
-            if (existing !== undefined && existing !== count) {
-                throw new Error(`FXEmitter: attribute "${name}" is written and read with conflicting widths ` +
-                    `(${existing.toString()} vs ${count.toString()}); the behavior attributeWrites and ` +
-                    `the render attributeReads must agree`);
-            }
-            components.set(name, count);
-        };
-        for (const write of this.simulation?.attributeWrites ?? []) {
-            add(write.name, write.components);
+    applyRenderArtifact(render, options = {}) {
+        if (this.destroyed) {
+            return;
         }
-        for (const read of this.material.attributeReads) {
-            add(read.name, read.components);
+        const material = new FXArtifactMaterial(render, options.textures);
+        const baseGeometry = resolveGeometrySource(render.geometry, options.geometries ?? {});
+        // Throws (leaving this emitter untouched) before anything below mutates it - see this
+        // method's own @throws doc.
+        this.driver.applyRenderArtifact(material, baseGeometry);
+        this.artifactMaterial = material;
+        this.mesh.receiveShadow = options.receiveShadow ?? EMITTER_DEFAULT_RECEIVE_SHADOW;
+        const previousDepthMaterial = this.mesh.customDepthMaterial;
+        if (options.castShadow ?? EMITTER_DEFAULT_CAST_SHADOW) {
+            this.mesh.castShadow = true;
+            this.mesh.customDepthMaterial = material.buildThreeDepthMaterial(this.driver.varyings);
         }
-        return components;
-    }
-    buildCollectedProperties(components) {
-        const properties = {
-            [FX_CORE_POSITION]: CORE_POSITION_TYPE,
-            [FX_CORE_LIFECYCLE]: CORE_LIFECYCLE_TYPE,
-        };
-        for (const [name, count] of components) {
-            properties[`${ATTRIBUTE_BUFFER_PREFIX}${name}`] = {
-                glslTypeName: GLSL_TYPE_BY_COMPONENTS[count],
-                bufferSize: count,
-                instantiable: true,
-            };
+        else {
+            this.mesh.castShadow = false;
+            this.mesh.customDepthMaterial = undefined;
         }
-        return properties;
+        previousDepthMaterial?.dispose();
     }
     setSortFraction(value, context) {
         assertValidNonNegativeNumber(value, context);
@@ -316,31 +343,10 @@ export class FXEmitter extends Object3D {
     // Throws when the behavior artifact cannot seed births. Checked at the scheduling points, NOT in
     // the frame tick - a throw from the world tick would take the host's render loop down.
     assertCanSpawn(context) {
-        if (this.simulation !== undefined && !this.simulation.canSpawn) {
+        if (!this.driver.canSpawn) {
             throw new Error(`${context}: this behavior artifact cannot seed births (update-only)`);
         }
     }
-    // Maps each kernel state-buffer name to its backing Float32Array. Cached across ticks/bursts and
-    // rebuilt only when the mesh's buffer set changes (`bufferVersion` - capacity growth).
-    kernelBuffers() {
-        const version = this.mesh.bufferVersion;
-        if (this.kernelBuffersCache !== undefined && this.kernelBuffersCacheVersion === version) {
-            return this.kernelBuffersCache;
-        }
-        const buffers = {
-            [FX_CORE_POSITION]: this.mesh.propertyBuffers[FX_CORE_POSITION].array,
-            [FX_CORE_LIFECYCLE]: this.mesh.propertyBuffers[FX_CORE_LIFECYCLE].array,
-        };
-        for (const buffer of this.simulation?.attributeBuffers ?? []) {
-            const attribute = this.mesh.propertyBuffers[`${ATTRIBUTE_BUFFER_PREFIX}${buffer.name}`];
-            if (attribute !== undefined) {
-                buffers[buffer.name] = attribute.array;
-            }
-        }
-        this.kernelBuffersCache = buffers;
-        this.kernelBuffersCacheVersion = version;
-        return buffers;
-    }
     // The emitter's world matrix as the reused snapshot the kernel reads. It is the mesh's
     // `matrixWorld` (same matrix the shader and depth sort see), so a world-space graph stays
     // consistent under any transform. `Matrix4.elements` is already column-major.
@@ -353,16 +359,6 @@ export class FXEmitter extends Object3D {
         }
         return transform;
     }
-    markBuffersNeedUpdate(names) {
-        for (const name of names) {
-            const isCore = name === FX_CORE_POSITION || name === FX_CORE_LIFECYCLE;
-            const key = isCore ? name : `${ATTRIBUTE_BUFFER_PREFIX}${name}`;
-            const attribute = this.mesh.propertyBuffers[key];
-            if (attribute !== undefined) {
-                attribute.needsUpdate = true;
-            }
-        }
-    }
     tick(deltaTime) {
         // World-space velocity/angular velocity since the previous tick, computed once here and not
         // inside worldTransform() - the burst/play loops below and the update phase can each call
@@ -390,16 +386,13 @@ export class FXEmitter extends Object3D {
         this.emitterTransform.angularVelocity[0] = motion.angularVelocity[0];
         this.emitterTransform.angularVelocity[1] = motion.angularVelocity[1];
         this.emitterTransform.angularVelocity[2] = motion.angularVelocity[2];
-        // Age increment + cull. Age is owned by this fixed loop, not the graph - same for every effect.
-        {
-            const lifecycle = this.mesh.propertyBuffers[FX_CORE_LIFECYCLE];
-            const { array, itemSize } = lifecycle;
-            const instanceCount = this.mesh.instanceCount;
-            for (let i = 0; i < instanceCount; i++) {
-                array[i * itemSize + FX_AGE] += deltaTime;
-            }
+        // Paused (dt == 0): skip the simulation step entirely - no JS age/kernel update, no GPU
+        // transform-feedback dispatch, no schedule advance - the emitter keeps rendering whatever
+        // particle state the last active tick left behind.
+        if (deltaTime <= 0) {
+            return;
         }
-        this.mesh.removeDeadParticles();
+        this.driver.beginTick(deltaTime);
         for (let i = this.pendingBursts.length - 1; i >= 0; i--) {
             const pending = this.pendingBursts[i];
             pending.delay -= deltaTime;
@@ -438,27 +431,10 @@ export class FXEmitter extends Object3D {
                 this.activePlays.splice(i, 1);
             }
         }
-        if (this.mesh.instanceCount === 0) {
-            return;
-        }
-        if (this.simulation !== undefined) {
-            // Motion integration lives in the graph (an `integrate-motion` node writes
-            // `position += velocity * dt`), not in this host loop.
-            this.simulation.update(this.kernelBuffers(), this.mesh.instanceCount, deltaTime, this.worldTransform());
-            this.markBuffersNeedUpdate(this.simulation.updateWrittenBuffers);
-        }
-        // Age (written above) must reach the GPU this frame; the update phase's buffers were flagged already.
-        this.mesh.propertyBuffers[FX_CORE_LIFECYCLE].needsUpdate = true;
+        this.driver.endTick(deltaTime, this.worldTransform());
     }
     spawnBurst(count) {
-        const instanceBegin = this.mesh.instanceCount;
-        this.mesh.createInstances(count);
-        const instanceEnd = this.mesh.instanceCount;
-        // Re-checked (defensive): no spawn function would leave the freshly zeroed rows born dead.
-        if (this.simulation?.canSpawn === true) {
-            this.simulation.spawn(this.kernelBuffers(), instanceBegin, instanceEnd - instanceBegin, this.worldTransform());
-            this.markBuffersNeedUpdate(this.simulation.spawnWrittenBuffers);
-        }
+        this.driver.spawn(count, this.worldTransform());
     }
 }
 // Returned by post-destroy `burst`/`play` - never matches a scheduled handler.

package/dist/emitter/FXEmitterDriver.Internal.d.ts

@@ -0,0 +1,26 @@
+import type { GLTypeInfo } from "../instancedParticle/glTypeInfo.js";
+/** A named width declaration - shape shared by `FXAttributeDecl` (`components`) and a mapped
+ *  `FXBufferLayout` (`stride`), the two concrete lists {@link mergeAttributeWidths} merges. */
+interface FXNamedWidth {
+    readonly name: string;
+    readonly components: number;
+}
+/**
+ * Merges width-declaring attribute lists (a driver's own state buffers, the render artifact's
+ * `attributeReads`) into one name -> component-count map, throwing on a genuine cross-source
+ * disagreement rather than sizing a buffer wrong. Shared by both drivers' constructors so the
+ * validation itself never drifts between them, even though each driver's own input list does not.
+ */
+export declare function mergeAttributeWidths(...sources: readonly (readonly FXNamedWidth[])[]): ReadonlyMap<string, number>;
+/** Builds a driver's full varyings map (the two core buffers plus one `fx_<name>` per attribute)
+ *  from a merged width map - the input to both `FXArtifactMaterial.buildThreeMaterial` and either
+ *  mesh class's constructor. */
+export declare function varyingsFromComponents(components: ReadonlyMap<string, number>): Record<string, GLTypeInfo>;
+/**
+ * Whether two varyings maps declare the exact same names at the exact same width - the guard
+ * `applyRenderArtifact` needs before reusing already-allocated buffers in place: a new render
+ * artifact whose attribute reads disagree with what is already allocated (a new name, or an
+ * existing name at a different width) cannot be applied without a full rebuild.
+ */
+export declare function sameVaryings(current: Record<string, GLTypeInfo>, next: Record<string, GLTypeInfo>): boolean;
+export {};

package/dist/emitter/FXEmitterDriver.Internal.js

@@ -0,0 +1,70 @@
+import { FX_CORE_LIFECYCLE, FX_CORE_LIFECYCLE_STRIDE, FX_CORE_POSITION, FX_CORE_POSITION_STRIDE, meshPropertyKeyFor, } from "../coreLayout.js";
+const CORE_POSITION_TYPE = {
+    glslTypeName: "vec3",
+    bufferSize: FX_CORE_POSITION_STRIDE,
+    instantiable: true,
+};
+const CORE_LIFECYCLE_TYPE = {
+    glslTypeName: "vec3",
+    bufferSize: FX_CORE_LIFECYCLE_STRIDE,
+    instantiable: true,
+};
+// GLSL type of a float attribute, indexed by component count.
+const GLSL_TYPE_BY_COMPONENTS = ["", "float", "vec2", "vec3", "vec4"];
+/**
+ * Merges width-declaring attribute lists (a driver's own state buffers, the render artifact's
+ * `attributeReads`) into one name -> component-count map, throwing on a genuine cross-source
+ * disagreement rather than sizing a buffer wrong. Shared by both drivers' constructors so the
+ * validation itself never drifts between them, even though each driver's own input list does not.
+ */
+export function mergeAttributeWidths(...sources) {
+    const components = new Map();
+    for (const source of sources) {
+        for (const decl of source) {
+            const existing = components.get(decl.name);
+            if (existing !== undefined && existing !== decl.components) {
+                throw new Error(`FXEmitter: attribute "${decl.name}" is declared with conflicting widths ` +
+                    `(${existing.toString()} vs ${decl.components.toString()}) across its sources`);
+            }
+            components.set(decl.name, decl.components);
+        }
+    }
+    return components;
+}
+/** Builds a driver's full varyings map (the two core buffers plus one `fx_<name>` per attribute)
+ *  from a merged width map - the input to both `FXArtifactMaterial.buildThreeMaterial` and either
+ *  mesh class's constructor. */
+export function varyingsFromComponents(components) {
+    const varyings = {
+        [FX_CORE_POSITION]: CORE_POSITION_TYPE,
+        [FX_CORE_LIFECYCLE]: CORE_LIFECYCLE_TYPE,
+    };
+    for (const [name, count] of components) {
+        varyings[meshPropertyKeyFor(name)] = {
+            glslTypeName: GLSL_TYPE_BY_COMPONENTS[count],
+            bufferSize: count,
+            instantiable: true,
+        };
+    }
+    return varyings;
+}
+/**
+ * Whether two varyings maps declare the exact same names at the exact same width - the guard
+ * `applyRenderArtifact` needs before reusing already-allocated buffers in place: a new render
+ * artifact whose attribute reads disagree with what is already allocated (a new name, or an
+ * existing name at a different width) cannot be applied without a full rebuild.
+ */
+export function sameVaryings(current, next) {
+    const currentNames = Object.keys(current);
+    if (currentNames.length !== Object.keys(next).length) {
+        return false;
+    }
+    return currentNames.every((name) => {
+        if (!Object.prototype.hasOwnProperty.call(next, name)) {
+            return false;
+        }
+        const nextEntry = next[name];
+        return (nextEntry.glslTypeName === current[name].glslTypeName &&
+            nextEntry.bufferSize === current[name].bufferSize);
+    });
+}

package/dist/emitter/FXFromArtifactsOptions.d.ts

@@ -1,4 +1,5 @@
-import type { BufferGeometry, Texture } from "three";
+import type { BufferGeometry, Texture, WebGLRenderer } from "three";
+import type { FXParticleKernelArtifact } from "../artifact/FXArtifact.js";
 import type { FXEmitterOptions } from "./FXEmitter.Internal.js";
 /**
  * Options for {@link FXEmitter.fromArtifacts}: the emitter options plus external textures by slot -
@@ -10,4 +11,14 @@ import type { FXEmitterOptions } from "./FXEmitter.Internal.js";
 export interface FXFromArtifactsOptions extends Partial<FXEmitterOptions> {
     readonly textures?: Record<string, Texture>;
     readonly geometries?: Record<string, BufferGeometry>;
+    /**
+     * The standard-tier (WebGL2, transform-feedback) behavior artifact, present only when the
+     * graph's spawn node had "Try GPU simulation" on and the graph compiled to GLSL. `renderer` is
+     * required alongside it - without one, or if GPU program setup itself throws (a real
+     * driver-level failure), the emitter falls back to the mandatory JS `behavior` artifact in
+     * place, never a hard error. `expectedCapacity` becomes this emitter's fixed GPU particle
+     * capacity (no growth); `capacityStep` is meaningless for a GPU-driven emitter and is ignored.
+     */
+    readonly gpuKernel?: FXParticleKernelArtifact;
+    readonly renderer?: WebGLRenderer;
 }

package/dist/emitter/FXGPUEmitterDriver.Internal.d.ts

@@ -0,0 +1 @@
+export {};