three-nebula 11.0.0 → 11.1.1

package/package.json

@@ -1,43 +1,38 @@
 {
   "name": "three-nebula",
-  "version": "11.0.0",
+  "version": "11.1.1",
   "description": "WebGL based 3D particle engine",
-  "main": "./build/cjs/index.js",
-  "module": "./build/esm/index.js",
+  "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",
     "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 test && npm run coverage",
-    "ci:website": "npm run ci --prefix website",
-    "analyze": "webpack-bundle-analyzer build/stats.json"
+    "ci:src": "npm run lint && npm run coverage",
+    "ci:website": "npm run ci --prefix website"
   },
   "repository": {
     "type": "git",
@@ -58,45 +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": "^11.1.1"
-  },
   "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",
     "@playwright/test": "^1.61.1",
-    "babel-loader": "^8.2.3",
-    "babel-plugin-istanbul": "^6.0.0",
+    "@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.185.1",
+    "uuid": "^11.1.1",
     "vite": "^8.1.4",
-    "webpack": "^5.61.0",
-    "webpack-bundle-analyzer": "^4.5.0",
-    "webpack-cli": "^4.9.1"
+    "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)

package/specs/03-sound-renderer.md

@@ -0,0 +1,183 @@
+# Spec 03 — Sound Renderer
+
+Treat particles as sound sources. A renderer that emits voices instead of pixels.
+
+**Depends on:** 02 (seeded jitter, scrub muting), 05 (audio blob storage)
+**Priority:** lowest of the five. Most additive, least entangled, easiest to defer.
+
+---
+
+## The model
+
+**This is not a sound-type particle.** It is an ordinary particle that a sound
+renderer happens to be reading.
+
+The particle stays dumb — position, life, age, alpha, size. It has no idea it's
+audible. The *renderer* decides to interpret the stream as voices. Nothing new
+enters the particle struct. The simulation does not branch.
+
+Sound sits alongside billboard, mesh, ribbon and light as a peer renderer.
+
+*Prior art:* this is PopcornFX's model — its renderer list is billboard, mesh,
+ribbon, light, **sound**, decal, triangle, where the sound renderer simply treats
+particles as sound sources in the world. It's the right shape and worth copying
+closely.
+
+**Corollary:** a layer can carry both renderers. An ember that glows *and* crackles
+is one emitter with a `SpriteRenderer` and a `SoundRenderer` reading the same
+particles. No duplicate emitter.
+
+**Corollary 2:** triggering is already built. "Play a sound 0.5s in" is an emitter
+with `delay: 0.5`, `burst: 1`, `life: <sound duration>`, and a sound renderer. It
+draws nothing. It exists to be heard. The existing rate/burst/delay controls *are*
+the sound sequencer.
+
+---
+
+## Stage 0 — Audit
+
+1. Exact renderer interface — confirm the lifecycle hooks. Assumed:
+   `onParticleCreated`, `onParticleUpdate`, `onParticleDead`, `onSystemUpdate`.
+2. Is there any existing audio anywhere in the codebase? (Assume no.)
+3. How does the system expose the camera? The audio listener must track it.
+
+---
+
+## Stage 1 — One-shot voices
+
+**v1 is one-shot only.** Fire and forget. Persistent/attached sounds are Stage 5
+and may never happen.
+
+```
+onParticleCreated(particle):
+  if (!canPlay()) return          // voice cap, cooldown, probability
+  const src = ctx.createBufferSource()
+  src.buffer = resolvedBuffer
+  src.detune.value = jitter(particle.prng, detuneRange)
+  src.connect(panner).connect(gain).connect(ctx.destination)
+  src.start(ctx.currentTime, startOffsetJitter(particle.prng))
+```
+
+That's it. No handle retained. The voice finishes and GCs itself.
+
+**Config on the renderer (not the particle):**
+
+```jsonc
+{
+  "type": "sound",
+  "src": { "$ref": "sha256:..." },
+  "volume": 0.8,
+  "detuneCents": [-200, 200],
+  "startOffsetMs": [0, 30],
+  "maxVoices": 8,
+  "cooldownMs": 40,
+  "probability": 0.2,
+  "attenuation": { "refDistance": 1, "maxDistance": 50, "rolloff": 1 },
+  "gainFrom": "alpha",        // optional particle attribute → gain
+  "pitchFrom": null
+}
+```
+
+---
+
+## Stage 2 — Voice limiting
+
+**This is the feature.** 500 sparks × a sound renderer = 500 voices = catastrophe.
+
+Three independent throttles, all needed:
+
+1. **`maxVoices`** — hard cap per renderer. When exceeded, steal the
+   lowest-priority live voice or drop the new one (drop is usually better for FX).
+2. **`cooldownMs`** — minimum gap between triggers on this renderer. Kills the
+   machine-gun case where 50 particles spawn in one frame.
+3. **`probability`** — play on only N% of particles. The cheapest and most
+   effective control. 500 sparks, 5% probability → 25 crackles. Sounds right,
+   costs nothing.
+
+**Priority heuristic warning.** The obvious voice-stealing heuristic — rank by
+`volume × attenuation` — is naive, and it's worth understanding why before
+shipping it. It reads the *configured* volume, not perceived loudness: a quiet
+sample at volume 1.0 outranks a hot sample at 0.1, which is backwards.
+
+The pragmatic answer is to use the heuristic anyway and require **normalised
+source audio** (all samples at roughly equal perceptual loudness), then **say so
+in the docs**. Do not attempt loudness analysis in v1.
+
+*Prior art:* PopcornFX prioritises exactly this way, and its docs are refreshingly
+candid that the heuristic misjudges for precisely this reason — their guidance is
+to normalise source audio so it behaves. Their sound renderer page is worth reading
+before implementing this stage.
+
+---
+
+## Stage 3 — Jitter (required, not polish)
+
+Many copies of the same sample within a few milliseconds phase-cancel into
+flanging mush. Two mitigations, both mandatory:
+
+- **Detune jitter** — per-voice `detune` in cents, drawn from the *particle's*
+  seeded PRNG (02). Suggest ±200 cents default.
+- **Start-offset jitter** — a few ms of random offset into the buffer. Decorrelates
+  transients even at identical pitch.
+
+Both must be deterministic — the same system must produce the same pitches on
+every run. (Audio is not captured by offline rendering anyway — see below — but
+the property should hold regardless.)
+
+---
+
+## Stage 4 — Context lifecycle and scrub
+
+**Autoplay policy.** `AudioContext` starts `suspended` until a user gesture. This
+is not a bug to work around; design for it:
+
+- The system must function fully with audio unavailable. Sound is decoration on
+  a working sim, never a dependency.
+- Expose `system.audio.resume()` for the host to call from a click handler.
+- Default to silence; opt in on an explicit user action. Any consumer displaying
+  many systems at once must not auto-play audio.
+
+**Mute conditions** — the renderer must not fire when:
+
+- Seeking / scrubbing (02, Stage 4)
+- `timeScale !== 1` (pitch would be wrong and it's not worth correcting)
+- The system is being stepped headlessly (02, Stage 6)
+- `ctx.state !== "running"`
+
+**Clock note.** Web Audio's `currentTime` and rAF are different clocks. Spawning
+voices off rAF gives up to ~16ms jitter. That is tolerable for FX and not worth
+fixing in v1. If anything rhythmic ever matters, schedule against `ctx.currentTime`
+with lookahead — do not do this now.
+
+---
+
+## Stage 5 — Persistent voices (deferred, possibly never)
+
+A sound that travels with a particle and stops on its death. Requires holding a
+handle per voice, updating the panner in `onParticleUpdate`, and stopping in
+`onParticleDead`.
+
+*Prior art:* Niagara splits exactly here. `Play Audio` is the one-shot — cheapest,
+fires and forgets, and once triggered it cannot be changed or stopped and keeps
+playing even if the simulation does not. `Play Persistent Audio` retains a
+reference per voice so it can be updated over time, requires a paired update
+module, and is notably trickier to set up.
+
+That two-feature split is a good signal: the persistent path is meaningfully
+harder and most effects don't need it. **Do not build this until something
+concrete demands it.**
+
+---
+
+## Known limitations to document, not solve
+
+- **Offline rendering loses audio.** A sprite sheet has no audio track. A system
+  with a sound renderer renders silently, so sound and any sheet/video export path
+  do not compose. Not fatal; be explicit about it in the docs.
+- **No external mixer.** A native engine has audio middleware (Wwise, FMOD)
+  downstream to arbitrate voice budgets, ducking and concurrency — engine
+  integrations of FX tools typically defer to it, and PopcornFX's UE integration
+  has you configure max concurrency per sound asset for exactly this reason. On the
+  web there is nothing downstream. The library owns its own voice budget, which is
+  why the limiting in Stage 2 is the substance of this spec rather than an
+  optimisation.