babylon.quarks-editor 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -4,6 +4,98 @@ All notable changes to the `babylon.quarks-editor` 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.29.0] — 2026-10-24
+
+### Changed
+
+- **Renderer module** has an "Image processing" switch beside "Apply fog", for
+  `ParticleSystem.applyImageProcessing`.
+
+- **Value fields** offer Random Between Two Curves, with a curve editor for each bound. Switching
+  between Curve and Random Between Two Curves keeps every segment.
+- **Curve modules** (Size, Speed and Limit Speed over Lifetime, Size by Speed, Width over Trail,
+  Texture Sheet frames) have a "Two curves" switch and show both bounds of an imported Random
+  Between Two Curves; an edit used to drop the upper one.
+- **Stop action** in Main and **Ring buffer** (with its loop range) beside Max particles, as
+  Unity's. The editor saves the stop action but does not apply it, so previews replay.
+- **Separate axes** in Limit Speed over Lifetime (with its Space), Size over Lifetime and Size by
+  Speed: a curve for each of X, Y and Z, as Unity's Separate Axes.
+- **Scaling mode** offers Local (the default), Hierarchy and Shape, as Unity's, for world- and
+  local-space systems alike.
+- **Shape module:** a cone's Emit from (Base, Volume) and Length, shown for Volume only, and a
+  grid's Sampling (Random, Sequential).
+
+## [0.28.0] — 2026-10-23
+
+### Breaking
+
+- **Texture callbacks are typed.** `resolveTexture` returns `Texture | null | undefined` instead
+  of `unknown` (on `EffectEditorHost`, `QuarksEffectEditor.Show`, `EffectEditor`,
+  `RendererModule` and `createDefaultEffect`). `TextureSelect`'s `loadTexture` and `onChange` use
+  `Texture`, and `RendererMaterialPatch` types `texture` as `Texture | null` and
+  `reflectionAtlas` as `BaseTexture | null`. A resolver that returns a Babylon `Texture` needs no
+  change; one typed to return something else must now return a `Texture`.
+- **`ValueField` has two prop shapes.** `CurveValueFieldProps` (the default, `curve` unset or
+  `true`) calls `onChange` with a `ScalarGenerator`; `ConstantValueFieldProps` (`curve: false`)
+  calls it with a `ValueGenerator`. Code that passed `curve={false}` and expected a curve back no
+  longer type-checks.
+
+### Added
+
+- A **Render face** field (Both, Front, Back) for mesh systems, editing the library's new
+  `renderFace`.
+- **`createEditorSession`** and the `EditorSession` interface, in a new
+  `babylon.quarks-editor/session` entry: the scene, camera, gizmos, history, scene entries, assets,
+  prefab mode and project save/load without React. The host passes only the view callbacks it
+  needs; none runs after `dispose()`, which also drops a project load or an import still in
+  flight. `EffectEditorHost` is now a view over a session. The session has its own entry because
+  it builds the viewport (grid, gizmos, markers), which the UI-free `.` entry does not load.
+- **`createEngine`** on `EffectEditorHostProps` (and `Show()`), to draw with a WebGPU or other
+  engine instead of the default WebGL `Engine`. It may return a promise, so a `WebGPUEngine` can
+  finish `initAsync()` first.
+- Exported types that public signatures already used: `AssetLoadProgress`, `EffectAsset`,
+  `AssetDragPayload`, `SceneEntry`, `TimelineRow` (`TimelineGroupRow | TimelineSystemRow`),
+  `AnyGenerator`, `ModuleProps`, `ConstantValueFieldProps` and `CurveValueFieldProps`, and
+  `EditorProject` from `./react`.
+- TSDoc on every public export. `npm run docs:check` now builds the editor's API docs and fails on
+  an undocumented export or a broken link.
+
+### Fixed
+
+- A mesh from geometry without indices (a preset or a loaded GLB) no longer leaves the system
+  with no index buffer: it gets sequential indices, so it draws and exports. A mesh without UVs or
+  normals gets the library's fallback ones instead of keeping the previous mesh's.
+- Randomize Direction's angle no longer offers a curve. The angle is sampled once per particle,
+  so a curve could not apply, and a curve loaded from JSON shows as its starting value.
+- `EffectEditorHost` under React StrictMode, or remounted, no longer lets the first mount's project
+  load fill the live editor with entries from a disposed scene.
+- The transport's play resumes what pause froze and no longer replays effects or bursts that had
+  already finished (it uses the library's new `resume()`, now that `play()` replays a finished
+  system).
+- A node deleted by an undo while selected hands the selection back to its effect's root on the
+  next render. The host only checked when the selection or the session changed, so the inspector
+  and timeline could keep showing the deleted node.
+
+### Internal
+
+- The asset import checks every field it reads from an effect file, with no `any`.
+- The React panels follow the React Compiler's rules (eslint-plugin-react-hooks 7): no ref
+  written during render, and state that follows a prop is adjusted during render instead of in an
+  effect, which saves a render each time.
+- `EffectEditorHost` is split into a session and panel components under `src/react/host/`, and
+  every `as never` cast is gone. The session and the host have their own tests, and the React
+  code has a coverage floor.
+
+## [0.27.1] — 2026-10-23 (not published)
+
+### Changed
+
+- **Peer ranges:** `@babylonjs/core` and `@babylonjs/materials` are `^9.0.0` instead of
+  `>=9.0.0` (no Babylon 10 exists yet, so no install that worked stops working). `babylon.quarks` stays `~0.27.0`: the editor follows the library's minor line, and
+  the release check now enforces it.
+- The `exports` map lists `types` first and exports `./package.json`. The README says the package
+  is ES modules only.
+
 ## [0.27.0] — 2026-10-23
 
 A 0.27.0 dated 2026-10-21 was prepared but never published; its entries are folded in here.

