babylon.quarks-editor 0.17.7

package/dist/core/values.js

@@ -0,0 +1,81 @@
+import { Bezier, ConstantValue, IntervalValue, PiecewiseBezier } from 'babylon.quarks';
+export function readScalar(generator) {
+    const state = { mode: 'constant', value: 1, min: 0.5, max: 1.5, curve: [0, 1, 1, 0] };
+    if (generator instanceof ConstantValue) {
+        state.mode = 'constant';
+        state.value = generator.value;
+        state.min = generator.value * 0.5;
+        state.max = generator.value * 1.5;
+    }
+    else if (generator instanceof IntervalValue) {
+        state.mode = 'random';
+        state.min = generator.a;
+        state.max = generator.b;
+        state.value = (generator.a + generator.b) / 2;
+    }
+    else if (generator instanceof PiecewiseBezier) {
+        state.mode = 'curve';
+        const first = generator.functions[0]?.[0];
+        if (first) {
+            state.curve = [first.p[0], first.p[1], first.p[2], first.p[3]];
+            state.value = first.p[0];
+        }
+    }
+    return state;
+}
+export function buildScalar(state) {
+    switch (state.mode) {
+        case 'constant':
+            return new ConstantValue(state.value);
+        case 'random':
+            return new IntervalValue(Math.min(state.min, state.max), Math.max(state.min, state.max));
+        case 'curve':
+            return new PiecewiseBezier([[new Bezier(...state.curve), 0]]);
+    }
+}
+/** Reads pieces from a PiecewiseBezier (or synthesizes one segment for other generators). */
+export function readPieces(generator) {
+    if (generator instanceof PiecewiseBezier && generator.functions.length > 0) {
+        return generator.functions.map(([bezier, start]) => ({
+            start,
+            p: [bezier.p[0], bezier.p[1], bezier.p[2], bezier.p[3]],
+        }));
+    }
+    const fallback = readScalar(generator);
+    return [{ start: 0, p: fallback.curve }];
+}
+export function buildCurve(pieces) {
+    const sorted = [...pieces].sort((a, b) => a.start - b.start);
+    return new PiecewiseBezier(sorted.map((piece) => [new Bezier(...piece.p), piece.start]));
+}
+/** Splits the piece containing x into two exact halves using Bezier.split. */
+export function splitPieces(pieces, x) {
+    const sorted = [...pieces].sort((a, b) => a.start - b.start);
+    for (let i = 0; i < sorted.length; i++) {
+        const end = i + 1 < sorted.length ? sorted[i + 1].start : 1;
+        if (x > sorted[i].start + 0.02 && x < end - 0.02) {
+            const t = (x - sorted[i].start) / (end - sorted[i].start);
+            const { left, right } = new Bezier(...sorted[i].p).split(t);
+            sorted.splice(i, 1, { start: sorted[i].start, p: [left.p[0], left.p[1], left.p[2], left.p[3]] }, { start: x, p: [right.p[0], right.p[1], right.p[2], right.p[3]] });
+            return sorted;
+        }
+    }
+    return sorted;
+}
+/** Removes the boundary at pieces[index].start by merging with the previous piece. */
+export function mergePieces(pieces, index) {
+    if (index <= 0 || index >= pieces.length) {
+        return pieces;
+    }
+    const sorted = [...pieces].sort((a, b) => a.start - b.start);
+    const a = sorted[index - 1];
+    const b = sorted[index];
+    sorted.splice(index - 1, 2, { start: a.start, p: [a.p[0], a.p[1], b.p[2], b.p[3]] });
+    return sorted;
+}
+/** Samples a cubic bezier defined by four control values at normalized t. */
+export function sampleCurve(curve, t) {
+    const [p0, p1, p2, p3] = curve;
+    const u = 1 - t;
+    return u * u * u * p0 + 3 * u * u * t * p1 + 3 * u * t * t * p2 + t * t * t * p3;
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { EffectBinding } from './core/binding';
+export type { EditorListener } from './core/binding';
+export { EffectHistory } from './core/history';
+export { createChildSystem } from './core/systems';
+export { buildEffectTree, collectSystems, serializeEffectTree, serializeEffectForest } from './core/effectTree';
+export type { EffectTreeNode } from './core/effectTree';
+export type { ChildSystemOptions } from './core/systems';
+export { readScalar, buildScalar, sampleCurve, readPieces, buildCurve, splitPieces, mergePieces } from './core/values';
+export type { ScalarGenerator, ScalarMode, ScalarValueState, CurvePiece } from './core/values';
+export { DEFAULT_GRADIENT_STOPS, buildGradient, buildColorOverLife, rgbaToVector4, stopToCss, stopsToCssGradient, hexToRgb, rgbToHex, findBehavior, } from './core/colors';
+export type { GradientStop } from './core/colors';
+export { SHAPE_TYPES, SHAPE_PARAM_KEYS, DEFAULT_SHAPE_PARAMS, getShapeType, readShapeParams, createShape, } from './core/shapes';
+export type { ShapeType, ShapeParams } from './core/shapes';
+export { GroundPlaneResolver, ensureGroundResolver } from './core/collision';
+export { ensurePortableTextureUrl } from './core/textureExport';

package/dist/index.js

@@ -0,0 +1,9 @@
+export { EffectBinding } from './core/binding';
+export { EffectHistory } from './core/history';
+export { createChildSystem } from './core/systems';
+export { buildEffectTree, collectSystems, serializeEffectTree, serializeEffectForest } from './core/effectTree';
+export { readScalar, buildScalar, sampleCurve, readPieces, buildCurve, splitPieces, mergePieces } from './core/values';
+export { DEFAULT_GRADIENT_STOPS, buildGradient, buildColorOverLife, rgbaToVector4, stopToCss, stopsToCssGradient, hexToRgb, rgbToHex, findBehavior, } from './core/colors';
+export { SHAPE_TYPES, SHAPE_PARAM_KEYS, DEFAULT_SHAPE_PARAMS, getShapeType, readShapeParams, createShape, } from './core/shapes';
+export { GroundPlaneResolver, ensureGroundResolver } from './core/collision';
+export { ensurePortableTextureUrl } from './core/textureExport';

package/dist/react/CurveEditor.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { CurvePiece } from '../core/values';
+/**
+ * Multi-segment piecewise-bezier curve editor. Drag keys/handles vertically,
+ * drag inner keys horizontally, double-click the curve to add a key, double-click
+ * a key to remove it (Unity-like).
+ */
+export declare function CurveEditor(props: {
+    pieces: CurvePiece[];
+    onChange: (pieces: CurvePiece[]) => void;
+    maxValue?: number;
+}): React.JSX.Element;

package/dist/react/CurveEditor.js

@@ -0,0 +1,106 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useRef, useState } from 'react';
+import { mergePieces, sampleCurve, splitPieces } from '../core/values';
+import { inputStyle, theme } from './theme';
+const WIDTH = 218;
+const HEIGHT = 84;
+const PAD = 8;
+/**
+ * Multi-segment piecewise-bezier curve editor. Drag keys/handles vertically,
+ * drag inner keys horizontally, double-click the curve to add a key, double-click
+ * a key to remove it (Unity-like).
+ */
+export function CurveEditor(props) {
+    const svgRef = useRef(null);
+    const drag = useRef(null);
+    const [selected, setSelected] = useState(null);
+    const pieces = [...props.pieces].sort((a, b) => a.start - b.start);
+    const allValues = pieces.flatMap((piece) => piece.p);
+    const max = Math.max(props.maxValue ?? 1, ...allValues.map(Math.abs), 0.001);
+    const spanEnd = (i) => (i + 1 < pieces.length ? pieces[i + 1].start : 1);
+    const toX = (x) => PAD + x * (WIDTH - PAD * 2);
+    const toY = (v) => HEIGHT - PAD - (v / max) * (HEIGHT - PAD * 2);
+    const fromY = (y) => Math.round(Math.min(max, Math.max(0, ((HEIGHT - PAD - y) / (HEIGHT - PAD * 2)) * max)) * 1000) / 1000;
+    const fromX = (px) => Math.min(1, Math.max(0, (px - PAD) / (WIDTH - PAD * 2)));
+    // Control point positions: piece start key, two handles, plus the final end key.
+    const points = [];
+    pieces.forEach((piece, i) => {
+        const end = spanEnd(i);
+        const span = end - piece.start;
+        points.push({ ref: { piece: i, idx: 0 }, x: piece.start, y: piece.p[0], isKey: true });
+        points.push({ ref: { piece: i, idx: 1 }, x: piece.start + span / 3, y: piece.p[1], isKey: false });
+        points.push({ ref: { piece: i, idx: 2 }, x: piece.start + (2 * span) / 3, y: piece.p[2], isKey: false });
+        if (i === pieces.length - 1) {
+            points.push({ ref: { piece: i, idx: 3 }, x: 1, y: piece.p[3], isKey: true });
+        }
+    });
+    const samples = [];
+    pieces.forEach((piece, i) => {
+        const end = spanEnd(i);
+        for (let s = 0; s <= 16; s++) {
+            const t = s / 16;
+            samples.push(`${toX(piece.start + t * (end - piece.start)).toFixed(1)},${toY(sampleCurve(piece.p, t)).toFixed(1)}`);
+        }
+    });
+    const applyDrag = (clientX, clientY) => {
+        const target = drag.current;
+        if (!target || !svgRef.current) {
+            return;
+        }
+        const rect = svgRef.current.getBoundingClientRect();
+        const v = fromY(clientY - rect.top);
+        const next = pieces.map((piece) => ({ start: piece.start, p: [...piece.p] }));
+        const { piece, idx } = target;
+        if (idx === 0) {
+            next[piece].p[0] = v;
+            if (piece > 0) {
+                next[piece - 1].p[3] = v;
+                // Inner keys can also move horizontally between neighbours.
+                const x = fromX(clientX - rect.left);
+                const min = next[piece - 1].start + 0.02;
+                const maxX = (piece + 1 < next.length ? next[piece + 1].start : 1) - 0.02;
+                next[piece].start = Math.min(maxX, Math.max(min, x));
+            }
+        }
+        else if (idx === 3) {
+            next[piece].p[3] = v;
+        }
+        else {
+            next[piece].p[idx] = v;
+        }
+        props.onChange(next);
+    };
+    const selectedPoint = selected ? points.find((pt) => pt.ref.piece === selected.piece && pt.ref.idx === selected.idx) : null;
+    return (_jsxs("div", { children: [_jsxs("svg", { ref: svgRef, width: WIDTH, height: HEIGHT, style: { background: 'rgba(5, 8, 18, 0.85)', border: `1px solid ${theme.border}`, borderRadius: 8, touchAction: 'none', display: 'block' }, onPointerMove: (e) => applyDrag(e.clientX, e.clientY), onPointerUp: (e) => {
+                    drag.current = null;
+                    e.target.releasePointerCapture?.(e.pointerId);
+                }, onDoubleClick: (e) => {
+                    if (e.target.tagName === 'circle') {
+                        return;
+                    }
+                    const rect = svgRef.current.getBoundingClientRect();
+                    props.onChange(splitPieces(pieces, fromX(e.clientX - rect.left)));
+                }, children: [[0.25, 0.5, 0.75].map((f) => (_jsx("line", { x1: PAD, x2: WIDTH - PAD, y1: PAD + f * (HEIGHT - PAD * 2), y2: PAD + f * (HEIGHT - PAD * 2), stroke: "#1c274a", strokeWidth: 1 }, f))), _jsx("polyline", { points: samples.join(' '), fill: "none", stroke: theme.curveStroke, strokeWidth: 2 }), points.map((pt) => (_jsx("circle", { className: "qe-hover", cx: toX(pt.x), cy: toY(pt.y), r: pt.isKey ? 5 : 4, fill: pt.isKey ? theme.curveStroke : '#28407f', stroke: theme.curveStroke, strokeWidth: 1.5, style: { cursor: pt.isKey && pt.ref.idx === 0 && pt.ref.piece > 0 ? 'move' : 'ns-resize' }, onPointerDown: (e) => {
+                            drag.current = pt.ref;
+                            setSelected(pt.ref);
+                            e.target.setPointerCapture(e.pointerId);
+                        }, onDoubleClick: (e) => {
+                            e.stopPropagation();
+                            if (pt.isKey && pt.ref.idx === 0 && pt.ref.piece > 0) {
+                                setSelected(null);
+                                props.onChange(mergePieces(pieces, pt.ref.piece));
+                            }
+                        } }, `${pt.ref.piece}-${pt.ref.idx}`)))] }), _jsx("div", { style: { display: 'flex', gap: 4, marginTop: 4, alignItems: 'center' }, children: selectedPoint ? (_jsxs(_Fragment, { children: [_jsx("span", { style: { fontSize: 10.5, color: theme.textDim }, children: "value" }), _jsx("input", { type: "number", className: "qe-hover", step: 0.05, style: { ...inputStyle, fontSize: 11, padding: '3px 5px', width: 70 }, value: Math.round(selectedPoint.y * 1000) / 1000, onChange: (e) => {
+                                const parsed = parseFloat(e.target.value);
+                                if (Number.isNaN(parsed)) {
+                                    return;
+                                }
+                                const next = pieces.map((piece) => ({ start: piece.start, p: [...piece.p] }));
+                                const { piece, idx } = selectedPoint.ref;
+                                if (idx === 0 && piece > 0) {
+                                    next[piece - 1].p[3] = parsed;
+                                }
+                                next[piece].p[idx === 3 ? 3 : idx] = parsed;
+                                props.onChange(next);
+                            } }), _jsxs("span", { style: { fontSize: 10.5, color: theme.textDim }, children: ["t=", Math.round(selectedPoint.x * 100) / 100] })] })) : (_jsx("span", { style: { fontSize: 10.5, color: theme.textDim }, children: "dbl-click curve: add key \u00B7 dbl-click key: remove" })) })] }));
+}

