sparcoon 0.9.1 → 0.9.3

package/README.md

@@ -1,133 +1,233 @@
-# Sparcoon
+# <img src="https://raw.githubusercontent.com/jango-git/sparcoon/experimental/assets/logo.svg" width="30" height="30" alt="" align="top" /> Sparcoon
 
-Three.js runtime for VFX authored in the Sparcoon Editor.
+A three.js runtime that plays visual effects authored in the
+[Sparcoon Editor](https://github.com/jango-git/sparcoon-editor). The editor compiles a node graph
+into a plain ES module of precompiled artifacts, and this package executes them: instanced particle
+rendering in one draw call plus a small timeline player. No graph, no compiler and no `eval` in your
+build.
 
-`sparcoon` plays back particle effects designed in the Sparcoon Editor: the
-editor compiles a node graph into a plain ES module of precompiled artifacts,
-and this thin runtime loads and runs it -- instanced-particle rendering in one
-draw call plus a small timeline player. No graph, compiler, or live protocol
-ships to your app.
+**[Open the editor](https://jango-git.github.io/sparcoon-editor/)** -
+[Editor source](https://github.com/jango-git/sparcoon-editor) -
+[npm](https://www.npmjs.com/package/sparcoon/v/0.9.3)
 
-> Editor: link coming soon.
+> **Pre-release.** The artifact format is not frozen yet - breaking changes are possible before the
+> first stable release. The package is published under the `experimental` tag: npm's `latest` holds
+> an older release that the current editor does not work with.
 
-## Features
+## Who this is for
 
-- Instanced billboard and 3D-mesh particles in a single draw call.
-- Per-particle simulation from a precompiled kernel -- no `eval`, no codegen.
-- Whole-project playback: an editor module subclasses `FXEffect`.
-- One `FXWorld.update` per frame drives every effect.
-- Optional depth sorting, shadows, and custom-geometry particles.
-- Tree-shakeable ESM with full TypeScript types.
+Someone sent you a `.ts` file exported from the editor and you need to play it in your three.js
+scene. This package is everything you have to add for that.
+
+What is worth knowing before you install:
+
+- **No code generation.** The exported module is ready GLSL plus ordinary JavaScript functions that
+  your bundler compiles like any other source. Neither `eval` nor `new Function` is called anywhere,
+  so the effect passes where runtime code generation is forbidden by policy.
+- **No dependencies.** The only peer dependency is `three`.
+- **One draw call per emitter.** Billboards and mesh particles are drawn instanced.
+- **Two GLSL tiers in every artifact.** Standard (WebGL2) and Baseline (WebGL1-compatible); the
+  runtime picks by the capabilities of the renderer you pass in.
+- **Optional GPU simulation** through transform feedback, with an automatic fallback to the
+  JavaScript kernel.
+- **Tree-shakeable ESM with full types**, unbundled and unminified: your bundler processes the
+  package like any other source, exactly the way three.js is consumed.
 
 ## Install
 
 ```sh
-npm install sparcoon three
+npm install sparcoon@experimental three
 ```
 
-`three` (>= 0.157) is a peer dependency.
+`three` is a peer dependency; the supported range is `>=0.157 <0.180`.
 
 ## Quick start
 
-An editor project exports an `FXEffect` subclass plus a typed map of the
-textures it needs. Construct it (it joins the default world automatically), add
-it to your scene, and call `FXWorld.update(deltaTime)` once per frame.
+A module from the editor exports a named `FXEffect` subclass and a typed interface for its assets.
+The runtime does not load assets: you prepare the textures and geometries and pass them to the
+constructor.
 
 ```ts
 import { TextureLoader } from "three";
 import { FXWorld } from "sparcoon";
-import { VFXDemo0 } from "./effects/VFXDemo_0"; // emitted by the editor
+import { MyEffect, type MyEffectAssets } from "./effects/MyEffect"; // emitted by the editor
 
 const loader = new TextureLoader();
-const assets = {
-  heart: loader.load("heart.png"),
-  fire: loader.load("fire.png"),
+const assets: MyEffectAssets = {
+  spark: loader.load("spark.png"),
 };
-const effect = new VFXDemo0(assets);
+
+// renderer picks the artifact tier (WebGL2 -> Standard) and enables GPU simulation.
+// camera is needed by emitters that were given a sort interval in the editor.
+const effect = new MyEffect(assets, { renderer, camera });
 
 scene.add(effect); // FXEffect is a THREE.Group
 effect.play();
 
-function frame(deltaTime: number): void {
-  FXWorld.update(deltaTime); // advances every effect's timeline and its particles
+function frame(deltaSeconds: number): void {
+  FXWorld.update(deltaSeconds); // advances the timeline and particles of every effect
   renderer.render(scene, camera);
 }
 ```
 
-The effect is an `Object3D` -- position, rotate, and scale it like any other.
-Call `effect.dispose()` to remove it, free its GPU resources, and unsubscribe it
-from the world.
+Straight after the constructor the effect sits on frame zero, in the state the artist authored.
+`play()` restarts the timeline from the top; `stop()` halts playback, clears live particles and
+returns the effect to frame zero. The timeline loops, and seamlessly: particles still alive at the
+end of a lap finish their lives in the next one.
+
+Without `renderer` the effect takes the Baseline tier unconditionally and runs on the JavaScript
+kernel. That is a working mode if you have no renderer at the point of construction.
 
-### Live parameters
+`effect.dispose()` unsubscribes the effect from its world, destroys its emitters and frees mesh
+resources. The textures and geometries you passed in are left alone: you own their lifecycle.
 
-Channels the editor marked "live" are driven from your code, not the timeline:
+## Where the module comes from
+
+Effects are built in the [Sparcoon Editor](https://jango-git.github.io/sparcoon-editor/): a
+browser-based node editor with a timeline and a three.js viewport. Each emitter there owns two
+graphs - behavior (per-particle simulation) and render (its material) - and exporting a project puts
+everything into one self-contained TypeScript module. You drop it into your source tree and import
+it, as in the example above.
+
+Transform channels and timeline values can be marked by the artist as excluded from the export: the
+timeline does not drive those, your code supplies the values.
+
+## Driving it from code
 
 ```ts
-effect.setEmitterParam("Hearts", "spawnRate", 64);
-effect.setMeshParam("Mesh", "glow", [1, 0.4, 0.1]);
+effect.setEmitterParam("Sparks", "intensity", 0.7);
+effect.setMeshParam("Shockwave", "glow", [1, 0.4, 0.1]);
 
-effect.getEmitter("Hearts"); // the underlying emitter (Object3D)
-effect.getMesh("Mesh"); // the underlying THREE.Mesh
+effect.getEmitter("Sparks")?.position.set(0, 1, 0);
+effect.getMesh("Shockwave")?.rotateY(Math.PI);
 ```
 
-### Many effects, and separate worlds
+In the module the editor emitted, both setters and both getters are typed against the names the
+project actually declares, so a typo is caught at compile time. An unknown parameter name is always a
+safe no-op: a name drift never corrupts the runtime's data.
 
-Every effect joins the default world on construction, so any number of them are
-driven by the same single `FXWorld.update(deltaTime)` -- there is nothing extra
-to wire up per effect.
+`getEmitter` returns a live `FXEmitter` (an `Object3D`), which gives you direct control over emission
+outside the timeline:
 
-A world is a tick and clock domain (not a scene graph). Create your own
-`FXWorld` when you want an independent clock -- an isolated time scale, or a
-group you pause on its own -- and pass it to the effect:
+```ts
+const sparks = effect.getEmitter("Sparks");
+if (sparks) {
+  sparks.burst(64); // one-off release, optionally delayed; returns a handle for stop()
+  sparks.play(120); // continuous emission in particles per second; also returns a handle
+  sparks.stop(); // with no argument, cancels everything scheduled on this emitter
+  sparks.prewarm(2); // simulate 2 seconds forward so playback does not start from an empty screen
+
+  sparks.sortCamera = camera; // depth sorting; undefined turns it off
+  sparks.sortFraction = 0.1; // fraction of frames that re-sort (the default)
+}
+```
+
+An immediate `burst()` spawns from the emitter's pose and parameter values at the moment of the
+call, on the GPU path too - so moving the emitter between two bursts of one frame spawns them in two
+places.
+
+For diagnostics there are `particleCount` and `particleCapacity`. A GPU-driven emitter has no exact
+live count, so `particleCount` reports an honest upper bound - the buffer's current capacity.
+
+## Multiple effects and worlds
+
+A world is a tick and clock domain, not a scene graph. Every effect subscribes to a world on
+construction, so a single `FXWorld.update(deltaSeconds)` per frame drives them all.
 
 ```ts
 import { FXWorld } from "sparcoon";
 
 const slowmo = new FXWorld();
-const boss = new VFXDemo0(assets, { world: slowmo });
-scene.add(boss); // still added to your scene yourself
+const boss = new MyEffect(assets, { renderer, world: slowmo });
+scene.add(boss); // you still add the object to your scene yourself
 
-function frame(deltaTime: number): void {
-  FXWorld.update(deltaTime); // the default world
-  slowmo.update(deltaTime * 0.3); // its own, slower clock
+function frame(deltaSeconds: number): void {
+  FXWorld.update(deltaSeconds); // the default world
+  slowmo.update(deltaSeconds * 0.3); // its own, slower clock
   renderer.render(scene, camera);
 }
 ```
 
-Within one world every effect shares the clock and one delta per frame, so
-`effect.stop()` clears rather than freezes -- to freeze one effect on its own,
-give it its own world. `world.dispose()` disposes every effect in it.
+Within one world every effect shares the clock and one delta per frame, so `effect.stop()` clears the
+effect rather than freezing it. To freeze one effect on its own, give it its own world.
+`world.dispose()` disposes every effect in that world.
 
 ## How it works
 
-The **Sparcoon Editor** compiles a node graph into a plain ES module exporting
-a render artifact (GLSL, uniforms, textures) and a behavior artifact (authored
-spawn/update functions). This runtime executes them -- your bundler compiles
-the authored functions like any other source, so nothing is evaluated at
-runtime. The editor/runtime boundary is a frozen ABI: two core per-particle
-buffers, `position` and `lifecycle` (`[age, lifetime]`).
+The editor compiles a graph into artifacts and bakes them into a module together with the project's
+timeline:
+
+- **Render artifact** - GLSL, uniforms, texture references.
+- **Behavior artifact** - the authored spawn/update functions, bindings and buffer layout.
+- **GPU kernel** - a fused transform-feedback program, present only when the graph opted into GPU
+  simulation and compiled.
+
+The runtime executes those artifacts and compiles nothing. The editor/runtime boundary is frozen:
+each particle carries two core buffers, `position` (vec3) and `lifecycle` (vec3 `[age, lifetime,
+id]`), a particle counts as dead once `age >= lifetime`, and everything else lives in ordinary
+`a_fx_<name>` attributes. The package exports the constants of that layout (`FX_AGE`, `FX_LIFETIME`,
+`FX_ID`, `FX_CORE_POSITION` and the rest).
+
+The math the generated code calls comes from here too (`fxMix`, `fxSmoothstep`, `fxNoise1` /
+`fxNoise2` / `fxNoise3`, `fxFbm`, `fxFbm3`, `fxFract`, `fxMod`, `fxSampleLut`), along with
+`fxDataTexture` for baked curves and gradients. There is no reason to import them by hand: the effect
+module does it itself.
+
+## Development-build checks
+
+Arguments to public methods are sanity-checked (finite numbers, positive durations, integer
+capacities) and throw with the parameter's name when violated. The checks live behind
+`process.env.NODE_ENV !== "production"`, so they drop out of a production build entirely. The access
+to `process` is guarded by a `typeof` check, which keeps the package safe without a bundler - under
+import maps or from a CDN.
 
 ## Requirements
 
-- **A bundler** (Vite, webpack, Rollup, esbuild). `sparcoon` ships as
-  unbundled, unminified ES2020 modules plus types; your bundler tree-shakes and
-  minifies them, the same way three.js is consumed. Not a drop-in `<script>`.
-- **`three` >= 0.157**, as a peer dependency.
-- **Old devices.** Output targets ES2020; to run on pre-2015 hardware (for
-  example a first-generation iPad Pro), downlevel it in your own build
-  (Babel / SWC / your bundler's `target`). `sparcoon` leaves that final step
-  to you.
-
-## API overview
-
-- `FXEffect` -- whole-project timeline player (a `Group`); emitted modules
-  subclass it. `play` / `stop`, `setEmitterParam` / `setMeshParam`,
-  `getEmitter` / `getMesh`, `dispose`.
-- `FXWorld` -- the tick domain. `FXWorld.update(deltaTime)` per frame drives the
-  default world; `new FXWorld()` is an isolated clock and pool.
-- Artifact contract types, the `FX_*` core-layout constants, CPU math helpers
-  (`fxMix`, `fxSnoise3`, ...), and `fxDataTexture`.
+|          |                                                                                    |
+| -------- | ---------------------------------------------------------------------------------- |
+| three.js | `>=0.157 <0.180`, a peer dependency                                                |
+| Bundler  | Vite, webpack, Rollup, esbuild - the package ships unminified ESM plus types       |
+| JS level | ES2020; for devices older than 2015, transpile it on your side                     |
+| WebGL    | WebGL1 is enough for the Baseline tier; WebGL2 unlocks Standard and the GPU kernel |
+
+Dropping the package in through a `<script>` tag is not supported: these are unminified ES modules
+that expect your bundler. The ES2020 target is deliberate, so that you can downlevel it with your own
+Babel or SWC as far as you need, down to first-generation iPad Pro hardware.
+
+## What the runtime does not do
+
+- **It does not load assets.** You prepare the textures and geometries and pass them to the effect's
+  constructor. Freeing them is yours as well: the runtime never disposes resources it does not own.
+- **It contains no compiler, graph or validator.** All of that stays in the
+  [editor](https://github.com/jango-git/sparcoon-editor); only the result arrives here.
+- **It brings no lighting.** A lit graph reads the lights of your scene, so a lit effect needs a
+  light probe and a directional light nearby. The preview's own lighting rig is not exported.
+- **It does not decide your scene's draw order.** Depth sorting of particles is enabled per emitter
+  and costs frame time.
+
+## The `sparcoon/editor` entry point
+
+A separate, unstable entry for tools that build objects from artifacts directly:
+`FXEmitter.fromArtifacts` and `FXMesh.fromArtifact`, targeted value updates, swapping the render half
+without resetting the simulation, and the keyframe-sampling functions shared with the editor. The
+editor's live preview uses it. An application that simply plays a finished effect has no reason to go
+there: the whole path it needs runs through `FXEffect`.
+
+## Local development
+
+```sh
+npm ci
+npm run build   # tsc -> dist/, unminified ESM plus .d.ts
+npm test        # vitest run
+npm run lint
+```
+
+## Status
+
+Pre-release, under active development. If you hit a bug, the most useful thing is a minimal
+reproduction plus the editor project `.json` it shows up on.
 
 ## License
 
-MIT (c) jango
+MIT - use it in commercial work, client projects and ads that ship; keep the copyright notice. See
+[LICENSE](LICENSE).

package/dist/artifact/FXArtifact.d.ts

@@ -3,9 +3,11 @@ import type { FXGraphLambertMaterialOptions, FXGraphUnlitMaterialOptions } from
 /**
  * Frozen editor<->runtime boundary. The editor compiles a graph into a plain ESM module that
  * exports an {@link FXRenderArtifact} (GLSL + uniforms + textures) and an {@link FXBehaviorArtifact}
- * (authored spawn/update functions + bindings + buffer layout); the runtime only executes them.
- * Runtime-owned and exported; no code generation, no eval (the app's bundler compiles the authored
- * functions). Every value scrub must no-op on an unknown name so a name drift never corrupts values.
+ * (authored spawn/update functions + bindings + buffer layout), plus an optional
+ * {@link FXParticleKernelArtifact} (a fused GPU transform-feedback program) when the graph opts into
+ * GPU simulation; the runtime only executes them. Runtime-owned and exported; no code generation, no
+ * eval (the app's bundler compiles the authored JS functions, the editor precompiles the GLSL).
+ * Every value scrub must no-op on an unknown name so a name drift never corrupts values.
  */
 /** One state buffer: name + per-particle stride in floats. */
 export interface FXBufferLayout {
@@ -98,6 +100,23 @@ export interface FXRenderArtifact {
     /** Attributes the shader reads (`p_fx_<name>`); the emitter merges these with the sim's write set. */
     readonly attributeReads: readonly FXAttributeDecl[];
 }
+/**
+ * Which GLSL-family compiler tier produced a compiled {@link FXRenderArtifact}: `"baseline"` is
+ * the WebGL1/GLSL-ES-1.00-style compiler; `"standard"` is the WebGL2/GLSL-ES-3.00-only compiler
+ * (may use int/ivec and other standard-only capabilities a `"baseline"` graph cannot). Both
+ * compile to the same GLSL-text artifact shape and splice through the same material builders
+ * unchanged - Three already upgrades any material to `#version 300 es` (with full
+ * `attribute`/`varying`/`gl_FragColor` backward-compat macros) on an actual WebGL2 context,
+ * regardless of tier, so the runtime needs no declaration-style distinction between the two.
+ *
+ * Deliberately scoped to the GLSL family in its name: a structurally different family (the future
+ * advanced tier - a WGSL/WebGPU compiler, whose artifact has no vertex/fragment GLSL text at all)
+ * would need its own sibling type and its own field on the emitter/mesh spec, never a third member
+ * of this union or a third key in {@link FXRenderArtifactsByGLSLTier}.
+ */
+export type FXGLSLRenderTier = "baseline" | "standard";
+/** One emitter/mesh's render artifact, precompiled once per GLSL tier the editor supports. */
+export type FXRenderArtifactsByGLSLTier = Readonly<Record<FXGLSLRenderTier, FXRenderArtifact>>;
 /**
  * Behavior half of an emitted effect: authored spawn/update functions mutating the packed state
  * buffers, plus buffer layout and live bindings. Math helpers are inlined, so the artifact carries
@@ -118,3 +137,32 @@ export interface FXBehaviorArtifact {
     /** Advances all live particles `[0, count)`. */
     update(buffers: FXKernelBuffers, count: number, deltaTime: number, bindings: Record<string, FXValueSlot<number | Float32Array>>, emitter?: FXEmitterTransform): void;
 }
+/**
+ * Standard-tier (WebGL2, transform-feedback) behavior half of an emitted effect - a sibling of
+ * {@link FXBehaviorArtifact}, not a variant of it: a compiled GLSL program has no JS function
+ * shape to reuse. One fused GLSL ES 3.00 vertex-shader program handles both spawn and update in a
+ * single draw, branching per-invocation on the runtime-supplied spawn range (see
+ * `behaviorTransformFeedbackLayout.ts`'s uniform-name contract) - never two separate programs,
+ * since transform feedback cannot read and write the same buffer in one pass, and splitting the
+ * update range around a wrapping spawn cursor compounds badly with GPU-side buffer offsets.
+ *
+ * Optional per emitter/mesh spec: present only when the graph's spawn node had "Try GPU
+ * simulation" on and the graph actually compiled to GLSL; every emitter always has a matching
+ * {@link FXBehaviorArtifact} too (the mandatory JS fallback, including for the WebGL2->WebGL1
+ * emergency downgrade), so the runtime is never left with only this artifact and no JS twin.
+ */
+export interface FXParticleKernelArtifact {
+    readonly vertexSource: string;
+    readonly fragmentSource: string;
+    /** State buffers this program's `in`/`out` pairs cover, in declaration order - a buffer's index
+     *  here IS its `layout(location = N)` attribute index in {@link vertexSource}; the runtime binds
+     *  by that index, never by looking an attribute up by name. */
+    readonly buffers: readonly FXBufferLayout[];
+    /** Varying names for `gl.transformFeedbackVaryings`, one per {@link buffers} entry, same order. */
+    readonly transformFeedbackVaryings: readonly string[];
+    /** Live-tunable uniform values (graph-authored params only - the fixed contract uniforms in
+     *  `behaviorTransformFeedbackLayout.ts` are always declared and are the runtime's own
+     *  responsibility to set every tick, not part of this map). Float32Array is reserved for a
+     *  future sampler2D-backed (LUT) uniform; no standard-tier node produces one yet. */
+    readonly bindings: Record<string, FXValueSlot<number | Float32Array>>;
+}

package/dist/behaviorTransformFeedbackLayout.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Frozen transform-feedback (WebGL2, standard-tier behavior) uniform-name contract, shared by the
+ * editor's standard-tier behavior assembler (`FXKernelBuildStandard.Internal.ts`) and the
+ * runtime's transform-feedback driver. Every fused spawn+update program declares all of these
+ * uniforms unconditionally, regardless of whether a given graph actually reads them - fixed,
+ * literal names both sides import instead of independently deriving, the same reasoning as
+ * `coreLayout.ts`'s `PARTICLE_AGE`-style macros. Dependency-free (the editor imports this too), so
+ * keep it three-free and portable.
+ *
+ * Buffer-backed `in` attributes and `out` (transform-feedback) varyings are NOT listed here: a
+ * compiled program binds attributes by explicit `layout(location = N)` index (N = the buffer's
+ * position in the artifact's own `buffers` array), and transform-feedback varying names travel
+ * with the artifact itself (`FXParticleKernelArtifact.transformFeedbackVaryings`) - neither needs
+ * a shared naming scheme, only these truly fixed, graph-independent uniforms do.
+ */
+export declare const FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_START_UNIFORM = "u_fxSpawnRangeStart";
+export declare const FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_COUNT_UNIFORM = "u_fxSpawnRangeCount";
+export declare const FX_TRANSFORM_FEEDBACK_SPAWN_ID_BASE_UNIFORM = "u_fxSpawnIdBase";
+export declare const FX_TRANSFORM_FEEDBACK_CAPACITY_UNIFORM = "u_fxCapacity";
+export declare const FX_TRANSFORM_FEEDBACK_RAND_SEED_UNIFORM = "u_fxRandSeed";
+export declare const FX_TRANSFORM_FEEDBACK_DELTA_TIME_UNIFORM = "u_fxDt";
+export declare const FX_TRANSFORM_FEEDBACK_MODEL_MATRIX_UNIFORM = "u_fxModelMatrix";
+export declare const FX_TRANSFORM_FEEDBACK_OBJECT_VELOCITY_UNIFORM = "u_fxObjectVelocity";
+export declare const FX_TRANSFORM_FEEDBACK_OBJECT_ANGULAR_VELOCITY_UNIFORM = "u_fxObjectAngularVelocity";

package/dist/behaviorTransformFeedbackLayout.js

@@ -0,0 +1,24 @@
+/**
+ * Frozen transform-feedback (WebGL2, standard-tier behavior) uniform-name contract, shared by the
+ * editor's standard-tier behavior assembler (`FXKernelBuildStandard.Internal.ts`) and the
+ * runtime's transform-feedback driver. Every fused spawn+update program declares all of these
+ * uniforms unconditionally, regardless of whether a given graph actually reads them - fixed,
+ * literal names both sides import instead of independently deriving, the same reasoning as
+ * `coreLayout.ts`'s `PARTICLE_AGE`-style macros. Dependency-free (the editor imports this too), so
+ * keep it three-free and portable.
+ *
+ * Buffer-backed `in` attributes and `out` (transform-feedback) varyings are NOT listed here: a
+ * compiled program binds attributes by explicit `layout(location = N)` index (N = the buffer's
+ * position in the artifact's own `buffers` array), and transform-feedback varying names travel
+ * with the artifact itself (`FXParticleKernelArtifact.transformFeedbackVaryings`) - neither needs
+ * a shared naming scheme, only these truly fixed, graph-independent uniforms do.
+ */
+export const FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_START_UNIFORM = "u_fxSpawnRangeStart";
+export const FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_COUNT_UNIFORM = "u_fxSpawnRangeCount";
+export const FX_TRANSFORM_FEEDBACK_SPAWN_ID_BASE_UNIFORM = "u_fxSpawnIdBase";
+export const FX_TRANSFORM_FEEDBACK_CAPACITY_UNIFORM = "u_fxCapacity";
+export const FX_TRANSFORM_FEEDBACK_RAND_SEED_UNIFORM = "u_fxRandSeed";
+export const FX_TRANSFORM_FEEDBACK_DELTA_TIME_UNIFORM = "u_fxDt";
+export const FX_TRANSFORM_FEEDBACK_MODEL_MATRIX_UNIFORM = "u_fxModelMatrix";
+export const FX_TRANSFORM_FEEDBACK_OBJECT_VELOCITY_UNIFORM = "u_fxObjectVelocity";
+export const FX_TRANSFORM_FEEDBACK_OBJECT_ANGULAR_VELOCITY_UNIFORM = "u_fxObjectAngularVelocity";

package/dist/coreLayout.d.ts

@@ -1,22 +1,26 @@
 /**
  * Frozen per-particle ABI shared by the runtime loop and every editor-emitted module.
- * Two GPU-mirrored core buffers only: `position` (vec3) and `lifecycle` (vec2 [age, lifetime]);
+ * Two GPU-mirrored core buffers only: `position` (vec3) and `lifecycle` (vec3 [age, lifetime, id]);
  * a particle is dead once `age >= lifetime`. Everything else (velocity, scale, ...) is an ordinary
  * node-declared `a_fx_<name>` attribute, not core.
  *
- * Split into two buffers because a Three instanced attribute is at most a vec4 - a 5-float core
- * cannot be one attribute, whereas vec3 + vec2 are two clean varyings. Dependency-free (the editor's
+ * Split into two buffers because a Three instanced attribute is at most a vec4 - a 6-float core
+ * cannot be one attribute, whereas vec3 + vec3 are two clean varyings. Dependency-free (the editor's
  * module emitter imports this too), so keep it three-free and portable.
  */
 export declare const FX_CORE_POSITION = "position";
 export declare const FX_CORE_LIFECYCLE = "lifecycle";
 export declare const FX_CORE_POSITION_STRIDE = 3;
-export declare const FX_CORE_LIFECYCLE_STRIDE = 2;
+export declare const FX_CORE_LIFECYCLE_STRIDE = 3;
 export declare const FX_POSITION_X = 0;
 export declare const FX_POSITION_Y = 1;
 export declare const FX_POSITION_Z = 2;
 export declare const FX_AGE = 0;
 export declare const FX_LIFETIME = 1;
+export declare const FX_ID = 2;
 export declare const FX_CORE_POSITION_VARYING = "p_position";
 export declare const FX_CORE_LIFECYCLE_VARYING = "p_lifecycle";
-export declare const FX_CORE_PARTICLE_DEFINES = "\n  #define PARTICLE_POSITION_X p_position.x\n  #define PARTICLE_POSITION_Y p_position.y\n  #define PARTICLE_POSITION_Z p_position.z\n  #define PARTICLE_POSITION p_position\n\n  #define PARTICLE_AGE p_lifecycle.x\n  #define PARTICLE_LIFETIME p_lifecycle.y\n";
+export declare const ATTRIBUTE_BUFFER_PREFIX = "fx_";
+export declare function isCoreBufferName(bufferName: string): boolean;
+export declare function meshPropertyKeyFor(bufferName: string): string;
+export declare const FX_CORE_PARTICLE_DEFINES = "\n  #define PARTICLE_POSITION_X p_position.x\n  #define PARTICLE_POSITION_Y p_position.y\n  #define PARTICLE_POSITION_Z p_position.z\n  #define PARTICLE_POSITION p_position\n\n  #define PARTICLE_AGE p_lifecycle.x\n  #define PARTICLE_LIFETIME p_lifecycle.y\n  #define PARTICLE_ID p_lifecycle.z\n";

package/dist/coreLayout.js

@@ -1,24 +1,36 @@
 /**
  * Frozen per-particle ABI shared by the runtime loop and every editor-emitted module.
- * Two GPU-mirrored core buffers only: `position` (vec3) and `lifecycle` (vec2 [age, lifetime]);
+ * Two GPU-mirrored core buffers only: `position` (vec3) and `lifecycle` (vec3 [age, lifetime, id]);
  * a particle is dead once `age >= lifetime`. Everything else (velocity, scale, ...) is an ordinary
  * node-declared `a_fx_<name>` attribute, not core.
  *
- * Split into two buffers because a Three instanced attribute is at most a vec4 - a 5-float core
- * cannot be one attribute, whereas vec3 + vec2 are two clean varyings. Dependency-free (the editor's
+ * Split into two buffers because a Three instanced attribute is at most a vec4 - a 6-float core
+ * cannot be one attribute, whereas vec3 + vec3 are two clean varyings. Dependency-free (the editor's
  * module emitter imports this too), so keep it three-free and portable.
  */
 export const FX_CORE_POSITION = "position";
 export const FX_CORE_LIFECYCLE = "lifecycle";
 export const FX_CORE_POSITION_STRIDE = 3;
-export const FX_CORE_LIFECYCLE_STRIDE = 2;
+export const FX_CORE_LIFECYCLE_STRIDE = 3;
 export const FX_POSITION_X = 0;
 export const FX_POSITION_Y = 1;
 export const FX_POSITION_Z = 2;
 export const FX_AGE = 0;
 export const FX_LIFETIME = 1;
+export const FX_ID = 2;
 export const FX_CORE_POSITION_VARYING = "p_position";
 export const FX_CORE_LIFECYCLE_VARYING = "p_lifecycle";
+// A kernel-compiled buffer name (e.g. "velocity", as authored/compiled - always unprefixed) to its
+// mesh property-buffer key: unchanged for the two core buffers, `fx_<name>` for every attribute.
+// The one place this mapping is defined - every mesh/simulation-holder pairing (JS or GPU) must
+// go through this, not re-derive the prefix locally, or the two sides can silently drift apart.
+export const ATTRIBUTE_BUFFER_PREFIX = "fx_";
+export function isCoreBufferName(bufferName) {
+    return bufferName === FX_CORE_POSITION || bufferName === FX_CORE_LIFECYCLE;
+}
+export function meshPropertyKeyFor(bufferName) {
+    return isCoreBufferName(bufferName) ? bufferName : `${ATTRIBUTE_BUFFER_PREFIX}${bufferName}`;
+}
 // Stable macro names so emitted render GLSL reads PARTICLE_POSITION_X / PARTICLE_AGE etc. instead
 // of hardcoding the varying names this module owns.
 export const FX_CORE_PARTICLE_DEFINES = `
@@ -29,4 +41,5 @@ export const FX_CORE_PARTICLE_DEFINES = `
 
   #define PARTICLE_AGE ${FX_CORE_LIFECYCLE_VARYING}.x
   #define PARTICLE_LIFETIME ${FX_CORE_LIFECYCLE_VARYING}.y
+  #define PARTICLE_ID ${FX_CORE_LIFECYCLE_VARYING}.z
 `;

package/dist/editor/index.d.ts

@@ -1,5 +1,6 @@
 export { FXEmitter } from "../emitter/FXEmitter.js";
 export type { FXFromArtifactsOptions } from "../emitter/FXFromArtifactsOptions.js";
+export type { FXApplyRenderArtifactOptions } from "../emitter/FXApplyRenderArtifactOptions.js";
 export type { FXApplyValues, FXEmitterOptions, FXEmitterBurstOptions, FXEmitterPlayOptions, } from "../emitter/FXEmitter.Internal.js";
 export { FXMesh } from "../render/FXMesh.js";
 export type { FXFromMeshArtifactOptions } from "../render/FXMesh.js";

package/dist/editor/index.js

@@ -13,5 +13,5 @@ export { FXMesh } from "../render/FXMesh.js";
 export { FXMeshMaterial } from "../render/FXMeshMaterial.js";
 export { resolveGeometrySource } from "../instancedParticle/primitiveGeometry.js";
 // Shared keyframe/transform sampling: the editor bakes keyframes and the runtime samples them, so
-// both sides must sample identically. See the frozen-contract note in CLAUDE.md.
+// both sides must sample identically - a frozen contract, never a one-sided edit.
 export { frameOfTime, keyframeSegment, normalizeQuaternion, quaternionFromValue, sampleTrack, sampleTracks, sampleTransform, slerpQuaternion, timeOfFrame, vectorFromValue, } from "../effect/FXEffectSampling.Internal.js";

package/dist/effect/FXEffect.d.ts

@@ -18,6 +18,8 @@ export declare abstract class FXEffect extends Group {
     private readonly specification;
     private readonly world;
     private readonly emitters;
+    private readonly emitterRenders;
+    private readonly meshRenders;
     private readonly meshMaterials;
     private readonly meshes;
     private readonly meshMotionTrackers;
@@ -63,6 +65,8 @@ export declare abstract class FXEffect extends Group {
     dispose(): void;
     private resetTransport;
     private advance;
+    /** Poses every entity for the frame `time` falls in, unless it already is. */
+    private poseAt;
     /** Fires burst/play events whose time lies in `[from, to)` on their owning emitter. */
     private fire;
     /**