package/README.md

@@ -10,6 +10,9 @@ Shuriken-style effect editor for [babylon.quarks](https://www.npmjs.com/package/
 npm install babylon.quarks-editor babylon.quarks @babylonjs/core @babylonjs/materials react react-dom @heroicons/react @tanstack/react-virtual
 ```
 
+The editor is an ES module package (`import`, not `require`). Its version follows babylon.quarks:
+editor 0.29.x needs babylon.quarks 0.29.x.
+
 ## Usage
 
 The supported embed is the host: it owns the scene, the timeline, undo/redo, playback and the
@@ -66,8 +69,9 @@ The `.` export is UI-free (edit model, serialization, value/shape/gradient helpe
 The editor never loads assets itself — it defers to host-supplied callbacks so it doesn't need
 an opinion on your CDN, asset pipeline, or loader (`@babylonjs/loaders`, your own backend, etc.):
 
-- `resolveTexture(url) => Texture-like` — turns a picked URL or `data:` URI (from "Custom URL…" /
-  "Load from file…" in the Renderer module) into whatever object you assign as `system.texture`.
+- `resolveTexture(url) => Texture | null | undefined` — turns a picked URL or `data:` URI (from
+  "Custom URL…" / "Load from file…" in the Renderer module) into the Babylon `Texture` assigned as
+  `system.texture`. Return `null` or `undefined` to leave the texture unset.
 - `resolveGeometry(file) => Promise<GeometryData>` — turns a picked file (from "Load from file…"
   in the Mesh render mode's geometry dropdown) into vertex buffers: `{positions, indices?, uvs?,
 uvs2?, normals?}` (typed arrays or plain number arrays; `uvs2` is the second UV set textures on
@@ -80,10 +84,10 @@ uvs2?, normals?}[]` — preset lists shown alongside "Custom URL…" / "Load fro
 host" bugs:
 
 - `QuarksEffectEditor.Show(...)` / `<EffectEditorHost>` call your callbacks with the live
-  `Scene` as a second argument: `resolveTexture: (url, scene) => unknown`,
+  `Scene` as a second argument: `resolveTexture: (url, scene) => Texture | null | undefined`,
   `resolveGeometry: (file, scene) => Promise<GeometryData>`.
 - The lower-level `<EffectEditor>` (no Host wrapper) does **not** pass a scene:
-  `resolveTexture: (url) => unknown`, `resolveGeometry: (file) => Promise<GeometryData>`. If you
+  `resolveTexture: (url) => Texture | null | undefined`, `resolveGeometry: (file) => Promise<GeometryData>`. If you
   copy a `Show()`-style resolver that reads its `scene` parameter into a raw `<EffectEditor>`,
   `scene` is `undefined` and your resolver throws.
 
@@ -112,6 +116,29 @@ resolveGeometry: async (file, scene) => {
 },
 ```
 
+## Custom engines and headless use
+
+`<EffectEditorHost>` creates a WebGL `Engine` on its canvas. Pass `createEngine` to build another
+engine on that canvas instead, or a `NullEngine` in tests. It may return a promise:
+
+```ts
+createEngine: async (canvas) => {
+    const engine = new WebGPUEngine(canvas);
+    await engine.initAsync();
+    return engine;
+},
+```
+
+Build a new engine on every call: the host disposes it when it unmounts, and React StrictMode
+mounts the host twice.
+
+Everything the host does besides drawing its panels lives in an `EditorSession`, from the
+`babylon.quarks-editor/session` entry: `createEditorSession({engine, playback, view, ...})`. The
+session owns the scene, camera, gizmos, history, scene entries, assets, prefab mode and project
+save/load, and reports changes through the `view` callbacks you pass. Use it to drive the editor
+from your own UI, or to script and test editing without React. It builds the viewport (grid,
+gizmos, markers), which is why it is not part of the lighter UI-free `.` entry.
+
 ## License
 
 MIT

package/dist/core/assetTree.d.ts

@@ -19,11 +19,16 @@ export declare function folderChildren(tree: AssetTreeNode[], path: string): Ass
 /** Assets whose name or path contains `query`, across every folder, sorted by name. */
 export declare function searchAssets(assets: EffectAsset[], query: string): EffectAsset[];
 export declare const ASSET_DRAG_MIME = "application/x-quarks-asset-drop";
+/** What is dragged out of the Assets panel: one asset, or every asset under a folder. */
 export type AssetDragPayload = {
+    /** One asset. */
     kind: 'asset';
+    /** The asset's id. */
     id: number;
 } | {
+    /** A folder. */
     kind: 'folder';
+    /** The folder's path; every asset under it is dragged. */
     path: string;
 };
 export declare function writeAssetDrag(dataTransfer: DataTransfer, payload: AssetDragPayload): void;

package/dist/core/assets.d.ts

@@ -4,7 +4,9 @@
  * fresh, independent copy (see `instantiateSceneEntry`).
  */
 export interface EffectAsset {
+    /** The asset's id in this session; scene entries made from it keep it. */
     id: number;
+    /** The asset's display name, its file name without `.json`. */
     name: string;
     /** Relative path inside the imported folder (preserves subfolders). */
     path: string;
@@ -13,10 +15,15 @@ export interface EffectAsset {
     /** Texture/geometry files the effect references that were not among the imported files. */
     missingFiles: string[];
 }
+/** How far an asset import got. */
 export interface AssetLoadProgress {
+    /** JSON files read so far. */
     done: number;
+    /** JSON files in the import. */
     total: number;
+    /** Effects found so far. */
     loaded: number;
+    /** Files that could not be read. */
     failed: number;
 }
 export declare function relativePathOf(file: File): string;

package/dist/core/assets.js

@@ -42,6 +42,9 @@ function readAsDataUrl(file) {
         reader.readAsDataURL(file);
     });
 }
+function isRecord(value) {
+    return value !== null && typeof value === 'object';
+}
 /** True for a Quarks effect envelope with at least one particle emitter. */
 export function isEffectJson(json) {
     const object = json?.object;
@@ -206,11 +209,11 @@ export function assetIconUrl(asset) {
     if (cached !== undefined) {
         return cached;
     }
-    const json = asset.json;
+    const json = isRecord(asset.json) ? asset.json : {};
     const findMaterial = (node) => {
-        if (!node || typeof node !== 'object')
+        if (!isRecord(node))
             return undefined;
-        if (node.type === 'ParticleEmitter' && node.ps?.material)
+        if (node.type === 'ParticleEmitter' && isRecord(node.ps) && node.ps.material)
             return node.ps.material;
         for (const child of Array.isArray(node.children) ? node.children : []) {
             const found = findMaterial(child);
@@ -219,10 +222,11 @@ export function assetIconUrl(asset) {
         }
         return undefined;
     };
-    const byUuid = (list, uuid) => (Array.isArray(list) ? list : []).find((item) => item?.uuid === uuid);
-    const material = byUuid(json?.materials, findMaterial(json?.object));
-    const texture = byUuid(json?.textures, material?.map ?? material?.texture);
-    const image = byUuid(json?.images, texture?.image) ?? (Array.isArray(json?.images) ? json.images[0] : undefined);
+    const byUuid = (list, uuid) => (Array.isArray(list) ? list : []).find((item) => isRecord(item) && item.uuid === uuid);
+    const material = byUuid(json.materials, findMaterial(json.object));
+    const texture = byUuid(json.textures, material?.map ?? material?.texture);
+    const firstImage = Array.isArray(json.images) ? json.images[0] : undefined;
+    const image = byUuid(json.images, texture?.image) ?? (isRecord(firstImage) ? firstImage : undefined);
     const url = typeof image?.url === 'string' && image.url ? image.url : null;
     iconCache.set(asset, url);
     return url;

package/dist/core/binding.d.ts

@@ -1,6 +1,7 @@
 import type { TransformNode } from '@babylonjs/core/Meshes/transformNode.js';
 import type { ParticleSystem } from 'babylon.quarks';
 import type { EffectTreeNode } from './effectTree.js';
+/** Called after every change made through an {@link EffectBinding}. */
 export type EditorListener = () => void;
 /**
  * Headless edit-model over a live ParticleSystem: mutate through apply() so every
@@ -20,11 +21,18 @@ export declare class EffectBinding {
     constructor(system: ParticleSystem, subSystems?: ParticleSystem[], root?: TransformNode);
     /** Editor hierarchy tree (groups + emitters) rooted at this effect's scene root. */
     getTree(): EffectTreeNode;
+    /** Calls `listener` after every change; returns the call that stops it. */
     subscribe(listener: EditorListener): () => void;
     /** Monotonic change counter, usable as a React external-store snapshot. */
     getRevision(): number;
+    /**
+     * Changes the main system through `mutate`: takes an undo snapshot first, then notifies
+     * subscribers. Every inspector edit goes through here.
+     */
     apply(mutate: (system: ParticleSystem) => void): void;
+    /** Adds a system to the effect's sub systems. */
     addSubSystem(sub: ParticleSystem): void;
+    /** Removes a system from the effect's sub systems; a system it does not have is ignored. */
     removeSubSystem(sub: ParticleSystem): void;
     /**
      * Swaps which system is "main" — used when the current `system` is about to be removed
@@ -39,6 +47,7 @@ export declare class EffectBinding {
      */
     markChanged(): void;
     private notify;
+    /** Restarts every system of the effect from time 0. */
     restart(): void;
     /**
      * Serializes the effect into the Quarks JSON envelope understood by QuarksLoader,

package/dist/core/binding.js

@@ -17,6 +17,7 @@ export class EffectBinding {
     getTree() {
         return buildEffectTree(this.root);
     }
+    /** Calls `listener` after every change; returns the call that stops it. */
     subscribe(listener) {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
@@ -25,15 +26,21 @@ export class EffectBinding {
     getRevision() {
         return this.revision;
     }
+    /**
+     * Changes the main system through `mutate`: takes an undo snapshot first, then notifies
+     * subscribers. Every inspector edit goes through here.
+     */
     apply(mutate) {
         this.onBeforeChange?.();
         mutate(this.system);
         this.notify();
     }
+    /** Adds a system to the effect's sub systems. */
     addSubSystem(sub) {
         this.subSystems.push(sub);
         this.notify();
     }
+    /** Removes a system from the effect's sub systems; a system it does not have is ignored. */
     removeSubSystem(sub) {
         const index = this.subSystems.indexOf(sub);
         if (index >= 0) {
@@ -69,6 +76,7 @@ export class EffectBinding {
             listener();
         }
     }
+    /** Restarts every system of the effect from time 0. */
     restart() {
         // onlyUsedByOther systems skip self-emission in update(); play() only unpauses sim.
         for (const system of [this.system, ...this.subSystems]) {

package/dist/core/collision.d.ts

@@ -8,7 +8,11 @@ import { Vector3 } from 'babylon.quarks';
  */
 export declare class GroundPlaneResolver {
     y: number;
+    /** @param y - Height of the ground plane. */
     constructor(y?: number);
+    /**
+     * True when `position` is at or below the plane, with the plane's normal written to `normal`.
+     */
     resolve(position: Vector3, normal: Vector3): boolean;
 }
 /**

package/dist/core/collision.js

@@ -7,9 +7,13 @@ import { getPhysicsResolver, setPhysicsResolver } from 'babylon.quarks';
  * which is exactly what ApplyCollision.update reflects the velocity against.
  */
 export class GroundPlaneResolver {
+    /** @param y - Height of the ground plane. */
     constructor(y = 0) {
         this.y = y;
     }
+    /**
+     * True when `position` is at or below the plane, with the plane's normal written to `normal`.
+     */
     resolve(position, normal) {
         if (position.y <= this.y) {
             normal.set(0, 1, 0);

package/dist/core/colors.d.ts

@@ -2,28 +2,44 @@ import type { Behavior } from 'babylon.quarks';
 import { ColorOverLife, Gradient, Vector4 } from 'babylon.quarks';
 /** One RGBA stop of the editable gradient (all channels 0..1, pos 0..1). */
 export interface GradientStop {
+    /** Where the stop sits over the particle's life, 0..1. */
     pos: number;
+    /** Red, 0..1. */
     r: number;
+    /** Green, 0..1. */
     g: number;
+    /** Blue, 0..1. */
     b: number;
+    /** Alpha, 0..1. */
     a: number;
 }
+/** The gradient a new Color over Lifetime starts with: warm yellow fading out through red. */
 export declare const DEFAULT_GRADIENT_STOPS: GradientStop[];
+/** A quarks gradient through `stops`, sorted by position; colour and alpha share the stops. */
 export declare function buildGradient(stops: GradientStop[]): Gradient;
+/** A Color over Lifetime behavior through `stops`. */
 export declare function buildColorOverLife(stops: GradientStop[]): ColorOverLife;
+/** An RGBA colour as a quarks `Vector4`. */
 export declare function rgbaToVector4(stop: {
     r: number;
     g: number;
     b: number;
     a: number;
 }): Vector4;
+/** A stop's colour as CSS `rgba()`. */
 export declare function stopToCss(stop: GradientStop): string;
+/** The stops as a left-to-right CSS `linear-gradient`, for a gradient preview. */
 export declare function stopsToCssGradient(stops: GradientStop[]): string;
+/** A `#rrggbb` colour as channels 0..1. */
 export declare function hexToRgb(hex: string): {
+    /** Red, 0..1. */
     r: number;
+    /** Green, 0..1. */
     g: number;
+    /** Blue, 0..1. */
     b: number;
 };
+/** Channels 0..1, clamped, as a `#rrggbb` colour. */
 export declare function rgbToHex(r: number, g: number, b: number): string;
 /** Reads RGBA stops back from a Gradient (union of color/alpha key positions). */
 export declare function readGradientStops(gradient: Gradient): GradientStop[];

package/dist/core/colors.js

@@ -1,27 +1,34 @@
 import { ColorOverLife, Gradient, Vector3, Vector4 } from 'babylon.quarks';
+/** The gradient a new Color over Lifetime starts with: warm yellow fading out through red. */
 export const DEFAULT_GRADIENT_STOPS = [
     { pos: 0, r: 1, g: 0.85, b: 0.4, a: 1 },
     { pos: 1, r: 1, g: 0.25, b: 0.05, a: 0 },
 ];
+/** A quarks gradient through `stops`, sorted by position; colour and alpha share the stops. */
 export function buildGradient(stops) {
     const sorted = [...stops].sort((a, b) => a.pos - b.pos);
     return new Gradient(sorted.map((s) => [new Vector3(s.r, s.g, s.b), s.pos]), sorted.map((s) => [s.a, s.pos]));
 }
+/** A Color over Lifetime behavior through `stops`. */
 export function buildColorOverLife(stops) {
     return new ColorOverLife(buildGradient(stops));
 }
+/** An RGBA colour as a quarks `Vector4`. */
 export function rgbaToVector4(stop) {
     return new Vector4(stop.r, stop.g, stop.b, stop.a);
 }
+/** A stop's colour as CSS `rgba()`. */
 export function stopToCss(stop) {
     const c = (v) => Math.round(v * 255);
     return `rgba(${c(stop.r)}, ${c(stop.g)}, ${c(stop.b)}, ${stop.a.toFixed(2)})`;
 }
+/** The stops as a left-to-right CSS `linear-gradient`, for a gradient preview. */
 export function stopsToCssGradient(stops) {
     const sorted = [...stops].sort((a, b) => a.pos - b.pos);
     const parts = sorted.map((s) => `${stopToCss(s)} ${(s.pos * 100).toFixed(1)}%`);
     return `linear-gradient(90deg, ${parts.join(', ')})`;
 }
+/** A `#rrggbb` colour as channels 0..1. */
 export function hexToRgb(hex) {
     const value = hex.replace('#', '');
     return {
@@ -30,6 +37,7 @@ export function hexToRgb(hex) {
         b: parseInt(value.slice(4, 6), 16) / 255,
     };
 }
+/** Channels 0..1, clamped, as a `#rrggbb` colour. */
 export function rgbToHex(r, g, b) {
     const c = (v) => Math.round(Math.min(1, Math.max(0, v)) * 255)
         .toString(16)

package/dist/core/defaultEffect.d.ts

@@ -1,11 +1,12 @@
+import type { Texture } from '@babylonjs/core/Materials/Textures/texture.js';
 import type { Scene } from '@babylonjs/core/scene.js';
 import { ParticleSystem } from 'babylon.quarks';
 import { type SceneEntry } from './sceneEntries.js';
 export interface CreateSceneDefaultOptions {
-    resolveTexture?: (url: string, scene: Scene) => unknown;
+    resolveTexture?: (url: string, scene: Scene) => Texture | null | undefined;
     textureUrl?: string;
 }
 /** Creates a simple cone burst preset for new editor effects. */
-export declare function createDefaultEffect(scene: Scene, resolveTexture?: (url: string, scene: Scene) => unknown, textureUrl?: string): ParticleSystem;
+export declare function createDefaultEffect(scene: Scene, resolveTexture?: (url: string, scene: Scene) => Texture | null | undefined, textureUrl?: string): ParticleSystem;
 /** Creates a preset effect as a new scene entry (systems not registered with the renderer yet). */
 export declare function createSceneDefaultEntry(scene: Scene, existing: SceneEntry[], options?: CreateSceneDefaultOptions): SceneEntry;

package/dist/core/defaultEffect.js

@@ -15,10 +15,12 @@ export function createDefaultEffect(scene, resolveTexture, textureUrl) {
         emissionOverTime: new ConstantValue(80),
         shape: new ConeEmitter({ radius: 0.3, angle: 0.25 }),
         renderMode: RenderMode.BillBoard,
-        texture: (textureUrl && resolveTexture ? resolveTexture(textureUrl, scene) : undefined),
+        texture: textureUrl && resolveTexture ? resolveTexture(textureUrl, scene) : undefined,
         transparent: true,
         blendMode: 1,
     });
+    // The editor previews over and over; the stop action is saved, not applied.
+    system.ignoreStopAction = true;
     system.addBehavior(new ColorOverLife(buildGradient(DEFAULT_GRADIENT_STOPS)));
     system.emitter.rotation.x = -Math.PI / 2;
     return system;