package/dist/react/EffectEditor.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import { EffectBinding } from '../core/binding';
+import type { GeometryData, GeometryOption, TextureOption } from './modules';
+import type { ParticleSystem } from 'babylon.quarks';
+export interface EffectEditorProps {
+    binding: EffectBinding;
+    /** Currently selected system, lifted up so the timeline panel and this module stack agree. */
+    selectedSystem: ParticleSystem;
+    /** Texture presets offered in the Renderer module (host supplies the loader). */
+    textureOptions?: TextureOption[];
+    /** Mesh presets offered for the Mesh render mode (host supplies the geometry buffers). */
+    geometryOptions?: GeometryOption[];
+    resolveTexture?: (url: string) => unknown;
+    /** Host loader for "Load from file…" in the Mesh render mode (e.g. a GLB importer). */
+    resolveGeometry?: (file: File) => Promise<GeometryData>;
+}
+/**
+ * Shuriken-style effect editor: a stacked module inspector for the selected system.
+ * Embed it anywhere React runs — the standalone examples page or a BabylonJS Editor plugin.
+ * Module order mirrors Unity's Particle System inspector.
+ */
+export declare function EffectEditor(props: EffectEditorProps): React.JSX.Element;

package/dist/react/EffectEditor.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useSyncExternalStore } from 'react';
+import { EffectBinding } from '../core/binding';
+import { ColorOverLifeModule, EmissionModule, MainModule, RendererModule, ShapeModule, SizeOverLifeModule, } from './modules';
+import { CollisionModule, ColorBySpeedModule, EmitDirectionModule, ForceOverLifeModule, GravityModule, InheritVelocityModule, LimitSpeedOverLifeModule, NoiseModule, OrbitOverLifeModule, RotationBySpeedModule, RotationOverLifeModule, SizeBySpeedModule, SpeedOverLifeModule, TextureSheetModule, TurbulenceModule, VelocityOverLifeModule, WidthOverTrailModule, } from './behaviorModules';
+import { SubEmittersModule } from './SubEmittersModule';
+import { theme } from './theme';
+/**
+ * Shuriken-style effect editor: a stacked module inspector for the selected system.
+ * Embed it anywhere React runs — the standalone examples page or a BabylonJS Editor plugin.
+ * Module order mirrors Unity's Particle System inspector.
+ */
+export function EffectEditor(props) {
+    useSyncExternalStore((onStoreChange) => props.binding.subscribe(onStoreChange), () => props.binding.getRevision());
+    const allSystems = [props.binding.system, ...props.binding.subSystems];
+    // Selection survives re-renders but falls back to root if the system was removed/replaced.
+    const activeSystem = allSystems.includes(props.selectedSystem) ? props.selectedSystem : props.binding.system;
+    // Inspector edits go through a per-system binding; changes route into the root
+    // binding's undo history and re-render via the subscription below.
+    const binding = React.useMemo(() => {
+        if (activeSystem === props.binding.system) {
+            return props.binding;
+        }
+        const nested = new EffectBinding(activeSystem);
+        nested.onBeforeChange = () => props.binding.onBeforeChange?.();
+        return nested;
+    }, [props.binding, activeSystem]);
+    useSyncExternalStore((onStoreChange) => binding.subscribe(onStoreChange), () => binding.getRevision());
+    return (_jsxs("div", { style: { fontFamily: theme.font, color: theme.text }, children: [_jsx(MainModule, { binding: binding }), _jsx(EmissionModule, { binding: binding }), _jsx(ShapeModule, { binding: binding }), _jsx(EmitDirectionModule, { binding: binding }), _jsx(VelocityOverLifeModule, { binding: binding }), _jsx(SpeedOverLifeModule, { binding: binding }), _jsx(LimitSpeedOverLifeModule, { binding: binding }), _jsx(InheritVelocityModule, { binding: binding }), _jsx(ForceOverLifeModule, { binding: binding }), _jsx(GravityModule, { binding: binding }), _jsx(OrbitOverLifeModule, { binding: binding }), _jsx(ColorOverLifeModule, { binding: binding }), _jsx(ColorBySpeedModule, { binding: binding }), _jsx(SizeOverLifeModule, { binding: binding }), _jsx(SizeBySpeedModule, { binding: binding }), _jsx(RotationOverLifeModule, { binding: binding }), _jsx(RotationBySpeedModule, { binding: binding }), _jsx(NoiseModule, { binding: binding }), _jsx(TurbulenceModule, { binding: binding }), _jsx(CollisionModule, { binding: binding }), _jsx(WidthOverTrailModule, { binding: binding }), _jsx(SubEmittersModule, { binding: binding, rootBinding: props.binding }), _jsx(TextureSheetModule, { binding: binding }), _jsx(RendererModule, { binding: binding, textureOptions: props.textureOptions, geometryOptions: props.geometryOptions, resolveTexture: props.resolveTexture, resolveGeometry: props.resolveGeometry })] }));
+}

