babylon.quarks-editor 0.26.0 → 0.28.0

package/CHANGELOG.md

@@ -4,6 +4,140 @@ 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.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.
+
+### Added
+
+- Main module: "Warm-up time", shown while Prewarm is on, the seconds of the cycle simulated
+  before the first frame (`prewarmTime`; 0 warms up a whole cycle).
+- **The Renderer module reaches the 0.25–0.26 texture features.** Map layout (UV channel,
+  tiling, offset, scroll), Flip, a Gradient map section (ramp and channel), an Erosion section
+  (mask with its own layout, softness, edge width and colour) and a UV distortion section (noise
+  with its layout, strength). The ramp, mask and noise are picked the way the texture is: from
+  the host's presets, a URL or a file.
+- Renderer: a swept trail's side axis. A host geometry
+  (`GeometryOption`, `resolveGeometry`) may carry a second UV set, `uvs2`, which mesh particles
+  read on UV channel 1; the demo's glTF loader passes `TEXCOORD_1` through.
+- Main: Scaling mode for world-space systems (shape only, or the hierarchy's motion too).
+- Texture Sheet Animation: time mode (lifetime or FPS), FPS, loop or hold, random frame, cycles,
+  frame count and a random start frame.
+- Attractor module: a point gravity (`GravityForce`) with its centre and strength.
+- Emitter shape wireframes for the Box and Edge shapes: the box outline with its +Z emit
+  direction, and the edge line with its +Y emit direction.
+- `TextureSelect` and `TextureUVField` components, exported from `babylon.quarks-editor/react`.
+- Renderer module, trails: "Tessellation" and "Curve tension".
+
+### Changed
+
+- Renderer, trails: "Texture mode" (stretch, distribute per segment, tile, repeat per segment),
+  "Texture scale", "Min vertex distance" and "Trail time", each left unset at its default so the
+  JSON stays sparse. The "Head width scale" row is gone: it wrote a `headWidthScale` field no
+  runtime read (the head's width comes from the Width over Trail module).
+- **`TimelinePanelProps` and `TransportBarProps` take `RefObject<HTMLElement | null>` refs**, the
+  type `useRef<HTMLElement>(null)` returns, now that the editor compiles with `strict`. Code that
+  passed the old type still compiles.
+
+### Fixed
+
+- An imported effect whose images were inlined from the picked files is saved with those inlined
+  images; `serializeEffect` writes a texture's source path only while the texture still shows the
+  image it was loaded with, and an inlined image has no path. A test covers import → scene → save.
+- **Saving lost mesh nodes and texture settings.** The editor now saves through `serializeEffect`:
+  mesh nodes keep their geometry (so mesh surface emitters still emit after a save and reload),
+  and textures keep their wrap, sampling, repeat, offset and rotation. Textures with no url a file
+  can point at are reported instead of written as an empty entry.
+- The yellow hover ring stayed on the ground after the hovered effect was removed from the scene.
+- **Node ESM and webpack 5 could not import the package.** `dist` was compiled with relative and
+  `@babylonjs` deep imports that had no file extension. Every import now ends in `.js`.
+- The `babylon.quarks` peer range was `>=0.17.0`, but the editor needs current APIs (beam mode,
+  rim fade, culling and sort settings). It is now `~0.27.0`.
+
+### Internal
+
+- Jest tests now cover the whole editor core (`src/core`): systems, material, timeline, scrub,
+  playback and transport, groups, collision, effect tree, assets and asset tree, scene entries,
+  gallery layout, playback, markers and picker, emitter shape wireframes, texture export and the
+  IndexedDB project store. The coverage threshold for the editor is raised to match.
+- Editor tests resolve `babylon.quarks` to its sources, so they pick up library changes made in
+  the same branch without rebuilding it.
+- React modules are tested in jsdom through the DOM, and the whole `EffectEditor` is mounted in
+  every render mode.
+- The README leads with `QuarksEffectEditor.Show`, lists every peer and every module, and the
+  `EffectEditor` snippet carries all of its props.
+
 ## [0.26.0] — 2026-10-21
 
 ### Added

package/README.md

@@ -7,11 +7,33 @@ Shuriken-style effect editor for [babylon.quarks](https://www.npmjs.com/package/
 ## Install
 
 ```bash
-npm install babylon.quarks-editor babylon.quarks @babylonjs/core react @heroicons/react @tanstack/react-virtual
+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.28.x needs babylon.quarks 0.28.x.
+
 ## Usage
 
+The supported embed is the host: it owns the scene, the timeline, undo/redo, playback and the
+module inspector, and mounts into any element.
+
+```ts
+import {Texture} from '@babylonjs/core/Materials/Textures/texture';
+import {QuarksEffectEditor} from 'babylon.quarks-editor/react';
+
+const editor = QuarksEffectEditor.Show({
+    hostElement: document.getElementById('editor')!,
+    effectJson, // optional: a Quarks JSON export to open; a default effect otherwise
+    textureOptions: [{label: 'Glow', url: '/textures/glow.png'}],
+    resolveTexture: (url, scene) => new Texture(url, scene),
+    onSave: (json) => save(json), // the effect as Quarks JSON, round-trips through QuarksLoader
+});
+editor.dispose();
+```
+
+The module inspector on its own, for a host that already has a scene and a selection:
+
 ```tsx
 import {EffectBinding, EffectHistory} from 'babylon.quarks-editor';
 import {EffectEditor} from 'babylon.quarks-editor/react';
@@ -20,13 +42,25 @@ const binding = new EffectBinding(particleSystem); // your babylon.quarks Partic
 const history = new EffectHistory();
 history.attach(binding);
 
-<EffectEditor binding={binding} />;
+<EffectEditor
+    binding={binding}
+    selectedSystem={binding.system}
+    gizmoTargetNode={binding.system.emitter}
+    gizmoTargetLabel={binding.system.emitter.name}
+/>;
 
 // Serialize to Quarks JSON (round-trips through QuarksLoader):
 const json = binding.exportJSON('MyEffect');
 ```
 
-Modules: Main, Emission (bursts), Shape (7 emitter types), Speed/Limit Speed/Force/Rotation over Lifetime, Gravity, Color over Lifetime (gradient), Size over Lifetime (curve), Noise, Sub Emitters, Texture Sheet Animation, Renderer. Multi-system hierarchy with add/remove/rename, undo/redo via `EffectHistory`.
+Modules, in Unity's order: Main, Emission (rate over time and distance, bursts), Shape (cone,
+sphere, hemisphere, circle, donut, rectangle, grid, box, edge, mesh surface, point), Randomize
+Direction, Velocity / Speed / Limit Speed / Force over Lifetime, Inherit Velocity, Gravity,
+Attractor, Orbit over Lifetime, Color over Lifetime and by Speed, Size over Lifetime and by Speed,
+Rotation over Lifetime (2D and 3D) and by Speed, Noise, Turbulence, Collision, Width over Trail,
+Sub Emitters, Texture Sheet Animation, Sequences, Renderer (render modes incl. trail, mesh and
+beam; material, texture layout, flip, gradient map, erosion, UV distortion, soft particles, sorting).
+Multi-system hierarchy with add/remove/rename, undo/redo via `EffectHistory`.
 
 The `.` export is UI-free (edit model, serialization, value/shape/gradient helpers) — usable headless. The `./react` export ships the components; React is a peer dependency, so the same UI can mount in a standalone page or inside a [BabylonJS Editor](https://github.com/BabylonJS/Editor) plugin.
 
@@ -35,22 +69,25 @@ 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?,
-normals?}` (typed arrays or plain number arrays).
+uvs2?, normals?}` (typed arrays or plain number arrays; `uvs2` is the second UV set textures on
+  UV channel 1 read).
 - `textureOptions?: {label, url}[]` / `geometryOptions?: {label, positions, indices?, uvs?,
-normals?}[]` — preset lists shown alongside "Custom URL…" / "Load from file…".
+uvs2?, normals?}[]` — preset lists shown alongside "Custom URL…" / "Load from file…". The texture
+  presets also serve the gradient map's ramp, the erosion mask and the distortion noise.
 
 **Signature differs by entry point** — a common source of "works in the demo, throws in my
 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.
 
@@ -79,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/assetDragSession.d.ts

@@ -1,4 +1,4 @@
-import type { AssetDragPayload } from './assetTree';
+import type { AssetDragPayload } from './assetTree.js';
 /** Stores the current asset drag payload for viewport preview (getData is drop-only in most browsers). */
 export declare function setAssetDragSession(payload: AssetDragPayload | null): void;
 export declare function getAssetDragSession(): AssetDragPayload | null;

package/dist/core/assetTree.d.ts

@@ -1,4 +1,4 @@
-import type { EffectAsset } from './assets';
+import type { EffectAsset } from './assets.js';
 export interface AssetTreeFolder {
     kind: 'folder';
     name: string;
@@ -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';
+import type { TransformNode } from '@babylonjs/core/Meshes/transformNode.js';
 import type { ParticleSystem } from 'babylon.quarks';
-import type { EffectTreeNode } from './effectTree';
+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

@@ -1,4 +1,4 @@
-import { buildEffectTree, serializeEffectTree } from './effectTree';
+import { buildEffectTree, serializeEffectTree } from './effectTree.js';
 /**
  * Headless edit-model over a live ParticleSystem: mutate through apply() so every
  * change notifies subscribers (React UI, save indicators, hosts like BabylonJS Editor).
@@ -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 { Scene } from '@babylonjs/core/scene';
+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';
+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

@@ -1,7 +1,7 @@
-import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode.js';
 import { ColorOverLife, ConeEmitter, ConstantColor, ConstantValue, IntervalValue, ParticleSystem, RenderMode, Vector4, } from 'babylon.quarks';
-import { DEFAULT_GRADIENT_STOPS, buildGradient } from './colors';
-import { uniqueEntryName } from './sceneEntries';
+import { DEFAULT_GRADIENT_STOPS, buildGradient } from './colors.js';
+import { uniqueEntryName } from './sceneEntries.js';
 /** Creates a simple cone burst preset for new editor effects. */
 export function createDefaultEffect(scene, resolveTexture, textureUrl) {
     const system = new ParticleSystem({
@@ -15,7 +15,7 @@ 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,
     });

package/dist/core/editorScene.d.ts

@@ -1,4 +1,4 @@
-import type { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import type { TransformNode } from '@babylonjs/core/Meshes/transformNode.js';
 /** Marks meshes/nodes created only for editor interaction or overlays (not part of the effect). */
 export declare const EDITOR_SCENE_NODE_METADATA: {
     quarksEditorSceneNode: true;