babylon.quarks 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -4,6 +4,768 @@ All notable changes to the `babylon.quarks` package are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project follows the `quarks.core` 0.x version line.
 
+## [0.27.0] — 2026-10-23
+
+The release that follows the October 2026 audit: every domain (emitters, behaviors, system and
+loader, shaders, trails) was brought to the working rules in `CLAUDE.md`. A 0.27.0 dated
+2026-10-21 was prepared but never published; its entries are folded in here, so this is the only
+0.27.0 and the whole list applies when upgrading from 0.26.
+
+### Breaking changes
+
+Each item is described in full in the section it points to.
+
+- **Exports removed** that nothing in the package read: `VFXBatchSettings.reflectionFaces`,
+  `MeshSettings.rotationAxis`, the `ParticleMesh*Material` classes, the shader chunk registry and
+  GLSL string exports, `BatchedParticleRenderer`, the `SpriteBatch` / `TrailBatch` exports,
+  `ParticleEmitter.extractFromCache`, `ParticleSystemParameters.startLength` and the duplicate
+  `quarks.core` type re-exports (Removed); `ApplyForce` loses its runtime fields `magnitudeValue`
+  and `memory` (Changed).
+- **Trails stretch their texture by distance** by default; set the texture mode to
+  `'distributePerSegment'` to keep the old layout (Changed).
+- **`WidthOverLength` spans the samples the trail holds**, not its `startLength` capacity
+  (Changed).
+- **Trails face the camera in view space**; the trail material loses its `lineWidth`,
+  `resolution`, `sizeAttenuation`, `world` and `worldViewProjection` uniforms (Changed).
+- **Flipbook frames wrap into the sheet** and the last cell blends into the first (Changed).
+- **`softFarFade` defaults to 1**, so soft particles fade without a fade distance set (Changed).
+- **Soft particles name their depth encoding**: `setDepthTexture(depth, {encoding})` with
+  `'linear'` as the default; a hand-built non-linear depth needs `'nonLinear'` (Changed).
+- **`ApplyForce` is a world force**; a local-space effect that relied on the old reading sets
+  `space: 'local'` (Changed).
+- **`OrbitOverLife` orbits the emitter about the emitter's normalised axis**; set `space: 'world'`
+  for the old orbit (Changed).
+- **`Noise` turns mesh particles by `rotationAmount`** instead of ignoring it (Changed).
+- **`TurbulenceField` is deterministic**: two fields with the same settings and no `seed` swirl
+  identically (Changed).
+- **Bursts take the file defaults in code too**: `interval` is 0.1 s when left out, and the
+  system holds its own copy of `emissionBursts` (Changed).
+- **A system belongs to one `BatchedRenderer` at a time**, and a disposed renderer refuses
+  `addSystem` with an error (Changed).
+- **`ParticleSystem.toJSON()` ids are numbered per `meta`**, so two separate calls both write
+  `quarks_geometry_1`; merge outputs through one `meta` or use `serializeEffect` (Changed).
+- **A disposed system stays disposed**: `restart()` no longer brings it back (Changed).
+- **Seeded systems roll differently from 0.26**; a saved seed gives a different, still repeatable,
+  effect (Changed).
+- **`serializeEffect` writes the url a texture's image had in its source file** rather than the
+  joined url, so a save next to the source loads; a save elsewhere passes `imageUrl` (Changed).
+- **TypeScript:** the fields of `ParticleSystemJSONParameters` other than `version` are optional,
+  and `StoredBatchSettings.texture` is `BaseTexture | null` (Changed).
+
+### Added
+
+- **Trail texture modes** (`TrailSettings.textureMode`, Unity's Texture Mode): `'stretch'` (the
+  default) runs the texture once along the ribbon by distance; `'distributePerSegment'` once with
+  each recorded segment an equal share (Niagara's Scaled Uniformly, what trails did before);
+  `'tile'` repeats it per world unit, anchored where the particle was born so a sample keeps its U
+  while it lives (Niagara's Tiling Distance); `'repeatPerSegment'` once per segment.
+  `TrailSettings.textureScale` (Unity's Texture Scale) sets the repeats: per unit, per segment or
+  over the ribbon. `uvFromHead` runs any mode from the particle back. The texture's UV channel 1
+  follows the same U. Each sample now records its distance along the trail
+  (`TrailParticle.historyDistances`, `measureHeadDistance()`).
+- **`TrailSettings.minVertexDistance`** (Unity's Min Vertex Distance): a point is fixed only once
+  the particle has moved that far from the last fixed one, the newest sample following the
+  particle meanwhile (`TrailParticle.update(replaceHead)`), so a slow or standing particle no
+  longer fills its history with points on one spot, and the trail's length is a distance rather
+  than a number of steps.
+- **`TrailSettings.lifetime`** (Unity's Time): samples older than that many seconds are dropped
+  from the tail (`TrailParticle.historyAges`, `dropOldest()`), within the `startLength` cap.
+- **`ParticleSystem.clearTrails()`** (Unity's `TrailRenderer.Clear`): drops every ribbon and keeps
+  the particles, which start new ones where they are. With `pause()`, the move and `play()`, it is
+  how an emitter teleports without a ribbon across the jump; the advice to `pause()` alone, given
+  below, never cleared the samples already recorded.
+- Normalisers `trailTextureMode`, `trailTextureScale`, `trailMinVertexDistance`, `trailLifetime`,
+  beside `trailTessellation` and `trailCurveTension`; the trail settings' JSON writes each only
+  when set, and `fromJSON`, `clone()`, `serializeEffect` and `QuarksLoader` carry them all.
+- Demo: Trail Texture Modes and Sampling.
+- **`shaderProgram()` and `shaderVariants()`**: the defines, attributes, uniforms, samplers and
+  sources (GLSL and WGSL) of the material a batch builds from its settings, and every distinct
+  program the library can compile (Unity's ShaderVariantCollection), for warming the shader cache
+  before the first frame. The batches build their materials through `shaderProgram`, so the list
+  is the code's own account of what it compiles; `npm run validate:shaders` compiles every variant
+  in both languages in CI (the former `validate:wgsl` compiled a hand-written WGSL subset that
+  missed, among others, the env atlas, lit meshes with texture effects, and effects with fog, soft
+  particles or alpha test). Types `ShaderProgram`, `ShaderSettings`, `ShaderContext`,
+  `ShaderVariant`, `ShaderSources`.
+- **`ParticleSystem.clear()`** (Unity's `Clear`): removes the particles alive and nothing else; the
+  emission clock, the bursts and the pause stay where they were, and the sub emissions the
+  removed particles were driving end with them.
+- **`space` on `ApplyForce`, `ForceOverLife` and `OrbitOverLife`** (quarks.core), the space the
+  force or the orbit is authored in (Unity's Space on Force over Lifetime): `'world'` keeps gravity
+  down and wind steady however the emitter is turned, and orbits the world origin about a world
+  axis; `'local'` turns and scales the force with the emitter, and orbits the emitter about one of
+  its own axes. The forces default to `'world'`, the orbit to `'local'`. The behavior converts into
+  the space the system simulates in, so a setting means the same in a local and a world-space
+  system, and the compiled behavior pass does the same. Written to JSON only when not the default.
+  The type is `BehaviorSpace` (`VelocityOverLifeSpace` is now an alias of it); the decomposed
+  emitter transform the conversions use is `EmitterFrame`, for behaviors of your own. The editor
+  shows Space on Force over Lifetime and Gravity, and Seed on Turbulence. The Force Space demo
+  shows a world gravity and a local thrust on turning emitters.
+- **`seed` on `TurbulenceField`** (quarks.core): the field is built from it, 0 by default, so the
+  same settings swirl the same way on every run and in every copy; give each system its own seed
+  for different fields. Written to JSON only when set. `ParticleSystem.seed` now covers the whole
+  effect, since no behavior rolls outside the step any more.
+- **`PhysicsResolver`** (quarks.core) is exported, and `setPhysicsResolver(undefined)` unregisters
+  the host's resolver. `ApplyCollision` asks the registered resolver when a particle is tested,
+  so one registered after the effect loaded takes effect; a resolver given to the constructor is
+  still preferred. `getPhysicsResolver()` is typed as possibly undefined.
+- **`prewarmTime` on `ParticleSystem`**: how much of the cycle `prewarm` simulates before the first
+  frame, in seconds (Niagara's Warmup Time), on a looping system like `prewarm` itself. 0, the
+  default, warms up a whole cycle as Unity's Prewarm does; a shorter time warms up the cycle's last part only, with the bursts before it
+  counted as fired, which is enough for an effect whose particles live shorter than its cycle and
+  keeps a long cycle's first frame cheap. Cut to the cycle and to the static
+  `ParticleSystem.maxPrewarmSeconds` guard; written to JSON only when set.
+- **`transparent`, `depthTest`, `depthWrite` and `alphaTest` on `ParticleSystem`**, the material
+  flags a system is built with, readable and settable afterwards like `blending`. Setting one
+  moves the system to a matching batch. `alphaTest` is kept to 0…1; the material flags were
+  only constructor parameters and JSON fields before.
+- **`instancingIndices` on `ParticleSystem`**: the mesh particles' index list, settable after
+  construction. Mesh systems that share a vertex buffer but not an index list (sub-meshes of one
+  buffer) are now batched apart; they used to share a batch and draw with the first system's
+  indices.
+- **`serializeEffect(root, options?)` writes a whole effect** as one document `QuarksLoader`
+  loads back, the counterpart of `loader.load()`. It writes the node tree (groups, emitters, mesh
+  nodes with their geometry, prefabs with `timeScale`), each texture with its sampler state, and a
+  format version. The result is plain data, so `JSON.stringify` takes it; a loaded effect saved
+  again writes the same file. A texture with no url a file can point at is reported through
+  `onWarning`, as are links to nodes it does not write and mesh settings it cannot hold. Options:
+  `filter` to leave out helper nodes, `imageUrl` to write image urls relative to where the file is
+  saved, `generator`, and `name` for several roots. A mesh node that is not drawn keeps its
+  children drawn (`isVisible: false`, which the loader now reads). The document types are exported (`QuarksEffectJSON` and the rest), and the format is
+  described in `docs/FORMAT.md`. Before, `ParticleSystem.toJSON` left live textures and materials
+  in its meta, and every caller wrote its own envelope.
+- **Effect files carry a format version**, `metadata.quarksFormat` (`QUARKS_FORMAT_VERSION`). The
+  loader warns about a file from a newer version. Files without one still load.
+- **`QuarksFormatError`**, thrown by `QuarksLoader.parse` for a document with no `object`.
+- **Loads can wait for textures, report what failed, and be cancelled.** The loader option
+  `waitForTextures` makes `load`, `loadFromJSON`, `loadAll` and `loadFromJSONAll` resolve once every
+  texture of the effect has loaded or failed, so it does not draw its first frames blank, like an
+  Addressables or Unreal streamable handle completing. `onResourceError(kind, url, error)` reports
+  each geometry file or image that fails; the effect still loads. A `signal` (`AbortSignal`) in the
+  new `QuarksLoadOptions`, and in `QuarksBatchLoadOptions`, cancels a load: it rejects with the
+  signal's reason as soon as it is aborted and leaves no node of the effect in the scene, whatever
+  `continueOnError` says. The effect document's fetch is cancelled, and a custom
+  `QuarksResourceResolver.fetchJson` gets the signal for it. A scene disposed during a load rejects
+  it the same way, and a batch whose effect fails stops waiting on the others' textures.
+- **A loaded effect frees what it owns when it is disposed**: the materials made for it, and each
+  texture once no other loaded effect, or copy of one, uses it. This holds however the root goes
+  (`root.dispose()`, its parent's or the scene's); `QuarksLoader.disposeEffect(root)` says so in
+  code. Before, those materials and textures stayed in the scene. A material or texture of a loaded
+  effect handed to other code is freed with the effect.
+- **Soft particles and alpha test on trails.** `softParticles` and `alphaTest` now apply to trails
+  as to every other render mode, in GLSL and WGSL. Before, a trail accepted them, batched on them
+  and drew hard with a fixed 0.01 cutoff.
+- **Soft-particle depth encodings:** `SoftDepthEncoding`, `DepthTextureOptions`,
+  `BatchedRenderer.depthEncoding`, and the decode helpers `softDepthParams` and `decodeSoftDepth`
+  (see Changed).
+- **`disposeEnvAtlas(cube, scene?)`** drops the env atlases built for a cube.
+- **Trail tessellation** (`TrailSettings.tessellation`, `curveTension`), like Niagara's ribbon
+  tessellation and curve tension:
+  - Each segment between two recorded samples is drawn as `tessellation + 1` segments along a
+    centripetal cardinal spline through the samples: Catmull-Rom at `curveTension` 0 (the
+    default), straight at 1. Centripetal spacing keeps the curve from overshooting where samples
+    lie unevenly apart.
+  - A fast or sharply turning trail, such as a weapon swing that moves far between frames, stays
+    round instead of showing its corners. The curve passes through every sample, so the trail
+    keeps its shape.
+  - Swept trails curve their sides with the points, keeping each side's length, so a blade's trail
+    stays as wide as the blade.
+  - Widths, colors and the texture's U are eased along the curve. The live tip drawn between
+    steps joins it with a straight segment, so the recorded part stays still as the tip moves.
+  - `tessellation` is a whole number from 0 (the default: off, no cost) to 16
+    (`MAX_TRAIL_TESSELLATION`). JSON writes both settings only when set. Helpers:
+    `trailTessellation`, `trailCurveTension`.
+- **`textureSourceUrl(texture)`**: the url a loaded texture's image had in its effect file,
+  before the loader joined a base url, which `serializeEffect` now writes by default. It is
+  `undefined` for a texture made in code, one whose image a resolver inlined as a `data:` url, or
+  one whose `url` changed since it was loaded, which all write their `url` as before.
+
+### Removed (breaking)
+
+The public API is now what the docs describe; these exports were left over from the three.js port
+or duplicated something else, and nothing in the package used them.
+
+- **`VFXBatchSettings.reflectionFaces`**: six face textures were read off a material
+  (`material.reflectionFaces`) and kept in the batch key, but no shader ever sampled them.
+  `reflectionTexture` is documented as it works: a cube texture is unfolded into `reflectionAtlas`
+  and sampled from there; nothing else is sampled.
+- **`MeshSettings.rotationAxis`** (quarks.core), which was declared but never read, written or
+  cloned: a mesh particle's rotation is its start rotation (`startRotationX/Y/Z`, or a
+  `RandomQuatGenerator` / `EulerGenerator` start rotation) and `Rotation3DOverLife`. A file that
+  wrote it loses nothing, since no runtime ever read it.
+- **`ParticleMeshStandardMaterial`, `ParticleMeshPhysicsMaterial` and
+  `BabylonParticleMaterialParameters`.** Mesh particles are drawn by the batch's own material; set
+  their look with the system's `material`, `texture` and lighting settings.
+- **The three.js shader chunk registry**: `registerShaderChunks`, `getShaderChunk`,
+  `getRegisteredShaderChunks`, and the side effect that ran it on import. The batches never read
+  it.
+- **The GLSL shader string exports** (`particleVertShader`, `particleFragShader`,
+  `localParticleVertShader`, `trailVertShader` and the rest). The batches build their shaders
+  themselves, in GLSL and WGSL.
+- **`BatchedParticleRenderer`**, an alias of `BatchedRenderer`.
+- **The `SpriteBatch` and `TrailBatch` exports.** `BatchedRenderer` makes the batches; `VFXBatch`
+  stays exported as the type of `renderer.batches`.
+- **`ParticleEmitter.extractFromCache`**, a three.js serialisation helper.
+- **`ParticleSystemParameters.startLength`**, which nothing read. A trail's length is
+  `rendererEmitterSettings.startLength`.
+- **The duplicate type re-exports of `quarks.core`.** The same types still come from
+  `export * from 'quarks.core'`.
+
+### Changed
+
+- **A trail's texture is stretched by distance** (breaking: an existing effect file has no
+  `textureMode`, so its trails now stretch by distance, which shows wherever a trail's speed
+  varies along its length): the default texture mode is Unity's Stretch, so a fast stretch of
+  the ribbon shows more of the texture than a slow one. Trails used to give each recorded segment
+  an equal share whatever its length; set `textureMode: 'distributePerSegment'` to keep that. A
+  ribbon that has not moved is laid out per segment, since it has no distance to stretch over.
+- **`WidthOverLength` spans the samples the trail holds** (breaking for a young trail): the curve's
+  end is the oldest sample, as Unity's width curve runs over the trail as it is, so a trail cut
+  short by `lifetime` or `minVertexDistance` reaches the curve's end and a trail still growing
+  shows the whole curve compressed. It used to span the `startLength` capacity, so a growing or
+  shortened trail never tapered to the curve's end.
+- **`followLocalOrigin: false` is no longer written to JSON**, as the other trail settings at
+  their defaults are not (three.quarks's loader reads a missing flag as off); `startLength` is
+  still always written, for loaders that read it without a default. A JSON `sideAxis` that is
+  not three finite numbers (numeric strings still count), or has no length, is dropped with a
+  `[quarks]` warning instead of making a ribbon of no width (or of NaN).
+- **A particle at the end of its life is dead for its trail too.** The trail path recorded one
+  more sample at `age === life`, the step the removal pass already counted the particle dead, and
+  the renderer drew a tip for it; the samples, the world-space rewrite, the side axis and the tip
+  now all stop at `age < life`.
+- **Flipbook frames wrap into the sheet, and the last cell blends into the first** (breaking for a
+  frame outside the sheet). A frame past the last cell used to read outside the texture, a
+  negative one differed between GLSL (floored) and WGSL (truncated), and with `blendTiles` the last
+  frame cross-faded into a cell that does not exist. The cell is now computed by one shared chunk in
+  both languages and by the trail's CPU path (`sheetCell`), frames wrapping as Unity's Texture
+  Sheet Animation loops. `blendTiles` compiles nothing on a 1×1 sheet, where the `TILE_BLEND` shader
+  read varyings the vertex stage never wrote (undefined behaviour on some GLSL drivers; the common
+  content of imported files).
+- **`uTileCount`, `vTileCount`, `softNearFade` and `softFarFade` are normalised**: tile counts are
+  whole numbers of at least 1 (a 0 or fractional count divided by zero in the shader), fade
+  distances are finite and at least 0. **`softFarFade` defaults to 1** (breaking): with the old
+  default of 0 a soft particle was cut off hard at the scene instead of fading, so soft particles
+  did nothing unless a fade distance was set; a file that wrote neither fade now fades over one
+  unit, Unreal's Depth Fade default.
+- **Mesh particles light both faces and keep their normals under a non-uniform size.** The normal
+  is scaled by the inverse of the size, so a stretched mesh stays lit as a stretched mesh rather
+  than as its unscaled shape, and a back face (meshes draw without culling) is lit, reflected and
+  rimmed as the face the camera sees instead of as the hidden one; a mirrored size (a negative
+  component) turns the normal with the winding, so a mirrored mesh lights the same way.
+- **A stretched billboard seen along its velocity no longer vanishes**: the side vector was
+  `normalize(0)` (NaN) for a particle moving straight at the camera; it falls back as the beam's
+  already did.
+- **A rim fade can discard**: `MESH_RIM_FADE` lowered the alpha after the alpha test had run, so a
+  face faded to nothing still passed the test; the test now runs after the rim.
+- **A gradient map without a map tints every render mode the same**: sprites ignored it and meshes
+  (which sample a white placeholder) took the ramp's end colour; both now look the ramp up at white.
+- **Linear fog with `fogEnd == fogStart`** divided by zero; it is a cut at that distance.
+- **Erosion and distortion write only non-default values** to JSON (`softness`, `edgeWidth`,
+  `edgeColor`, `strength`, a missing `mask`), like every other setting; a gradient map, erosion mask
+  or distortion map that is not a url-backed `Texture` warns when it is left out of a file instead
+  of vanishing silently.
+- Documented: the fixed discard of fragments under alpha 0.01, fog on multiply and subtract blend
+  modes, `blendTiles` needing a sheet and not applying to trails, trails cutting their flipbook
+  cell on the CPU.
+- Internal: the unused `worldView` and `worldViewProjection` uniforms and the `USE_COLOR_AS_ALPHA`
+  define, which nothing set, are gone from the sprite shaders.
+- **A system belongs to one `BatchedRenderer` at a time.** `addSystem` on a second renderer takes
+  the system out of the first (both used to step and draw it), and adding a system again after
+  its settings changed moves it to the matching batch instead of leaving it in two. A disposed
+  renderer lets its systems go (they can join another renderer) and refuses `addSystem` with an
+  error; a setter on a system after its renderer was disposed used to rebuild a batch, mesh and
+  material under the dead node. The renderer warns once when it is itself transformed: particles
+  are placed by their emitters, so its transform would move them again.
+- **Opaque materials no longer draw a depth pre-pass.** `needDepthPrePass` was set whenever a
+  system wrote depth, so an opaque mesh system drew twice; it is now set only for a transparent
+  material that writes depth, which is what the pre-pass is for.
+- **Setting `renderMode` or `instancingGeometry` keeps the pause.** Both rebuild the particles
+  through `restart()`, which also unpaused a stopped system; the pause state is kept now.
+  Switching to `Mesh` at runtime gives the system normals when it has none (the mesh shader reads
+  them; a mesh without the attribute was the iOS `GL_INVALID_OPERATION`), and a geometry with a
+  different vertex count takes its own index sequence instead of keeping the old geometry's
+  indices (a cube given to a quad system drew two triangles). `play()` is documented as resuming
+  only; a finished system needs `restart()`.
+- **Bursts are normalised, in code and from a file.** A burst given to the constructor and one
+  read from JSON take the same defaults: `interval` 0.1 s when left out (the file default; the
+  constructor used to fire the waves all at once), `probability` kept to 0..1, `cycle` at least 1,
+  a non-finite `time` 0, a numeric `count` a constant; and the bursts are kept in time order, which
+  emission relies on: `restart()` puts bursts edited in place back in order, so an editor that
+  appends a burst at 0 after a later one no longer fires it late. The constructor used to keep the
+  caller's array; it now holds its own copy, so edit `emissionBursts` rather than the array that
+  was passed in. `BurstParameters.count` is documented as rolled per play and read at the wave's
+  time as a fraction of the duration, which is what the code has done since 0.27's burst fix.
+- **Setting `ParticleSystem.time` resynchronises the bursts and is normalised.** The bursts
+  before the new time count as fired and the ones after are due again (a burst the clock was set
+  past used to fire on the next step anyway); NaN or a negative value is 0 (NaN used to hang the
+  system, never finishing), a value past the duration wraps on a looping system. The waves of a
+  burst in progress are counted with the emission's own arithmetic, so a wave on a rounding edge is
+  no longer skipped (this also affected prewarm).
+- **`emissionMultiplier` is kept finite and at or above 0**; a negative, NaN or infinite value
+  counts as 0 (a negative value used to be ignored, an infinite one hung the spawner). An infinite
+  burst `cycle`, which hung the burst loop, is 1.
+- **`ApplyForce` is a world force (breaking for turned or scaled emitters in local-space systems,
+  and for `motionScale`).** It used to push along its direction in whatever space the system
+  simulated in, so a local-space system with a turned emitter had its "gravity" turned with it,
+  and a world-space system in `'hierarchy'` scaling mode did not scale it with the emitter, unlike
+  `ForceOverLife`. Both forces now follow the same rule: a `'world'` force is converted into the
+  emitter's axes for a local-space system and multiplied by `motionScale` in a world-space one. A
+  file that relied on the old reading sets `space: 'local'`. Converting a world vector into a
+  non-uniformly scaled emitter's axes now undoes the rotation before the scale, as the matrix's
+  inverse does; `ForceOverLife` used to do it the other way round. `GravityForce` is documented as
+  pulling toward a point in the simulation space.
+- **`OrbitOverLife` orbits the emitter, about the emitter's axis (breaking for a non-unit axis,
+  and for world-space systems).** The axis is normalised: an axis of length 2 used to turn
+  particles twice as far and push them off their circle. In a world-space system the pivot is now
+  the emitter's world position and the axis turns with the emitter, where it used to orbit the
+  world origin about the world axis; an effect that wants the old orbit sets `space: 'world'`.
+  A zero axis orbits nothing. The compiled behavior pass does the same.
+- **`Noise` turns mesh particles by `rotationAmount` (breaking for mesh particles with a
+  `rotationAmount`).** A quaternion particle used to be turned by
+  a normalised four-noise quaternion, which ignored the amount and the power altogether: a
+  `rotationAmount` of 0.001 wobbled as hard as 1. It now turns about an axis the X, Y and Z noise
+  choose by W noise × π × amount, the angle a billboard would turn by.
+- **`TurbulenceField` is deterministic and restarts cleanly (breaking: two fields with the same
+  settings and no `seed` now swirl identically).** Its noise permutation and time offsets were
+  rolled from the global random source when the behavior was constructed, so a clone, a reloaded
+  file and a seeded system all swirled differently, and `reset()` did nothing;
+  a zero `scale` component divided by zero and filled the velocities with NaN. The field now comes
+  from `seed` (see Added), `reset()` rewinds the drift, and a zero scale samples the field at 0
+  along that axis (no variation there) instead.
+- **`ForceOverLife` before its first particle.** `update`, `updateAll` and the compiled pass
+  disagreed on a behavior that had not seen a particle yet (one applied the force, one skipped
+  it); all three now apply it as a world force.
+- **The `Behavior` interface documents its contract**: the order the host calls `initialize`,
+  `frameUpdate`, `update`/`updateAll` and `reset` in, what the particle looks like at each, that
+  randomness goes through `quarks.core`'s `random()` so a host that wraps its steps in
+  `setRandomSource` replays an effect, and that everything else a behavior keeps derives from its
+  settings. `BehaviorTypes[...].params` lists every field a behavior writes (`Noise`'s
+  `scrollSpeed` and `remap`, `VelocityOverLife`'s `radial` and `orbitalOffset`, `FrameOverLife`'s
+  options, `WidthOverLength.absolute`, the new `space` and `seed`), and the serialisation contract
+  test fails when a field is written that the table does not list, so an editor cannot miss one.
+- **A moving emitter's motion is spread over the steps of a frame.** The simulation runs in fixed
+  1/60 s steps, several per frame on a slow display, and every step of a frame used the emitter
+  where the frame ended: the frame's spawns clumped there, and a trail recorded in world space
+  stair-stepped behind a moving emitter. Each step now gets the emitter interpolated between
+  where the last simulated step had it and where it is now, position, rotation and scale apart,
+  the way Niagara's interpolated spawning does; emission over distance already spawned along the
+  path, and the rate's spawns and world-space trail samples now follow it too; a burst due on a
+  mid-frame step fires where the emitter was then. A single-step frame, the first frame after
+  `play()`, `restart()`, a catch-up or a spell out of view, and a still emitter are unchanged, so
+  a copy placed and restarted (as `EffectPool.acquire` does) starts where it was put. A large move
+  of a playing system is motion like any other: a frame of two or more steps lays that frame's
+  spawns and trail samples along the jump, so teleport with `pause()` or `stop()` first.
+  `emitterVelocity` is still the frame's displacement over its time, which is the per-step
+  velocity of a linear path, so Inherit Velocity is unaffected. A seeded system with a moving
+  emitter plays differently from 0.27 when a frame runs more than one step; the simulation
+  snapshot test was re-recorded.
+- **Batches are keyed on what the render mode draws.** The renderer used to split systems on
+  every setting, including the ones their mode ignores: two billboards with different mesh rims,
+  two meshes with different billboard pivots or size limits, two opaque systems with different
+  blend modes, two systems with different soft fade distances and soft particles off, or two
+  trails with different instanced geometry each cost a draw call. They now share a batch. The
+  settings a mode ignores are at their defaults in the batch's `settings`, so an opaque batch's
+  `materialBlendMode` reads `ALPHA_DISABLE` and a billboard batch's `rim` is unset.
+- **Live parameters change a batch's material in place.** The values that only set uniforms (the
+  soft fade distances, the alpha cutoff, the pivot, the size limits, the reflection level, the rim
+  colour, power and strength, each texture effect's numbers and each texture's tiling, offset and
+  scroll) are the batch's live parameters, as a Unity MaterialPropertyBlock's values or an
+  Unreal dynamic material instance's parameters. Changing one on a system that is alone in its
+  batch writes the material and keeps the batch; it used to make a new batch, mesh and material
+  per value, and leave the old one for 120 frames. A change that needs a different shader (a
+  cutoff or pivot switched on or off, a rim mode, a texture) still rebuilds the material, and a
+  system that shares its batch still moves to a batch with its values. `VFXBatchSettings`
+  documents the two groups.
+- **A particle system's JSON leaves out settings at their defaults.** `toJSON`, and so
+  `serializeEffect` and the editor's saves, used to write every setting; now a setting is written
+  only when it differs from the default, and a missing field reads as the default. The shape, the
+  start and emission curves except `startDelay`, `startTileIndex`, the geometry, the material and
+  the behaviors are still always written, since loaders up to 0.27 and three.quarks need them, so
+  both still load the files. Files from earlier releases load as before. The fields of
+  `ParticleSystemJSONParameters` other than `version` are therefore optional (breaking for
+  TypeScript code that read them without a check).
+- **Every export has TSDoc**, and `npm run docs:check`, part of `npm run check` and CI, keeps it
+  that way. Members that are public only for other files of the package are tagged `@internal`
+  and left out of the API docs: the batches' buffers and lifecycle methods, `VFXBatch.addSystem`,
+  `applyDepthTexture`, `applyMeshLighting` and the like. They still compile, but are not part of
+  the contract.
+- **`StoredBatchSettings.texture` is typed `BaseTexture | null`** instead of `any` (breaking for
+  TypeScript code that assigned something else), and `ParticleSystemParameters.material` is
+  `unknown`: a Babylon material, or the material record a loaded system carries.
+- **`ParticleSystemParameters.speedFactor` is deprecated** in favour of
+  `rendererEmitterSettings.speedFactor`, and the demos use the latter.
+- **`BatchedRenderer.deleteSystem` is typed to return `boolean`**, whether the system was in a
+  batch, which it already returned.
+- **`QuarksPrefab.toJSON` writes `timeScale`** when it is not 1, so `toJSON` and `fromJSON` round-trip;
+  only `serializeEffect` wrote it before.
+- **The package compiles with TypeScript's `strict` mode.** The published declarations are the
+  same as before.
+- **`loadFromJSON` and `loadFromJSONAll` no longer change the document they are given.** They
+  resolve urls and inline geometry files on a copy, so one document can be loaded many times, into
+  several scenes or with several base urls. Code that read the resolved urls back from its own
+  document should call `resolveResources` (which still works in place) or read the loaded nodes.
+- **`EffectPool` frees a copy with `QuarksLoader.disposeEffect`**, and `QuarksUtil.instantiate`
+  gives the copy a hold on the source's textures, so disposing the source leaves its copies drawing
+  and the last one to go frees the textures.
+- **A geometry file that fails to load is reported through `onResourceError`** (default: the
+  same console warning as before). With `waitForTextures`, `onProgress` counts an effect once its
+  textures have settled.
+- **Unreadable parts of an effect warn and take their default** instead of throwing a `TypeError`
+  or going silent: an unknown shape gives a point emitter, an unknown behavior is skipped with a
+  warning, an unknown curve or colour type warns, and a setting the file leaves out (a system's
+  `startLife`) takes the constructor's default. A behavior's missing number, vector or speed
+  range takes a fixed default where the constructor has none (see `docs/FORMAT.md`). A mesh surface shape whose mesh is not in the effect warns, as a sub emitter does.
+- **Systems of one document share geometry and texture entries.** `ParticleSystem.toJSON(meta)`
+  writes a geometry or texture once per `meta`, however many systems or slots use it, and numbers
+  its ids per document, so the same effect serializes to the same file. Ids are no longer unique across
+  calls: two separate `toJSON()` calls both write `quarks_geometry_1`, so merge their outputs
+  through one `meta`, or use `serializeEffect`.
+- **Trails face the camera in view space (breaking for custom trail shaders)**, across their
+  tangent and the line of sight, like Unity's View alignment and Niagara's ribbons. The width is
+  the particle's size in world units, measured across the line of sight. Before, the facing was
+  worked out on screen, which spiked across the view when a trail passed the camera and put NaN
+  vertices (holes) at repeated points and hairpins. The trail material no longer has the
+  `lineWidth`, `resolution`, `sizeAttenuation`, `world` and `worldViewProjection` uniforms. Code
+  that set or read them, or a shader built on them, should drop them; to change a trail's width,
+  scale `startSize` or add `WidthOverLength`.
+- **A trail system made without `rendererEmitterSettings`** gets `startLength: 30` and
+  `followLocalOrigin: false`, as setting `renderMode` to Trail does, instead of throwing on its
+  first particle. `startLength` and `followLocalOrigin` are documented.
+- **Box and edge shapes now apply their shape transform.** `BoxEmitter` and `EdgeEmitter` take a
+  `transform` (offset, rotation and scale within the system) like the other shapes, and write and
+  read it in JSON. Before, a Unity export that moved, turned or scaled a Box, Rectangle or Edge
+  shape lost that transform, and its particles started from the system's origin. Effects with such
+  a shape now emit where they were authored.
+- **`ApplyForce` no longer has the public runtime fields `magnitudeValue` and `memory`.** The
+  magnitude is rolled per particle (see Fixed); read `magnitude` for the setting.
+- **Texture sequencer JSON names its type and writes `position` as `[x, y, z]`.** Files written
+  before this release, with no type and an `{x, y, z}` position, still load.
+- **Color, Size and Rotation by Speed read the current speed**, like Unity's modules and
+  Niagara's Scale by Speed: the velocity's length times the speed modifier, clamped to
+  `speedRange`. Motion `VelocityOverLife` adds does not count, since it moves particles without
+  changing their velocity. Before, they read the start speed, so a particle slowed by drag, a limit or a
+  collision kept its birth colour and size. Effects that use them on particles whose speed changes
+  now look different. An empty `speedRange` is a step at its value instead of NaN. The helper is
+  exported as `speedFraction`.
+- **`LimitSpeedOverLife` dampen is clamped to 0..1 and no longer depends on the frame rate.** At
+  60 steps a second a step still removes `dampen / 3` of the excess speed, so babylon.quarks
+  effects, which step at 60 Hz, look the same. Other step lengths now remove the share that
+  compounds to the same loss per second; before, a long step could reverse the velocity.
+- **A disposed system stays disposed.** `restart()` no longer brings it back, `update()` and
+  `emit()` do nothing, and `dispose()` drops its particles, also when called from a
+  `particleDied` listener. `isDisposed` (also on `IParticleSystem`) says so.
+- **Node ids in saved effects.** `ParticleEmitter.uuid`, and every link a file writes to a node
+  (sub emitter targets, mesh surface meshes, prefab animation targets), is now
+  `quarksNodeId(node)`: the uuid the node was loaded under, or a GUID given once to a node made in
+  code. Before, nodes made in code were written under their Babylon `uniqueId`, which differs per
+  session and can equal a loaded node's id. The editor writes every node this way too. Files
+  saved earlier with numeric ids still load; a prefab resolves a numeric id only to a node with no
+  file uuid.
+- **A Death sub emitter ignores `inherit: ['lifetime']`**, since its parent has no life left;
+  its particles live their own life.
+- **Soft particles: the depth texture now says what it stores (breaking for hand-built depth).**
+  `setDepthTexture(depth, {encoding})` takes `'linear'` (Babylon's default depth renderer, the
+  default), `'nonLinear'` (the depth buffer value, Unity's `_CameraDepthTexture`) or `'viewZ'`
+  (view-space Z, Unreal's SceneDepth). Pass the `DepthRenderer` itself and its encoding and
+  packing are read off it: `setDepthTexture(scene.enableDepthRenderer(camera))`. Perspective and
+  orthographic cameras, WebGL and WebGPU depth ranges, a reverse depth buffer and an infinite far
+  plane (`'nonLinear'` or `'viewZ'`) are handled. Before, the shaders always decoded a depth buffer
+  value, which no Babylon depth renderer writes by default. If you fed a non-linear depth by hand,
+  pass `{encoding: 'nonLinear'}`. The `projParams` uniform now holds the decode coefficients from
+  `softDepthParams`; the `soft_pars_fragment` chunk uses them too.
+- **Soft particles are compiled in only while a depth texture is set**, as Unity turns them off for
+  a camera with no depth texture. Without one they draw hard instead of sampling an unbound
+  texture; setting or clearing it rebuilds the soft batches.
+- **Batch meshes are not pickable, take no collisions and are not serialized** by Babylon's scene
+  serializer. Their geometry is one quad or mesh at the origin, not the particles.
+- **Env atlases are cached per scene**, so a second scene or engine (an editor preview) gets its
+  own instead of a texture of the first scene. `getCachedEnvAtlas(cube, scene?)` takes the scene.
+  An atlas quarks built is disposed with its cube; `disposeEnvAtlas(cube, scene?)` drops one
+  sooner. A system whose atlas is disposed while its cube is kept builds a new one.
+- **`BatchedRenderer.depthTexture` is an accessor**, and setting it calls `setDepthTexture`.
+  `VFXBatch.applyDepthTexture` takes a depth binding as well as a texture.
+- **Seeded systems roll differently from 0.26.** A seeded system now rolls its emission rates,
+  burst counts and start delay on its own generator when it is created and on every restart, so
+  a restart replays them too. A seed saved with 0.26 gives a different, still repeatable, effect,
+  and lock-step sessions must not mix 0.26 and 0.27 clients.
+- **`serializeEffect` writes each image's url as its source file had it** (breaking for a save
+  that relied on the joined url): a texture loaded from `fx/hit.json` as `tex/a.png` holds the url
+  `fx/tex/a.png`, and the saved file used to point at that, so a save next to the source loaded
+  `fx/fx/tex/a.png` the next time. The file now gets `tex/a.png` (see `textureSourceUrl`), as
+  Unity and Unreal keep asset links relative to the project; `imageUrl` still overrides it for a
+  save elsewhere, and a texture made in code still writes its `url`.
+
+### Fixed
+
+- **A trail re-emitted with a random `startLength` reallocated its history every time.** The ring
+  buffers were replaced whenever the capacity changed; they now only grow
+  (`TrailParticle.ensureHistoryCapacity`), and `TrailParticle.length` defaults to 30, the
+  documented value, instead of 100.
+- **Trail batches allocated twice the vertices they could draw.** The buffers were sized in
+  vertex pairs but compared against vertex counts, so every trail batch held two unused copies
+  of itself on the CPU and the GPU; `maxParticles` now counts vertices.
+- **A tessellated trail bunched its points at the samples at `curveTension: 1`** and on the live
+  tip's segment: the Hermite basis eased a segment with no tangents while its widths, colours and
+  U ran linearly. A straight segment is now walked evenly.
+- **Local-space sub emitter particles jumped to the next parent.** A sub emitter target in local
+  space (`worldSpace: false`) draws each particle through the matrix of the emission that spawned
+  it; that matrix object was reused for the next emission once the first ended, so particles that
+  outlived their emission (a child whose particles live longer than its `duration`) moved to where
+  the next parent died. The matrix now stays with the particles born through it, so they keep
+  following their parent while it lives (Frame and Birth modes), and the next emission gets its own.
+- **`ChangeEmitDirection` with a random angle (`IntervalValue`) threw on every spawn**
+  (`memory.push is not a function`): its scratch memory was in a format the generators no longer
+  use. It is a generator memory now, cleared before each spawn, so one sample is rolled per
+  particle and the memory does not grow. The behavior and `restart()` reset it.
+- **Arc modes keep their position within the arc.** `Loop` and `PingPong` at a negative speed, and
+  `Burst` for particles emitted by rate (not in a burst), gave positions outside 0…1, so the particle landed outside the arc or on the wrong side
+  of it; `PingPong` also started at the arc's far end. `Loop` wraps, `PingPong` starts at the arc's
+  start and sweeps back and forth, `Burst` places rate-emitted particles at random, and `spread`
+  snaps the result afterwards, as Unity's Arc Mode and Spread do.
+- **`restart()` starts a sweeping shape over.** A `Loop`/`PingPong` shape resumed its arc from where
+  the system stopped, so a seeded replay or a pooled copy did not spawn where the original did.
+  `EmitterShape` gained an optional `reset()`, which the built-in sweeping shapes implement and
+  `restart()` calls; a custom shape with sweep state can implement it too.
+- **`PointEmitter` emits at the start speed.** It scaled the speed by a random cube root, so with
+  `startSpeed` 5 the particles left at anything from 0.4 to 5, which no other shape and no Unity
+  shape does. Directions are uniform over the sphere as before. An effect tuned to the old spread of
+  speeds should set `startSpeed` to a random range (`IntervalValue`) to keep it.
+- **Cone `thickness` maps to the radius as Unity's Radius Thickness does.** The ring started at
+  `sqrt(1 - thickness)` (0.71 of the radius for a thickness of 0.5) instead of `1 - thickness`, and
+  the Unity exporter already wrote the value 1:1. Emission is uniform over the ring's area, and
+  the thickness is kept to 0…1 (a value above 1 used to give NaN positions).
+- **Curves and gradients hold their last key past 1.** `ContinuousLinearFunction` (vector and colour
+  curves, gradient keys) returned the _first_ key for a time past 1, so a particle that outlived its
+  curve snapped back to its start colour on the exact path while the sampled table held the end.
+  Both paths agree now.
+- **An empty or unknown sequencer no longer breaks the system.** `TextureSequencer` with no
+  locations (before `fromImage`, or `locations: []` in a file) threw on the first particle it moved;
+  it leaves the particle where it is. A sequencer of an unknown type in a file used to become a
+  silent empty one and throw the same way; it warns and is skipped, like an unknown behavior.
+- **The start colour and a burst's count curve run over the cycle like every other start curve.**
+  Both were sampled in seconds, so with a 4 s cycle a start-colour gradient was read past its end
+  from 1 s on, and a burst count curve was read at the burst's time in seconds. They now get the
+  normalised time of the cycle (0 to 1), as `startLife`, `startSpeed` and `startSize` do and as
+  Unity evaluates them. A sub emission reads the time since it began (its parent particle's birth
+  or death) over the target's duration, as its other start curves already did; before, a sub
+  emitter target's burst count curve was always read at 0, since the target's own clock never
+  runs. An effect authored to the old sampling changes: a start-colour gradient or burst count
+  curve meant to span the cycle now does.
+- **Distance covered while emission over distance is 0 is not owed later.** With a rate curve
+  that rises, or a rate switched on in code or in the editor, the emitter used to spawn a line of
+  particles for every metre it had moved while the rate was 0.
+- **A system stopped, paused or disposed from a listener stays stopped for the rest of the
+  frame.** `stop()` from a `finished` listener (which `EffectPool` does on release), `dispose()`
+  from `particleDied` and `autoDestroy` used to be followed by the frame's remaining steps, which
+  emitted into the stopped system and could fire `finished` again.
+- **A fast playback speed runs at full speed.** The 0.1 s frame clamp now applies to the host's
+  frame before it is scaled by `playbackSpeed`, and the per-frame step cap grows with the speed, so
+  speed 10 advances 10 seconds per second; before, it was held to about 6. A host frame longer than
+  0.1 s is still simulated as 0.1 s at any speed.
+- **Prewarm runs on the fixed step directly**, not through `update()`, so it always simulates one
+  whole cycle: before, `playbackSpeed` scaled it too, so at speed 0.5 only half the cycle was
+  warmed up and at speed 0 none of it. It costs one step per 1/60 s of the cycle and no more. A
+  cycle longer than `ParticleSystem.maxPrewarmSeconds` (10 by default, a performance guard for the
+  whole app) is warmed up over its last part only, with the burst waves due before that counted as
+  fired, so a long looping effect does not stall its first frame.
+- **Invalid clock settings are normalised.** A negative, NaN or infinite `playbackSpeed` reads as
+  0 (the clock never runs backwards) and a `duration` shorter than one simulation step (1/60 s),
+  0 or NaN reads as one step, so `timeRatio` stays finite; both are accessors now and normalise
+  what is set after construction too. The constructor also reads an invalid `cullingMode` as
+  `'always'` and a negative or NaN `maxParticles` as no limit, as `fromJSON` already did. A
+  negative or NaN frame given to `update()` is no time at all.
+- **A culled `'pauseAndCatchUp'` system owes at most 0.1 s per frame it missed**, the same clamp a
+  visible system's frame gets; before, one stalled frame off screen could owe up to the 2 s cap.
+- **`QuarksPrefab.play()` after `pause()` resumes the timeline's systems and clips**; before, a
+  system paused in the middle of its track stayed paused until the track ended.
+- **Setting `MeshSurfaceEmitter.mesh` to nothing, or to a mesh without positions or indices,
+  emits from the origin** as documented, instead of from the previous mesh.
+- **A stretched billboard system no longer writes its defaults into the
+  `rendererEmitterSettings` object it was given**, as trails already did not.
+- **A texture whose image failed to load is no longer shared.** The next load of the same image
+  tries it again instead of reusing the broken texture. A texture the engine cannot make at all is
+  reported and left out instead of failing the load.
+- **A loader read the images of the document it parsed before.** A document with textures but no
+  `images` loaded the previous document's pictures. Each parse now has its own.
+- **`loadPlugin` did not record the plugin**, so loading it again ran `initialize` again and
+  `unloadPlugin` removed nothing. `unloadPlugin` now removes only the types that plugin registered.
+- **`QuarksPrefab.timeScale` was not read from files.**
+- **A trail's live tip folded back over its head** on frames where the last step ran ahead of the
+  display, about every other frame at 120 Hz. The head is now drawn back along its last segment
+  instead. Float noise in the step accumulator no longer adds a tip of no length.
+- **A dead trail particle's tip kept moving**, drawing a spike that grew while the trail shrank.
+  The trail now ends at its last sample.
+- **The live tip ignored `WidthOverLength`**, so a trail narrowed by it flared at the tip on
+  frames between steps.
+- **`WidthOverLength` read its curve past the end** for a fractional or zero `startLength`.
+- **Camera-dependent uniforms reached the GPU one draw late.** The eye position (rim, env
+  reflection), the soft-particle depth decode and the `'scene'` light were
+  written after the material had uploaded its uniforms, so each draw used the previous bind's
+  values: a frame late with one camera, and the other camera's with `activeCameras`. They now reach
+  the effect of the draw they are for.
+- **Soft particles faded against the wrong depth**, both from the decode (see Changed) and because
+  the particle's own depth had the wrong sign for a left-handed camera, Babylon's default.
+- **GLSL and WGSL applied fog and the soft fade in different orders**, so WebGPU kept a fog-coloured
+  fringe where a fogged soft particle met geometry. Both now fade last, after fog.
+- **A mesh batch rebuilt for its env atlas lost the soft-particle depth texture.**
+- **A non-looping system whose rate curve starts at 0 never emitted.** It reported nothing
+  pending on its first step and finished at once. A rate that rises later in the cycle now counts
+  as pending.
+- **A looping system reported pending emission after `endEmit()`.**
+- **A disposed sub emitter target kept taking particles without limit**, since nothing updated it
+  any more. Sub emitters now skip disposed targets.
+- **Death sub emissions followed a newborn.** The dying particle's object is reused for the next
+  particle, and the emission followed that one back to the emitter, inheriting its colour and size.
+  A Death emission now stays where its parent died and inherits what the parent died with. Birth
+  and Frame emissions stop following when their parent dies (`Particle.serial`). A restart or
+  `stop()` drops the emissions still running from the last play.
+- **`useVelocityAsBasis` stretched the sub emitter by the parent's speed**, and gave a NaN matrix
+  for a parent moving along -Z or faster than 1 along +Z. The basis is now orthonormal.
+- **The fused `VelocityOverLife` ignored `radial` and `orbitalOffset`.** The fused pass, which runs
+  by default, now matches the per-particle path.
+- **Sub emitter and mesh surface links broke when a loaded effect was saved again.** The links were
+  written with Babylon's `uniqueId` and the nodes with the uuid they were loaded under.
+- **`clone()` shared state with the original**, so editing one changed the other:
+  - `ChangeEmitDirection`, the `Euler` rotation generator and `Vector3Function` (and with it
+    `SizeOverLife` with separate axes) reused their child generators.
+  - A system's emission bursts shared their `count` generator, and `startTileIndex` was shared.
+  - `emissionMultiplier` and a fixed `beamEnd` point were not copied. A `beamEnd` given as a
+    Babylon `Vector3` is now copied by value too. A `beamEnd` node is still shared, since the
+    clone follows the same node.
+- **`ApplyForce` with a random magnitude threw** when it was created or loaded, since its
+  generator memory was the wrong shape for `IntervalValue`. The magnitude is now rolled per
+  particle at emission, as Unity's Force over Lifetime does with Random Between Two Constants, on
+  the system's seeded random source.
+- **`ApplySequences` lost its sequences in JSON.** A texture sequencer wrote no type, so loading
+  the file could not tell which sequencer to build.
+- **Node ESM, webpack 5 and SSR could not import the package.** The ESM and CJS builds imported
+  `@babylonjs/core` deep paths without `.js`, which only lenient bundlers such as Vite resolve.
+  Every deep import now ends in `.js`. The `exports` map now gives `require` its own declaration
+  file (`dist/types/index.d.cts`) and lists `./package.json`, so TypeScript with
+  `node16`/`nodenext` resolution types both module kinds. `npm run check:pack` now installs the
+  packed tarballs into a scratch project and imports them with Node ESM, Node CJS and TypeScript
+  `nodenext`.
+- **`restart()` broke random emission.** It emptied the system's generator memory without
+  rolling `emissionOverTime` again, so an `IntervalValue` rate became NaN and the system emitted
+  nothing. Every pooled effect with a random emission rate was empty from its second play.
+- **`restart()` kept the emission-over-distance history.** A pooled effect placed somewhere new
+  and restarted spawned a line of particles along the jump from where it last played.
+- **Disposing an emitter node left its system running.** `root.dispose()` on an effect tree now
+  disposes every `ParticleSystem` in it and removes it from its renderer. A system that disposes
+  itself (`dispose()`, or `autoDestroy` when it finishes) still leaves the systems of its child
+  emitters playing until they finish.
+- **`depthTest: false` had no effect.** It was stored, batched and saved, but never reached the
+  material. It now draws particles over all geometry (Unity's `ZTest Always`) in every render mode.
+- **A mesh batch leaked a material when its env atlas finished loading.** The rebuild now disposes
+  the material it replaces, and does nothing when the batch was disposed before the atlas loaded.
+- **`QuarksLoader` joined a relative base url twice.** `load('fx/hit.json')` and
+  `loadFromJSON(json, 'fx/')` loaded textures from `fx/fx/...`, and from `fx/fx/fx/...` when the
+  same document was loaded again.
+- **Trails picked the wrong sprite-sheet cell.** The cell column was counted with `vTileCount`
+  and fractional frames were not rounded down, so a sheet with more columns than rows, or a
+  `FrameOverLife` curve, showed the wrong cell or a slice across two. Trails now pick the same cell
+  as billboards.
+- **`OrbitOverLife.clone()` dropped the axis**, so a cloned system orbited about Y.
+- **`loadFromJSON` after `resolveResources()` joined the base url twice.** The copy
+  `loadFromJSON` takes of the document lost the mark that its image urls were already resolved,
+  so a document prepared with `resolveResources(json, 'fx/')` and then loaded with the same base
+  got `fx/fx/tex/a.png`. The copy keeps the mark.
+
+### Tests
+
+- Trails: the texture modes and scale, the live tip's distance, minimum vertex distance, lifetime
+  (alive and dead), the end-of-life boundary, `clearTrails()` and the teleport, the history
+  buffers' reuse, the batch's vertex sizing, tessellation at tension 1, the trail `tint`, the
+  trail settings through `serializeEffect` and `QuarksLoader`, the `sideAxis` JSON validation,
+  and `WidthOverLength` on fractional and zero lengths.
+- **Coverage is enforced.** The package thresholds were never checked, because `npm test` ran
+  without coverage, and the root run ignored each package's file list. `npm run test:coverage` (in
+  CI and `npm run check`) now counts every source file and fails under a floor per package, set in
+  the root `jest.config.json` one point under today's coverage and raised as tests are added. The
+  floors show where tests are thinnest: the editor's core sits at 14%, quarks.core at 55%.
+- **Serialisation contract.** Every behavior, emitter shape, value and colour generator, and every
+  `ParticleSystem` setting in each render mode, must survive `toJSON` → `fromJSON`, `clone()` and
+  `QuarksLoader` unchanged, and a clone must share no mutable state with its original. A new
+  behavior or shape type fails the test until it is added to it.
+- **Frame-rate independence.** Every quarks.core behavior that changes a particle over time reaches
+  the same state after a second at 30, 60, 120 and 144 Hz, through both `update` and `updateAll`.
+  A seeded `ParticleSystem` gives the same particles, finishes within a frame of the same time and
+  pauses the same way at 20 to 240 Hz.
+- **Seeded simulation snapshot.** A seeded system in each render mode (billboard in world and
+  local space, stretched, mesh, trail, beam), with a moving emitter, bursts and behaviors, is
+  stepped on uneven frames and its particles (trail history included), bounds and JSON are compared
+  with a stored snapshot; loaded back with `fromJSON`, it must write the same JSON and play the same.
+  It was recorded before `ParticleSystem.ts` was split and pins the simulation while the rest of the
+  split follows.
+- Loader: a document `resolveResources()` prepared loads with the same base once; a save next to
+  the source writes the source url, through a custom resolver too.
+
+### Docs
+
+- **README** describes the WebGPU path as it is: native WGSL shaders, nothing transpiled or
+  fetched at run time. The feature list names beams, the texture effects and the scene-integration
+  options; the Unity-style snippet imports from `babylon.quarks` (the npm package `quarks.core` is
+  the upstream three.quarks core, not this monorepo's fork of it); the demo count is current. `ROADMAP.md` and
+  `docs/SHURIKEN_PARITY.md` match what shipped in 0.24 to 0.27.
+- **Three new demos** in the examples app: pooled one-shot hits (`EffectPool`,
+  `QuarksUtil.getDuration`, `emissionMultiplier`), renderer options side by side (`sortMode`,
+  `alignToDirection`, `minParticleSize` / `maxParticleSize`, `scalingMode`), and surface trails with
+  a mesh second UV set (`MeshSurfaceEmitter`, the trail flags, `tessellation`, `curveTension`,
+  `instancingUVs2` with a map on UV channel 1 through a gradient map).
+
+### Internal
+
+- **`npm run validate:wgsl` runs in CI** (job `wgsl`), on Chromium's software WebGPU adapter, so a
+  WGSL variant that stops compiling fails the pull request. The script compiles the variants in
+  batches instead of one round trip each, which brings a run from ten minutes to about fifteen
+  seconds; it reports a missing WebGPU adapter or an empty run in plain words instead of a stack
+  trace, fails when the device is lost mid-run (a lost device compiles nothing and reports no
+  errors), and gives up after five minutes instead of holding the job.
+- **The demo smoke in CI opened the wrong pages.** The examples are built under `/<repository>/`
+  on GitHub Actions, and the preview server answers a request outside that path with a 404 page
+  that loads without an error, so `check:demos` had been passing on 404 pages there. Both
+  `check:demos` and `validate:wgsl` now ask the server for its base path
+  (`scripts/examplesBase.mjs`), and the smoke fails a page the viewer never comes up on.
+- **`batchKey.ts`** holds the batch key: `storedBatchSettings` reduces a system's settings to the
+  canonical form a batch stores, `shaderKeyEqual` and `liveParamsEqual` compare the two groups
+  and `batchSettingsEqual` both. `BatchedRenderer.updateSystem` writes live parameters through
+  `VFXBatch.applyLiveSettings`. `VFXBatch` reads the texture layouts off its settings on every
+  bind, and each batch writes its live uniforms from one place (`writeLiveUniforms`), on build and
+  on a change.
+- **The stretched-billboard shaders no longer declare a `speedFactor` uniform.** The speed factor
+  is baked into the velocity attribute on the CPU, so the uniform, which was set from
+  `softNearFade`, was never read. The per-frame sync and its tests are gone with it.
+- **`integrate.ts`** (`src/system/`) holds the passes of a simulation step after emission: the
+  snapshot the renderer extrapolates from, the behavior steps, the sprite path's one pass over
+  the store (newborn collapse, motion, ageing, bounds and removal) and the trail path's passes
+  (collapse, motion, history, removal), as plain functions over the store and the particle array.
+  `ParticleSystem.stepOnce` calls them in order and is 60 lines; the file is now about 1700
+  lines, from 3641 before phase 3c. The hot loops are the same code and run the same within
+  benchmark noise (a local 88k-particle benchmark: 11.5, 11.6 and 10.4 ms before against 11.6,
+  9.2 and 10.1 ms after, in interleaved runs).
+- **`EmissionController` and `ParticleSpawner`** (`src/system/`) take emission (rates, bursts and
+  their waves, emission along the emitter's path, the system-level generator memory) and the
+  making of newborn particles (pool growth, start values, placement, behavior initialisation) out
+  of `ParticleSystem`, which goes from about 2460 to 1950 lines. The hot path is unchanged within
+  measurement noise (a 20-system, 88k-particle Node benchmark: 7.5 ms before, 7.9 ms after, a
+  spawn-heavy one 10.3 and 10.3 ms, with a run-to-run spread of about 1 ms).
+- **`SimulationClock`** (`src/system/SimulationClock.ts`) holds the fixed-step accumulator, the
+  rounding rule that keeps the residual near zero, the start delay and the catch-up debt of a
+  culled system, as pure numbers with their own tests. `ParticleSystem.update` is a client of it.
+- **One table of `ParticleSystem` settings** (`src/system/settingsSchema.ts`) gives each plain and
+  generator setting its default, its JSON form and how it is copied. `toJSON`, `fromJSON` and
+  `clone` are built from it, and a test fails when a constructor parameter is in neither the table
+  nor the code that handles the meta, the shape or the behaviors.
+- **`ParticleSystem.ts` is being split into modules under `src/system/`.** This first part moves
+  out the parameter and JSON types (`types.ts`), reading and writing JSON
+  (`serialization.ts`), culling bounds (`BoundsTracker.ts`), event listeners
+  (`EventDispatcher.ts`), the behavior fusion plan (`BehaviorPlan.ts`), reading draw settings from a
+  material (`materialResolve.ts`), default and fallback geometry (`geometry.ts`) and the setting
+  normalisers (`normalize.ts`). The file goes from 3641 to about 2500 lines. The public API and the
+  simulation are unchanged; the types are still exported from the package root. Still to come: one
+  table of settings for the constructor, setters, JSON and `clone`, the simulation clock, emission
+  and spawning, and the integration passes.
+
 ## [0.26.0] — 2026-10-21
 
 ### Changed (breaking)
@@ -104,13 +866,13 @@ renames below.
   unchanged and stays in the fused pass.
 - Texture effects on sprites, meshes and trails, GLSL and WGSL, each saved with the material in the
   effect JSON only when set and batched apart when they differ:
-    - `ParticleSystem.uvScroll` `[u, v]`: scrolls the map in UV units per second on the renderer's clock.
-    - `ParticleSystem.gradientMap`: recolours the map through a ramp texture picked by its red
-      channel; the particle colour still tints it.
-    - `ParticleSystem.erosion` (`ParticleErosion`: mask, softness, edgeWidth, edgeColor, maskScroll):
-      alpha erosion. The particle's alpha decides how much of the shape is left instead of how
-      transparent it is, so a `ColorOverLife` alpha curve dissolves it through a noise mask or wipes
-      it through a gradient one, with an optional glowing edge.
+  - `ParticleSystem.uvScroll` `[u, v]`: scrolls the map in UV units per second on the renderer's clock.
+  - `ParticleSystem.gradientMap`: recolours the map through a ramp texture picked by its red
+    channel; the particle colour still tints it.
+  - `ParticleSystem.erosion` (`ParticleErosion`: mask, softness, edgeWidth, edgeColor, maskScroll):
+    alpha erosion. The particle's alpha decides how much of the shape is left instead of how
+    transparent it is, so a `ColorOverLife` alpha curve dissolves it through a noise mask or wipes
+    it through a gradient one, with an optional glowing edge.
 - `RenderMode.Beam` (6) with `ParticleSystem.beamEnd` (a point or anything with a world position,
   such as a `TransformNode`, read every frame; runtime only): a quad laid from each particle to
   the end and turned about its length to face the camera, U along it, the size as its width. With
@@ -353,7 +1115,6 @@ renames below.
   optional per-axis thickness, moving particles along +Z; a box with no depth is a flat rectangle.
   `EdgeEmitter` (`edge`) emits from a line along X, moving particles along +Y. Both match the
   Unity shapes of the same name.
-
 - Trail settings `uvFromHead`, `colorFromParticle`, `dieWithParticle` and `recordWorldSpace`
   (all optional, off by default) for trails that behave like Unity's: the texture runs from the
   particle back to the tail, the whole trail takes the particle's current color, the trail