package/dist/react/EffectEditorHost.d.ts

@@ -0,0 +1,42 @@
+import React from 'react';
+import { Scene } from '@babylonjs/core/scene';
+import { BatchedRenderer } from 'babylon.quarks';
+import { EffectBinding } from '../core/binding';
+import { EffectHistory } from '../core/history';
+import type { GeometryData, GeometryOption, TextureOption } from './modules';
+export interface EffectEditorHostHandle {
+    binding: EffectBinding;
+    history: EffectHistory;
+    scene: Scene;
+    renderer: BatchedRenderer;
+    importJson: (json: unknown) => void;
+    exportJson: () => string;
+}
+export interface EffectEditorHostProps {
+    /** Quarks JSON export to open; a default effect is created when omitted. */
+    effectJson?: unknown;
+    /** When set, a Save button appears and receives the serialized effect. */
+    onSave?: (json: string) => void;
+    /** Called once the engine/scene/binding are live (and after every import). */
+    onReady?: (handle: EffectEditorHostHandle) => void;
+    title?: string;
+    textureOptions?: TextureOption[];
+    /** Mesh presets for the Mesh render mode (e.g. asset meshes from a host editor). */
+    geometryOptions?: GeometryOption[];
+    resolveTexture?: (url: string, scene: Scene) => unknown;
+    /** Host loader for the Mesh "Load from file…" option (e.g. GLB via @babylonjs/loaders). */
+    resolveGeometry?: (file: File, scene: Scene) => Promise<GeometryData>;
+}
+/**
+ * Self-contained effect editor: live Babylon preview + hierarchy/inspector sidebar.
+ * Designed for embedding — see QuarksEffectEditor.Show for the NME-style entry point.
+ */
+export declare function EffectEditorHost(props: EffectEditorHostProps): React.JSX.Element;
+/** NME-style imperative entry point for hosts like BabylonJS Editor windows. */
+export declare const QuarksEffectEditor: {
+    Show(options: EffectEditorHostProps & {
+        hostElement: HTMLElement;
+    }): {
+        dispose: () => void;
+    };
+};

