three-nebula 10.0.3 → 11.1.0

package/package.json

@@ -1,47 +1,38 @@
 {
   "name": "three-nebula",
-  "version": "10.0.3",
+  "version": "11.1.0",
   "description": "WebGL based 3D particle engine",
-  "main": "./build/cjs/index.js",
-  "module": "./build/esm/index.js",
-  "bundlesize": [
-    {
-      "path": "./build/three-nebula.js",
-      "maxSize": "105 kB",
-      "compression": "none"
+  "main": "./dist/three-nebula.cjs",
+  "module": "./dist/three-nebula.mjs",
+  "unpkg": "./dist/three-nebula.umd.js",
+  "jsdelivr": "./dist/three-nebula.umd.js",
+  "exports": {
+    ".": {
+      "import": "./dist/three-nebula.mjs",
+      "require": "./dist/three-nebula.cjs"
     }
-  ],
+  },
   "directories": {
     "docs": "docs",
     "website": "website"
   },
   "scripts": {
-    "build": "npm run build:clean && npm run build:umd && npm run build:cjs && npm run build:esm",
-    "build:clean": "rm -rf ./build",
-    "build:umd": "webpack",
-    "build:cjs": "babel src --out-dir build/cjs --extensions \".js\" --source-maps inline --presets @babel/env",
-    "build:esm": "babel src --out-dir build/esm --extensions \".js\" --source-maps inline",
-    "dev": "webpack --mode=development --watch",
-    "sandbox": "concurrently -k \"npm:sandbox:*\"",
-    "sandbox:build": "webpack --config webpack.config.sandbox.js --mode=development --watch",
-    "sandbox:serve": "npx serve sandbox",
+    "build": "vite build",
+    "dev": "vite build --watch",
     "docs": "serve docs",
     "docs:build": "./scripts/docs-build",
-    "test": "NODE_ENV=test mocha --require @babel/register --colors './test/**/*.spec.js'",
-    "test:only": "NODE_ENV=test mocha --require @babel/register --colors",
-    "test:watch": "NODE_ENV=test mocha --require @babel/register --colors -w './test/**/*.spec.js'",
-    "test:watch-only": "NODE_ENV=test mocha --require @babel/register --colors -w ",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
     "lint": "eslint src test && npx madge --circular src",
     "lint:fix": "eslint --fix",
-    "coverage": "NODE_ENV=test npm run coverage:generate && npm run coverage:report",
-    "coverage:view": "open ./coverage/lcov-report/index.html",
-    "coverage:generate": "nyc mocha './test/**/*.spec.js' -- --require @babel/register",
-    "coverage:report": "nyc report --reporter=lcov",
     "git:publish": "./scripts/publish",
-    "ci:src": "npm run lint && npm run test && npm run coverage",
-    "ci:bundlesize": "./scripts/check-bundlesize",
-    "ci:website": "npm run ci --prefix website",
-    "analyze": "webpack-bundle-analyzer build/stats.json"
+    "vr": "node vr/capture-all.mjs",
+    "vr:baseline": "node vr/capture-all.mjs --baselines",
+    "vr:diff": "node vr/diff.mjs",
+    "vr:montage": "node vr/montage.mjs",
+    "ci:src": "npm run lint && npm run coverage",
+    "ci:website": "npm run ci --prefix website"
   },
   "repository": {
     "type": "git",
@@ -62,41 +53,26 @@
     "url": "https://github.com/creativelifeform/three-nebula/issues"
   },
   "homepage": "https://github.com/creativelifeform/three-nebula#readme",
-  "dependencies": {
-    "lodash": "^4.17.21",
-    "potpack": "^1.0.1",
-    "uuid": "^3.3.2"
-  },
   "peerDependencies": {
     "three": ">=0.122.0 <1.0.0"
   },
   "devDependencies": {
-    "@babel/cli": "^7.16.0",
-    "@babel/core": "^7.16.0",
-    "@babel/eslint-parser": "^7.16.0",
-    "@babel/plugin-proposal-object-rest-spread": "^7.16.0",
-    "@babel/plugin-transform-runtime": "^7.16.0",
-    "@babel/preset-env": "^7.10.1",
-    "@babel/register": "^7.16.0",
-    "@babel/runtime": "^7.16.0",
-    "@istanbuljs/nyc-config-babel": "^3.0.0",
-    "babel-loader": "^8.2.3",
-    "babel-plugin-istanbul": "^6.0.0",
-    "bundlesize": "^0.18.1",
+    "@playwright/test": "^1.61.1",
+    "@vitest/coverage-v8": "^3.2.6",
     "chai": "^4.2.0",
-    "concurrently": "^6.3.0",
-    "coveralls": "^3.0.3",
     "domino": "^2.1.1",
     "eslint": "^8.1.0",
     "eslint-plugin-import": "^2.25.2",
-    "eslint-webpack-plugin": "^3.1.0",
-    "mocha": "^9.1.3",
-    "nyc": "^15.1.0",
+    "lodash": "^4.17.21",
+    "pixelmatch": "^7.2.0",
+    "pngjs": "^7.0.0",
+    "potpack": "^1.0.1",
     "prettier": "^1.16.4",
+    "seedrandom": "^3.0.5",
     "sinon": "^7.1.1",
-    "three": "^0.127.0",
-    "webpack": "^5.61.0",
-    "webpack-bundle-analyzer": "^4.5.0",
-    "webpack-cli": "^4.9.1"
+    "three": "^0.185.1",
+    "uuid": "^11.1.1",
+    "vite": "^8.1.4",
+    "vitest": "^3.2.6"
   }
 }

package/specs/01-emitter-hierarchy.md

@@ -0,0 +1,200 @@
+# Spec 01 — Emitter Hierarchy
+
+Nested child emitters, ribbon/trail renderers, and the pooling required to make
+both survivable.
+
+**Depends on:** 04 (schema versioning) — this spec breaks the schema.
+**Entangled with:** 02 (determinism) — child seeds derive from parent particle IDs.
+
+---
+
+## Problem
+
+Today three-nebula emitters are siblings: a flat list, all anchored to the system
+transform, running in parallel with no knowledge of each other. This is fine for
+effects that happen *at one place* — fire, rain, explosions.
+
+It cannot express effects that ride individual particles. *Every spark leaves its
+own smoke trail* is unrepresentable: a sibling smoke emitter has exactly one
+position and the sparks have twenty.
+
+Parent-child emitters change the cardinality. The child is instanced **once per
+parent particle**. 20 sparks → 20 live child emitter instances, each riding one
+spark, each dying with it.
+
+Ribbons and trails are grouped in here because they are the payoff: a child
+emitter with `onCreate` inheritance leaving a ribbon along a parent's path is the
+sword-arc effect, and it only exists once hierarchy exists.
+
+---
+
+## Stage 0 — Audit
+
+Before writing code, establish:
+
+1. Does particle pooling exist? Where? Is it per-emitter or global?
+2. Do particles carry a stable, monotonic ID? If not, what identifies them?
+3. What is the exact renderer interface? Enumerate its lifecycle hooks.
+4. How does `System.update()` order emitter updates today?
+5. Is there any existing concept of emitter-to-emitter reference?
+6. How are emitters serialised in the current JSON schema?
+
+**Write the answers into this spec before proceeding.** Stages 1–4 assume answers
+that may be wrong.
+
+---
+
+## Stage 1 — Pooling foundation
+
+Pooling is currently a nice-to-have. After Stage 2 it is load-bearing: nested
+emitters multiply cardinality (100 parents × 50 children = 5,000 particles and
+100 emitter instances), and child instances must be recycled on parent death or
+the system leaks.
+
+**Deliverables:**
+
+- A pool for particles (may already exist — see audit)
+- A pool for **emitter instances** (new)
+- Explicit `acquire()` / `release()` with no allocation in the hot path
+- A global cap on live emitter instances, configurable, with a documented
+  overflow policy (drop-newest is usually right for FX)
+- Instrumentation: live counts for particles, emitter instances, pool hits/misses
+
+**Acceptance:** a 60-second run of a nested system shows zero growth in heap
+allocation attributable to particle or emitter instance churn.
+
+---
+
+## Stage 2 — The emitter tree
+
+**Schema change.** `system.emitters[]` becomes a tree. Each emitter node gains
+`children: Emitter[]`.
+
+```jsonc
+{
+  "version": 2,
+  "emitters": [
+    {
+      "id": "sparks",
+      "rate": { /* ... */ },
+      "initializers": [ /* ... */ ],
+      "behaviours": [ /* ... */ ],
+      "renderer": { "type": "sprite", /* ... */ },
+      "children": [
+        {
+          "id": "spark-smoke",
+          "inherit": { "position": "always", "rotation": "none", "scale": "none" },
+          "rate": { /* ... */ },
+          "renderer": { "type": "sprite", /* ... */ },
+          "children": []
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Semantics:**
+
+- A child emitter is **instantiated once per parent particle**, at that particle's
+  spawn.
+- The child instance's origin is the parent particle, not the system.
+- The child instance is destroyed when its parent particle dies. Its already-emitted
+  particles may either die with it or live out their lifetimes — this is a per-node
+  flag, `orphanPolicy: "kill" | "detach"`. Default `detach` (a spark's smoke should
+  outlive the spark).
+- Update order is **topological**: a parent's particles must resolve before its
+  children read their transforms. Depth-first is fine.
+
+**Guards:**
+
+- `maxDepth` — hard recursion limit. Self-triggering recursive nodes are a known
+  hazard in any hierarchical particle system: every ancestor instance is retained
+  until its last descendant dies, so an unbounded chain leaks until it exhausts
+  memory. Cap depth (suggest 4) and cap total instances (Stage 1).
+  *Prior art:* Effekseer permits recursion in its node tree — its documentation on
+  instance retention is worth reading before designing this guard.
+- Reject cycles at parse time.
+
+**Acceptance:** a two-level system (sparks → smoke trails) renders correctly;
+killing the system releases all child instances; instance count is bounded.
+
+---
+
+## Stage 3 — Inheritance modes
+
+Per channel — `position`, `rotation`, `scale` — with three modes:
+
+| Mode | Behaviour | Use |
+|------|-----------|-----|
+| `always` | Child continuously tracks parent particle | Trails, attached FX |
+| `onCreate` | Child snapshots parent transform at spawn, then free | Ribbons, tracks, debris |
+| `none` | Child ignores parent transform (system-space) | Rare; events |
+
+`onCreate` vs `always` is the same hierarchy producing opposite looks from one
+dropdown. It is the single highest-value nuance in this spec — do not skip it.
+
+**Acceptance:** switching `position` from `always` to `onCreate` on the same
+system visibly converts an attached trail into a left-behind band.
+
+---
+
+## Stage 4 — Ribbon and Trail renderers
+
+**These are two different things and should be two renderers.** Conflating them
+is a common mistake.
+
+### `RibbonRenderer`
+
+Connects **sibling particles of one emitter** into a continuous strip, in spawn
+order. The particles are the spine.
+
+- Requires stable spawn ordering (see 02 — particle IDs)
+- Width driven by a curve over particle age
+- Texture UV: `stretch` (U maps 0→1 across the whole ribbon) or `tile`
+  (U repeats per segment). Both are needed; stretch is the common default.
+- Geometry: triangle strip, camera-facing by default; optional axis-aligned
+- Handle the degenerate cases: fewer than 2 live particles, particles at
+  identical positions (zero-length segments produce NaN normals)
+
+### `TrailRenderer`
+
+Each particle keeps a **ring buffer of its own past positions** and renders a tail.
+No sibling relationship.
+
+- `trailLength` (samples) and `sampleInterval` (seconds) per particle
+- Memory cost is `particles × trailLength × 3 floats` — must be pooled (Stage 1)
+- Same width-over-age and UV modes as ribbon
+
+**Which to build first:** Ribbon. It composes with Stage 3's `onCreate` mode to
+give sword arcs, and it's cheaper. Trail is the fallback for when you want a tail
+without a child emitter.
+
+**Acceptance:** a child emitter with `inherit.position: "onCreate"` and a
+`RibbonRenderer` produces a coherent band along the parent's path.
+
+---
+
+## Stage 5 — Events (deferred, scope permitting)
+
+Distinct from attachment. Attachment = child lives alongside parent for its
+lifetime (Stages 2–3). Events = a discrete trigger that spawns a burst which then
+**outlives** the parent.
+
+- `onDeath` → spawn burst at parent's final position
+- `onCollision` → spawn burst at contact point
+
+Fireworks want events. Trails want attachment. Ship attachment first; events are
+a clean additive follow-on and should not block Stages 1–4.
+
+---
+
+## Notes for implementation
+
+- Particles stay dumb. Nothing about hierarchy enters the particle struct except
+  an ID (which 02 needs anyway). Child emitter instances hold the parent reference,
+  not the other way round.
+- The child instance is an *emitter*, not a *particle*. Do not try to model it as
+  a special particle type.
+- Every new random draw in this spec must go through the seeded PRNG from 02.
+  Child instance seeds derive from `hash(systemSeed, emitterId, parentParticleId)`.

package/specs/02-determinism-scrubbing.md

@@ -0,0 +1,188 @@
+# Spec 02 — Determinism & Scrubbing
+
+Make the simulation reproducible: same seed + same step count = byte-identical
+particle state, every time, on every machine running the same JS engine.
+
+**Blocks:** 03 (sound jitter), and any offline/headless rendering built on the library
+**Entangled with:** 01 (hierarchy) — child seeds derive from parent particle IDs
+
+---
+
+## Why this is not optional
+
+Determinism looks like a nicety. It is actually the load-bearing property under
+four separate product features:
+
+1. **Reproducible rendering** — a headless render must match what was seen live.
+2. **Offline rendering** — two renders of one system must be byte-identical.
+3. **Seek and scrub** — step, rewind, edit-while-paused in any editing tool built
+   on the library. The single most-used affordance in mature FX tooling.
+4. **Programmatic iteration** — render → inspect → revise loops only work if the
+   output is a pure function of the input.
+
+Retrofitting determinism means touching every initializer and behaviour. Doing it
+while already in there for 01 costs a fraction.
+
+---
+
+## Stage 0 — Audit
+
+1. Grep for `Math.random`. Every hit is a defect. Count them.
+2. Grep for `Date.now`, `performance.now`, `new Date` inside the sim path.
+3. Does the sim use a fixed timestep or raw `delta` from rAF?
+4. Do particles have IDs? Are they stable across frames?
+5. Is there any iteration over `Set` / `Map` / `Object.keys` whose order affects
+   simulation output?
+6. Is there existing seed handling anywhere?
+
+---
+
+## Stage 1 — Seeded PRNG
+
+Replace all `Math.random()` with an injected, seedable generator.
+
+- Suggested: `mulberry32` or `xoshiro128**`. Small state, fast, good enough
+  distribution for FX. Do not use anything cryptographic.
+- The PRNG instance must be reachable from every initializer, behaviour, and
+  renderer that draws randomness. Pass it down; do not use a module singleton
+  (two systems on one page must not share a stream).
+
+**Acceptance:** `grep -r "Math.random" src/` returns zero hits in the sim path.
+
+---
+
+## Stage 2 — Seed derivation hierarchy
+
+Randomness must be *addressable*, not merely seeded. A single sequential stream
+breaks the moment emitters update in a different order.
+
+```
+systemSeed                         (user-set or random at creation)
+  └─ emitterSeed   = hash(systemSeed, emitterId)
+       └─ particleSeed = hash(emitterSeed, particleId)
+            └─ childEmitterSeed = hash(systemSeed, childEmitterId, particleId)
+```
+
+- `particleId` — monotonic counter per emitter, never reused, survives pooling
+  (i.e. a recycled particle object gets a *new* ID)
+- Each particle carries its own PRNG state, seeded from `particleSeed`
+- This is what makes 01's child emitters reproducible: the child's stream is a
+  pure function of which parent particle it rides
+
+**Acceptance:** reordering emitters in the JSON does not change any individual
+emitter's output.
+
+---
+
+## Stage 3 — Fixed timestep
+
+The sim must advance in fixed increments, decoupled from rAF.
+
+- Accumulator pattern: accumulate real delta, consume in fixed steps
+  (suggest 1/60s, configurable)
+- Clamp max steps per frame to avoid spiral-of-death on a slow frame
+- Optionally interpolate render state between steps (defer — not needed for v1)
+
+Without this, the same system produces different results on a 60Hz and a 144Hz
+display, and rendering offline at a different fps produces a different effect.
+
+**Acceptance:** stepping the sim 600× at 1/60 produces identical state regardless
+of wall-clock time taken.
+
+---
+
+## Stage 4 — Seek / scrub
+
+**You cannot run a stochastic sim backwards.** Do not try.
+
+Seek is implemented as **reset + fast-forward**:
+
+```
+seek(t):
+  reset to step 0 with the same seed
+  run ceil(t / dt) fixed steps with rendering disabled
+```
+
+- Forward seek from the current position is an optimisation, not a requirement —
+  correctness first
+- **Checkpointing** (snapshot full particle state every N steps, restore + replay
+  the remainder) is the obvious speed-up if seek becomes slow. Defer until measured.
+- Scrubbing must not fire audio (see 03) or any other side effect
+- Expose `step()`, `seek(t)`, `reset()`, `setTimeScale()` on the system
+
+**Acceptance:** `seek(2.0)` twice from different starting states produces
+identical particle buffers.
+
+---
+
+## Stage 5 — The determinism test
+
+This is the deliverable that keeps the property from rotting.
+
+- Hash the full particle buffer (positions, velocities, colors, ages) at
+  step N into a stable digest
+- Golden-file test: a corpus of systems, each with an expected digest at several
+  step counts
+- Run in CI. Any change that breaks a digest is either a bug or an intentional
+  change requiring a new golden file
+- Include at least one nested system once 01 lands
+
+**Acceptance:** CI fails if determinism regresses.
+
+---
+
+## Stage 6 — Headless contract
+
+Determinism is necessary but not sufficient for offline rendering. The system must
+also be *drivable from outside*, with no environmental dependencies.
+
+Consumers that step the library headlessly — in a Web Worker against an
+`OffscreenCanvas`, or under headless Chromium — are out of scope for this repo, but
+the contract that makes them possible is not.
+
+**Requirements:**
+
+- **The library never owns a loop.** No internal `requestAnimationFrame`. The caller
+  supplies `dt` and decides when to advance. (Verify in Stage 0 — this may already
+  hold.)
+- **No wall-clock reads in the sim path.** Covered by Stage 3, restated here because
+  it is the requirement that breaks headless stepping when violated.
+- **Simulation and rendering are separable.** A caller must be able to step N times
+  without rendering, or render the same state twice, in any order.
+- **No DOM access in the sim path.** No `document`, no `window`, no
+  `HTMLImageElement`. Textures arrive as decoded data via the resolver (05), not as
+  DOM elements. This is the requirement most likely to be quietly violated today.
+- **No `HTMLCanvasElement` assumption.** Anything canvas-shaped must accept an
+  `OffscreenCanvas`.
+
+**Acceptance:** a system steps 600 times inside a Web Worker with no DOM present,
+and produces particle state digests identical to the same run on the main thread.
+
+**Explicitly not this repo's job:** frame capture, sprite-sheet packing, video
+encoding, camera framing, warmup heuristics, loop-point selection, CLI, queueing.
+Those belong to whatever consumes this contract.
+
+---
+
+## Known non-determinism sources to eliminate
+
+| Source | Fix |
+|--------|-----|
+| `Math.random()` | Seeded PRNG (Stage 1) |
+| `Date.now()` / `performance.now()` in sim | Fixed timestep (Stage 3) |
+| Variable rAF delta | Fixed timestep (Stage 3) |
+| `Set`/`Map` iteration order | Sort, or use arrays |
+| Pool reuse order affecting IDs | IDs from a counter, not pool index |
+| Async texture load racing spawn | Resolve all assets before first step |
+
+**Not a concern:** IEEE-754 float behaviour is deterministic within a given JS
+engine on a given platform. Cross-platform float divergence matters for lockstep
+netcode, not for this. Do not over-engineer.
+
+---
+
+## Explicitly out of scope
+
+- Cross-runtime determinism (three-nebula ↔ a port to another engine)
+- Rewind / reverse simulation
+- Deterministic GPU simulation (revisit if/when a compute path exists)