package/dist/react/EffectEditorHost.js

@@ -0,0 +1,247 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useReducer, useRef, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { Engine } from '@babylonjs/core/Engines/engine';
+import { Scene } from '@babylonjs/core/scene';
+import { ArcRotateCamera } from '@babylonjs/core/Cameras/arcRotateCamera';
+import { DirectionalLight } from '@babylonjs/core/Lights/directionalLight';
+import { Vector3 as BVector3 } from '@babylonjs/core/Maths/math.vector';
+import { Color3, Color4 } from '@babylonjs/core/Maths/math.color';
+import { MeshBuilder } from '@babylonjs/core/Meshes/meshBuilder';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { GridMaterial } from '@babylonjs/materials/grid/gridMaterial';
+import { BatchedRenderer, ColorOverLife, ConeEmitter, ConstantColor, ConstantValue, IntervalValue, ParticleSystem, RenderMode, Vector4, } from 'babylon.quarks';
+import { EffectBinding } from '../core/binding';
+import { EffectHistory } from '../core/history';
+import { ensureGroundResolver } from '../core/collision';
+import { loadEffectFromJson } from '../core/loadEffect';
+import { DEFAULT_GRADIENT_STOPS, buildGradient } from '../core/colors';
+import { EffectEditor } from './EffectEditor';
+import { PromptDialog } from './PromptDialog';
+import { TimelinePanel } from './TimelinePanel';
+import { buttonStyle, globalEditorStyles, theme } from './theme';
+function createDefaultEffect(scene, resolveTexture, textureUrl) {
+    const system = new ParticleSystem({
+        scene,
+        duration: 4,
+        looping: true,
+        startLife: new IntervalValue(1.2, 1.8),
+        startSpeed: new IntervalValue(3, 5),
+        startSize: new IntervalValue(0.25, 0.5),
+        startColor: new ConstantColor(new Vector4(1, 1, 1, 1)),
+        emissionOverTime: new ConstantValue(80),
+        // quarks' angle is a half-angle; Babylon's native cone uses a full angle.
+        shape: new ConeEmitter({ radius: 0.3, angle: 0.25 }),
+        renderMode: RenderMode.BillBoard,
+        texture: (textureUrl && resolveTexture ? resolveTexture(textureUrl, scene) : undefined),
+        transparent: true,
+        blendMode: 1,
+    });
+    system.addBehavior(new ColorOverLife(buildGradient(DEFAULT_GRADIENT_STOPS)));
+    // quarks emits along local +Z; Babylon's native cone emits along +Y.
+    system.emitter.rotation.x = -Math.PI / 2;
+    return system;
+}
+/** Disposes an effect's systems and its remaining group tree (otherwise the groups leak). */
+function disposeEffect(root, systems, renderer) {
+    for (const system of systems) {
+        renderer.deleteSystem(system);
+        system.dispose();
+    }
+    // Disposing the systems already disposed their emitter nodes; dispose the leftover group
+    // tree too. Skip when the root IS a disposed emitter (default single-system effect).
+    if (!systems.some((system) => system.emitter === root)) {
+        root.dispose(false, true);
+    }
+}
+/**
+ * Self-contained effect editor: live Babylon preview + hierarchy/inspector sidebar.
+ * Designed for embedding — see QuarksEffectEditor.Show for the NME-style entry point.
+ */
+export function EffectEditorHost(props) {
+    const canvasRef = useRef(null);
+    const counterRef = useRef(null);
+    const playheadRef = useRef(null);
+    const importRef = useRef(null);
+    const stateRef = useRef(null);
+    const [binding, setBinding] = useState(null);
+    const [, force] = useReducer((x) => x + 1, 0);
+    const playbackRef = useRef({ paused: false, speed: 1, stepQueued: false, elapsed: 0, scrubbing: false });
+    const [paused, setPaused] = useState(false);
+    const [speed, setSpeed] = useState(1);
+    const [selectedSystem, setSelectedSystem] = useState(null);
+    const [renamingRoot, setRenamingRoot] = useState(false);
+    useEffect(() => {
+        // Register the shared ground-plane collider before any effect (default or imported)
+        // is built, so ApplyCollision behaviors deserialized by QuarksLoader resolve against it.
+        ensureGroundResolver();
+        const engine = new Engine(canvasRef.current, true);
+        const scene = new Scene(engine);
+        scene.clearColor = new Color4(0.03, 0.04, 0.09, 1);
+        const camera = new ArcRotateCamera('cam', -Math.PI / 2, 1.15, 9, new BVector3(0, 1.4, 0), scene);
+        camera.attachControl(canvasRef.current, true);
+        camera.wheelDeltaPercentage = 0.01;
+        // Mesh render mode particles are lit (billboard modes ignore these), and the grid gives
+        // a visual floor at the same y=0 plane the Collision module's ground resolver uses.
+        scene.ambientColor = new Color3(1, 1, 1);
+        const sunLight = new DirectionalLight('sun', new BVector3(-1, -1, -1), scene);
+        sunLight.intensity = 1.0;
+        sunLight.diffuse = new Color3(1, 1, 1);
+        sunLight.specular = new Color3(1, 1, 1);
+        const groundMaterial = new GridMaterial('groundMaterial', scene);
+        groundMaterial.majorUnitFrequency = 2;
+        groundMaterial.minorUnitVisibility = 0.1;
+        groundMaterial.gridRatio = 0.5;
+        groundMaterial.backFaceCulling = false;
+        groundMaterial.mainColor = new Color3(1, 1, 1);
+        groundMaterial.lineColor = new Color3(1, 1, 1);
+        groundMaterial.opacity = 0.5;
+        const ground = MeshBuilder.CreateGround('ground', { width: 100, height: 100 }, scene);
+        ground.material = groundMaterial;
+        const renderer = new BatchedRenderer('quarks-editor', scene);
+        const history = new EffectHistory();
+        const mount = (nextBinding) => {
+            history.attach(nextBinding);
+            nextBinding.subscribe(force);
+            stateRef.current = { engine, scene, renderer, binding: nextBinding, history };
+            setBinding(nextBinding);
+            props.onReady?.(makeHandle());
+        };
+        const makeHandle = () => ({
+            // Live getter: stays correct after presets/imports/undo replace the binding.
+            get binding() {
+                return stateRef.current.binding;
+            },
+            history,
+            scene,
+            renderer,
+            importJson,
+            exportJson: () => stateRef.current.binding.exportJSON('EditorEffect'),
+        });
+        const importJson = (json) => {
+            const current = stateRef.current.binding;
+            // Load first so a bad/empty JSON leaves the current effect intact.
+            const { root, systems } = loadEffectFromJson(scene, renderer, json);
+            if (systems.length === 0) {
+                disposeEffect(root, systems, renderer);
+                throw new Error('No particle systems found in the JSON.');
+            }
+            disposeEffect(current.root, [current.system, ...current.subSystems], renderer);
+            const main = systems.find((s) => !s.onlyUsedByOther) ?? systems[0];
+            mount(new EffectBinding(main, systems.filter((s) => s !== main), root));
+        };
+        let initial;
+        if (props.effectJson) {
+            const { root, systems } = loadEffectFromJson(scene, renderer, props.effectJson);
+            const main = systems.find((s) => !s.onlyUsedByOther) ?? systems[0];
+            initial = new EffectBinding(main, systems.filter((s) => s !== main), root);
+        }
+        else {
+            const system = createDefaultEffect(scene, props.resolveTexture, props.textureOptions?.[0]?.url);
+            renderer.addSystem(system);
+            // Root is a plain group (not the system's own emitter) so a new top-level system
+            // can be added as a sibling later, instead of always nesting under this one.
+            const root = new TransformNode('Effect', scene);
+            system.emitter.parent = root;
+            initial = new EffectBinding(system, [], root);
+        }
+        mount(initial);
+        engine.runRenderLoop(() => {
+            const playback = playbackRef.current;
+            if (!playback.scrubbing) {
+                let delta = (engine.getDeltaTime() / 1000) * playback.speed;
+                if (playback.paused) {
+                    delta = playback.stepQueued ? 1 / 60 : 0;
+                    playback.stepQueued = false;
+                }
+                if (delta > 0) {
+                    renderer.update(delta);
+                    playback.elapsed += delta;
+                }
+            }
+            scene.render();
+            const b = stateRef.current.binding;
+            let count = b.system.particleNum;
+            for (const sub of b.subSystems) {
+                count += sub.particleNum;
+            }
+            if (counterRef.current) {
+                counterRef.current.textContent = `${count} particles · ${playback.elapsed.toFixed(2)}s`;
+            }
+        });
+        const onResize = () => engine.resize();
+        const onKey = (e) => {
+            if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === 'z') {
+                e.preventDefault();
+                const json = e.shiftKey ? history.redo() : history.undo();
+                if (json) {
+                    importJson(json);
+                }
+                force();
+            }
+        };
+        window.addEventListener('resize', onResize);
+        window.addEventListener('keydown', onKey);
+        return () => {
+            window.removeEventListener('resize', onResize);
+            window.removeEventListener('keydown', onKey);
+            engine.dispose();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const state = stateRef.current;
+    const historyAction = (json) => {
+        if (json && state) {
+            const current = state.binding;
+            const { root, systems } = loadEffectFromJson(state.scene, state.renderer, json);
+            disposeEffect(current.root, [current.system, ...current.subSystems], state.renderer);
+            const main = systems.find((s) => !s.onlyUsedByOther) ?? systems[0];
+            const next = new EffectBinding(main, systems.filter((s) => s !== main), root);
+            state.history.attach(next);
+            next.subscribe(force);
+            state.binding = next;
+            setBinding(next);
+        }
+        force();
+    };
+    // Selection survives re-renders but falls back to root if the system was removed/replaced
+    // (e.g. after undo/redo or import swaps the whole binding out from under it).
+    const allSystems = binding ? [binding.system, ...binding.subSystems] : [];
+    const activeSystem = binding ? (selectedSystem && allSystems.includes(selectedSystem) ? selectedSystem : binding.system) : null;
+    return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', width: '100%', height: '100%', fontFamily: theme.font, color: theme.text, background: '#070b16' }, children: [_jsx("style", { children: globalEditorStyles }), _jsxs("div", { style: { display: 'flex', flex: 1, minHeight: 0 }, children: [_jsx("div", { style: { position: 'relative', flex: 1, minWidth: 0 }, children: _jsx("canvas", { ref: canvasRef, style: { width: '100%', height: '100%', display: 'block', touchAction: 'none', outline: 'none' } }) }), _jsxs("aside", { style: { width: 340, flexShrink: 0, borderLeft: `1px solid ${theme.border}`, background: theme.panelBg, display: 'flex', flexDirection: 'column' }, children: [_jsxs("div", { style: { padding: '12px 14px 10px', borderBottom: `1px solid ${theme.border}` }, children: [_jsx("div", { className: "qe-hover-bg", title: binding ? 'Rename effect' : undefined, style: { fontSize: 16, fontWeight: 600, cursor: binding ? 'pointer' : 'default', borderRadius: 6, padding: '2px 4px', margin: '-2px -4px' }, onClick: () => binding && setRenamingRoot(true), children: (binding?.root.name || props.title) ?? 'Effect editor' }), renamingRoot && binding && (_jsx(PromptDialog, { title: "Rename effect", defaultValue: binding.root.name, onSubmit: (name) => {
+                                            binding.apply(() => (binding.root.name = name));
+                                            setRenamingRoot(false);
+                                        }, onCancel: () => setRenamingRoot(false) })), _jsxs("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 6, marginTop: 10 }, children: [_jsx("button", { className: "qe-hover", style: buttonStyle, title: "Undo (Ctrl+Z)", disabled: !state?.history.canUndo, onClick: () => historyAction(state.history.undo()), children: "\u21B6" }), _jsx("button", { className: "qe-hover", style: buttonStyle, title: "Redo (Ctrl+Shift+Z)", disabled: !state?.history.canRedo, onClick: () => historyAction(state.history.redo()), children: "\u21B7" }), _jsx("button", { className: "qe-hover", style: buttonStyle, onClick: () => {
+                                                    if (!binding)
+                                                        return;
+                                                    const blob = new Blob([binding.exportJSON('EditorEffect')], { type: 'application/json' });
+                                                    const link = document.createElement('a');
+                                                    link.href = URL.createObjectURL(blob);
+                                                    link.download = 'effect.json';
+                                                    link.click();
+                                                    URL.revokeObjectURL(link.href);
+                                                }, children: "Export" }), _jsx("button", { className: "qe-hover", style: buttonStyle, onClick: () => importRef.current?.click(), children: "Import" }), props.onSave && (_jsx("button", { className: "qe-hover", style: buttonStyle, onClick: () => binding && props.onSave(binding.exportJSON('EditorEffect')), children: "Save" })), _jsx("input", { ref: importRef, type: "file", accept: ".json,application/json", hidden: true, onChange: async (e) => {
+                                                    const file = e.target.files?.[0];
+                                                    e.target.value = '';
+                                                    if (!file || !state)
+                                                        return;
+                                                    try {
+                                                        const json = JSON.parse(await file.text());
+                                                        historyAction(json);
+                                                        state.history.clear();
+                                                        force();
+                                                    }
+                                                    catch (err) {
+                                                        console.error('Failed to import effect JSON:', err);
+                                                    }
+                                                } })] })] }), _jsx("div", { style: { flex: 1, overflowY: 'auto', padding: '6px 14px 20px' }, children: binding && activeSystem && (_jsx(EffectEditor, { binding: binding, selectedSystem: activeSystem, textureOptions: props.textureOptions, geometryOptions: props.geometryOptions, resolveTexture: props.resolveTexture && state ? (url) => props.resolveTexture(url, state.scene) : undefined, resolveGeometry: props.resolveGeometry && state ? (file) => props.resolveGeometry(file, state.scene) : undefined })) })] })] }), binding && activeSystem && state && (_jsx(TimelinePanel, { binding: binding, selectedSystem: activeSystem, onSelect: setSelectedSystem, scene: state.scene, renderer: state.renderer, playbackRef: playbackRef, playheadRef: playheadRef, counterRef: counterRef, paused: paused, setPaused: setPaused, speed: speed, setSpeed: setSpeed }))] }));
+}
+/** NME-style imperative entry point for hosts like BabylonJS Editor windows. */
+export const QuarksEffectEditor = {
+    Show(options) {
+        const { hostElement, ...props } = options;
+        const root = createRoot(hostElement);
+        root.render(_jsx(EffectEditorHost, { ...props }));
+        return { dispose: () => root.unmount() };
+    },
+};

package/dist/react/GradientEditor.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+import { GradientStop } from '../core/colors';
+/** Gradient editor: RGBA stops on a bar — click to add, drag to move, edit the selected stop. */
+export declare function GradientEditor(props: {
+    stops: GradientStop[];
+    onChange: (stops: GradientStop[]) => void;
+}): React.JSX.Element;