babylon.quarks-editor 0.17.7 → 0.17.8

package/dist/core/timeline.d.ts

@@ -31,5 +31,5 @@ export declare function computeStartOffset(gen: ValueGenerator | FunctionValueGe
 };
 /** Flattens the effect's group/emitter tree into display rows, preserving tree-walk order. */
 export declare function computeTimelineRows(binding: EffectBinding): TimelineRow[];
-/** Overall visible timeline span: the furthest track extent, floored at a sane minimum. */
+/** Overall timeline span: the furthest track extent (start offset + duration). */
 export declare function computeTimelineSpan(rows: TimelineRow[]): number;

package/dist/core/timeline.js

@@ -1,5 +1,6 @@
 import { ConstantValue, IntervalValue } from 'babylon.quarks';
-const MIN_TIMELINE_SPAN = 4;
+/** Guards against a literally zero-width ruler (e.g. no tracks yet) — not a usability stretch. */
+const MIN_TIMELINE_SPAN = 0.01;
 /**
  * Reads a representative start-delay value for display without invoking the generator's
  * stateful `genValue` (IntervalValue caches its sampled slot on first call and returns NaN
@@ -57,7 +58,7 @@ export function computeTimelineRows(binding) {
     walk(binding.getTree());
     return rows;
 }
-/** Overall visible timeline span: the furthest track extent, floored at a sane minimum. */
+/** Overall timeline span: the furthest track extent (start offset + duration). */
 export function computeTimelineSpan(rows) {
     let span = 0;
     for (const row of rows) {

package/dist/react/EffectEditor.d.ts

@@ -1,4 +1,5 @@
 import React from 'react';
+import type { TransformNode } from '@babylonjs/core/Meshes/transformNode';
 import { EffectBinding } from '../core/binding';
 import type { GeometryData, GeometryOption, TextureOption } from './modules';
 import type { ParticleSystem } from 'babylon.quarks';
@@ -6,6 +7,8 @@ export interface EffectEditorProps {
     binding: EffectBinding;
     /** Currently selected system, lifted up so the timeline panel and this module stack agree. */
     selectedSystem: ParticleSystem;
+    gizmoTargetNode: TransformNode;
+    gizmoTargetLabel: string;
     /** 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). */

package/dist/react/EffectEditor.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { useSyncExternalStore } from 'react';
 import { EffectBinding } from '../core/binding';
+import { ObjectModule } from './ObjectModule';
 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';
@@ -26,5 +27,9 @@ export function EffectEditor(props) {
         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 })] }));
+    const gizmoTargetIsEmitter = allSystems.some((s) => s.emitter === props.gizmoTargetNode);
+    if (!gizmoTargetIsEmitter) {
+        return (_jsx("div", { style: { fontFamily: theme.font, color: theme.text }, children: _jsx(ObjectModule, { node: props.gizmoTargetNode, label: props.gizmoTargetLabel }) }));
+    }
+    return (_jsxs("div", { style: { fontFamily: theme.font, color: theme.text }, children: [_jsx(ObjectModule, { node: props.gizmoTargetNode, label: props.gizmoTargetLabel }), _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.js

@@ -9,6 +9,8 @@ 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 { GizmoManager } from '@babylonjs/core/Gizmos/gizmoManager';
+import { UtilityLayerRenderer } from '@babylonjs/core/Rendering/utilityLayerRenderer';
 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';
@@ -54,6 +56,26 @@ function disposeEffect(root, systems, renderer) {
         root.dispose(false, true);
     }
 }
+const GIZMO_MODE_BUTTONS = [
+    { value: 'none', icon: '↖', title: 'Select (hide stage gizmo)' },
+    { value: 'position', icon: 'M', title: 'Move the stage node (position)' },
+    { value: 'rotation', icon: 'R', title: 'Rotate the stage node' },
+    { value: 'scale', icon: 'S', title: 'Scale the stage node' },
+];
+const squareButtonStyle = {
+    ...buttonStyle,
+    width: 28,
+    height: 28,
+    padding: 0,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    fontWeight: 700,
+};
+const activeSquareButtonStyle = {
+    border: `1px solid ${theme.borderActive}`,
+    background: 'rgba(120, 165, 255, 0.35)',
+};
 /**
  * Self-contained effect editor: live Babylon preview + hierarchy/inspector sidebar.
  * Designed for embedding — see QuarksEffectEditor.Show for the NME-style entry point.
@@ -64,13 +86,15 @@ export function EffectEditorHost(props) {
     const playheadRef = useRef(null);
     const importRef = useRef(null);
     const stateRef = useRef(null);
+    const gizmoManagerRef = 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);
+    const [gizmoMode, setGizmoMode] = useState('none');
+    const [selectedNode, setSelectedNode] = useState(null);
     useEffect(() => {
         // Register the shared ground-plane collider before any effect (default or imported)
         // is built, so ApplyCollision behaviors deserialized by QuarksLoader resolve against it.
@@ -98,13 +122,21 @@ export function EffectEditorHost(props) {
         groundMaterial.opacity = 0.5;
         const ground = MeshBuilder.CreateGround('ground', { width: 100, height: 100 }, scene);
         ground.material = groundMaterial;
+        const stageRoot = new TransformNode('StageRoot', scene);
+        const gizmoUtilityLayer = new UtilityLayerRenderer(scene);
+        const gizmoManager = new GizmoManager(scene, undefined, gizmoUtilityLayer);
+        gizmoManager.usePointerToAttachGizmos = false;
+        gizmoManager.attachToNode(stageRoot);
+        gizmoManagerRef.current = gizmoManager;
         const renderer = new BatchedRenderer('quarks-editor', scene);
         const history = new EffectHistory();
         const mount = (nextBinding) => {
+            nextBinding.root.parent = stageRoot;
             history.attach(nextBinding);
             nextBinding.subscribe(force);
-            stateRef.current = { engine, scene, renderer, binding: nextBinding, history };
+            stateRef.current = { engine, scene, renderer, binding: nextBinding, history, stageRoot };
             setBinding(nextBinding);
+            setSelectedNode(nextBinding.system.emitter);
             props.onReady?.(makeHandle());
         };
         const makeHandle = () => ({
@@ -169,7 +201,8 @@ export function EffectEditorHost(props) {
                 counterRef.current.textContent = `${count} particles · ${playback.elapsed.toFixed(2)}s`;
             }
         });
-        const onResize = () => engine.resize();
+        const resizeObserver = new ResizeObserver(() => engine.resize());
+        resizeObserver.observe(canvasRef.current);
         const onKey = (e) => {
             if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === 'z') {
                 e.preventDefault();
@@ -180,16 +213,43 @@ export function EffectEditorHost(props) {
                 force();
             }
         };
-        window.addEventListener('resize', onResize);
         window.addEventListener('keydown', onKey);
         return () => {
-            window.removeEventListener('resize', onResize);
+            resizeObserver.disconnect();
             window.removeEventListener('keydown', onKey);
+            gizmoManager.dispose();
+            gizmoUtilityLayer.dispose();
             engine.dispose();
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);
+    useEffect(() => {
+        const gm = gizmoManagerRef.current;
+        if (!gm)
+            return;
+        gm.positionGizmoEnabled = gizmoMode === 'position';
+        gm.rotationGizmoEnabled = gizmoMode === 'rotation';
+        gm.scaleGizmoEnabled = gizmoMode === 'scale';
+        const activeGizmo = gizmoMode === 'position' ? gm.gizmos.positionGizmo : gizmoMode === 'rotation' ? gm.gizmos.rotationGizmo : gizmoMode === 'scale' ? gm.gizmos.scaleGizmo : null;
+        const observer = activeGizmo?.onDragObservable.add(() => force());
+        return () => {
+            if (activeGizmo && observer)
+                activeGizmo.onDragObservable.remove(observer);
+        };
+    }, [gizmoMode]);
+    useEffect(() => {
+        const gm = gizmoManagerRef.current;
+        const stageRoot = stateRef.current?.stageRoot;
+        if (!gm || !stageRoot)
+            return;
+        if (selectedNode && selectedNode.isDisposed()) {
+            setSelectedNode(stateRef.current?.binding.system.emitter ?? null);
+            return;
+        }
+        gm.attachToNode(selectedNode ?? stageRoot);
+    }, [selectedNode, binding]);
     const state = stateRef.current;
+    const gizmoNode = selectedNode && !selectedNode.isDisposed() ? selectedNode : state?.stageRoot;
     const historyAction = (json) => {
         if (json && state) {
             const current = state.binding;
@@ -197,21 +257,22 @@ export function EffectEditorHost(props) {
             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);
+            next.root.parent = state.stageRoot;
             state.history.attach(next);
             next.subscribe(force);
             state.binding = next;
             setBinding(next);
+            setSelectedNode(next.system.emitter);
         }
         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) => {
+    const activeSystem = binding ? (allSystems.find((s) => s.emitter === selectedNode) ?? binding.system) : null;
+    const gizmoTargetLabel = selectedNode ? gizmoNode?.name || 'Node' : 'Stage (preview parent)';
+    return (_jsxs("div", { className: "qe-root", 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: [_jsxs("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("div", { style: { position: 'absolute', top: 12, right: 12, display: 'flex', flexDirection: 'column', alignItems: 'flex-end', gap: 6 }, children: [_jsxs("div", { style: { display: 'flex', gap: 4, background: theme.panelBg, border: `1px solid ${theme.border}`, borderRadius: 8, padding: 4 }, children: [_jsx("button", { className: "qe-hover", style: squareButtonStyle, title: "Undo (Ctrl+Z)", disabled: !state?.history.canUndo, onClick: () => historyAction(state.history.undo()), children: "\u21B6" }), _jsx("button", { className: "qe-hover", style: squareButtonStyle, title: "Redo (Ctrl+Shift+Z)", disabled: !state?.history.canRedo, onClick: () => historyAction(state.history.redo()), children: "\u21B7" })] }), _jsx("div", { style: { display: 'flex', flexDirection: 'column', gap: 4, background: theme.panelBg, border: `1px solid ${theme.border}`, borderRadius: 8, padding: 4 }, children: GIZMO_MODE_BUTTONS.map((m) => (_jsx("button", { className: "qe-hover", style: { ...squareButtonStyle, ...(gizmoMode === m.value ? activeSquareButtonStyle : {}) }, title: m.title, onClick: () => setGizmoMode(m.value), children: m.icon }, m.value))) })] })] }), _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: () => {
+                                        }, onCancel: () => setRenamingRoot(false) })), _jsxs("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 6, marginTop: 10 }, children: [_jsx("button", { className: "qe-hover", style: buttonStyle, onClick: () => {
                                                     if (!binding)
                                                         return;
                                                     const blob = new Blob([binding.exportJSON('EditorEffect')], { type: 'application/json' });
@@ -234,7 +295,7 @@ export function EffectEditorHost(props) {
                                                     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 }))] }));
+                                                } })] })] }), _jsx("div", { style: { flex: 1, overflowY: 'auto', padding: '6px 14px 20px' }, children: binding && activeSystem && gizmoNode && (_jsx(EffectEditor, { binding: binding, selectedSystem: activeSystem, gizmoTargetNode: gizmoNode, gizmoTargetLabel: gizmoTargetLabel, 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, selectedNode: selectedNode, onSelectNode: setSelectedNode, 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 = {

package/dist/react/ObjectModule.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+import type { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+export declare function ObjectModule(props: {
+    node: TransformNode;
+    label: string;
+}): React.JSX.Element;

package/dist/react/ObjectModule.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Quaternion } from '@babylonjs/core/Maths/math.vector';
+import { ModuleSection } from './ModuleSection';
+import { NumberField, Row } from './fields';
+const RAD_TO_DEG = 180 / Math.PI;
+const DEG_TO_RAD = Math.PI / 180;
+function getEulerDegrees(node) {
+    const euler = node.rotationQuaternion ? node.rotationQuaternion.toEulerAngles() : node.rotation;
+    return { x: euler.x * RAD_TO_DEG, y: euler.y * RAD_TO_DEG, z: euler.z * RAD_TO_DEG };
+}
+function setEulerDegreeAxis(node, axis, degrees) {
+    const euler = node.rotationQuaternion ? node.rotationQuaternion.toEulerAngles() : node.rotation.clone();
+    euler[axis] = degrees * DEG_TO_RAD;
+    if (node.rotationQuaternion) {
+        node.rotationQuaternion = Quaternion.FromEulerVector(euler);
+    }
+    else {
+        node.rotation = euler;
+    }
+}
+function AxisRow(props) {
+    return (_jsx(Row, { label: props.label, children: _jsxs("div", { style: { display: 'flex', gap: 4 }, children: [_jsx(NumberField, { value: props.values.x, step: props.step, onChange: (v) => props.onChange('x', v) }), _jsx(NumberField, { value: props.values.y, step: props.step, onChange: (v) => props.onChange('y', v) }), _jsx(NumberField, { value: props.values.z, step: props.step, onChange: (v) => props.onChange('z', v) })] }) }));
+}
+export function ObjectModule(props) {
+    const { node } = props;
+    const euler = getEulerDegrees(node);
+    return (_jsxs(ModuleSection, { title: `Object — ${props.label}`, children: [_jsx(AxisRow, { label: "Position", values: { x: node.position.x, y: node.position.y, z: node.position.z }, step: 0.1, onChange: (axis, v) => (node.position[axis] = v) }), _jsx(AxisRow, { label: "Rotation", values: euler, step: 1, onChange: (axis, v) => setEulerDegreeAxis(node, axis, v) }), _jsx(AxisRow, { label: "Scale", values: { x: node.scaling.x, y: node.scaling.y, z: node.scaling.z }, step: 0.1, onChange: (axis, v) => (node.scaling[axis] = v) })] }));
+}

package/dist/react/TimelinePanel.d.ts

@@ -1,6 +1,7 @@
 import React from 'react';
-import type { ParticleSystem, BatchedRenderer } from 'babylon.quarks';
+import type { BatchedRenderer } from 'babylon.quarks';
 import type { Scene } from '@babylonjs/core/scene';
+import type { TransformNode } from '@babylonjs/core/Meshes/transformNode';
 import type { EffectBinding } from '../core/binding';
 export interface PlaybackState {
     paused: boolean;
@@ -11,8 +12,8 @@ export interface PlaybackState {
 }
 export interface TimelinePanelProps {
     binding: EffectBinding;
-    selectedSystem: ParticleSystem;
-    onSelect: (system: ParticleSystem) => void;
+    selectedNode: TransformNode | null;
+    onSelectNode: (node: TransformNode | null) => void;
     scene: Scene;
     renderer: BatchedRenderer;
     playbackRef: React.MutableRefObject<PlaybackState>;

package/dist/react/TimelinePanel.js

@@ -7,9 +7,12 @@ import { TimelineTrackRow } from './TimelineTrackRow';
 import { buttonStyle, theme } from './theme';
 const LABEL_WIDTH = 200;
 const RULER_HEIGHT = 22;
+const STAGE_ROW_HEIGHT = 26;
 const PANEL_HEIGHT = 220;
 /** Small gap between the label column and the first pixel of the time axis. */
 export const TIMELINE_INSET = 10;
+/** Gap reserved at the right edge so the full-duration mark doesn't sit flush against the panel edge. */
+const RIGHT_PADDING = 16;
 function pickTickInterval(pxPerSecond) {
     if (pxPerSecond >= 60)
         return 1;
@@ -24,7 +27,7 @@ function pickTickInterval(pxPerSecond) {
  * draggable playhead (approximate scrub — see core/scrub.ts), and one track row per system.
  */
 export function TimelinePanel(props) {
-    const { binding, selectedSystem, onSelect, scene, renderer, playbackRef, playheadRef, counterRef, paused, setPaused, speed, setSpeed } = props;
+    const { binding, selectedNode, onSelectNode, scene, renderer, playbackRef, playheadRef, counterRef, paused, setPaused, speed, setSpeed } = props;
     const [bodyWidthPx, setBodyWidthPx] = useState(600);
     const [collapsedGroups, setCollapsedGroups] = useState(() => new Set());
     const [hiddenSystems, setHiddenSystems] = useState(() => new Set());
@@ -87,24 +90,53 @@ export function TimelinePanel(props) {
         return () => observer.disconnect();
     }, []);
     const rows = useMemo(() => computeTimelineRows(binding), [binding, binding.getRevision()]);
+    // The ruler spans exactly the furthest track extent (no artificial stretch), minus a
+    // right-hand gap so the full-duration mark never sits flush against the panel edge.
     const timelineSpan = useMemo(() => computeTimelineSpan(rows), [rows]);
-    const pxPerSecond = Math.max(1, bodyWidthPx - TIMELINE_INSET) / timelineSpan;
+    const pxPerSecond = Math.max(1, bodyWidthPx - TIMELINE_INSET - RIGHT_PADDING) / timelineSpan;
     // Follows playbackRef.elapsed independently of Babylon's render loop (Host only owns
-    // simulation time; this owns translating it into pixels for the playhead line). Looping
-    // effects run forever, so elapsed grows unbounded — wrap it to the visible span instead
-    // of letting the playhead fly off past the right edge.
+    // simulation time; this owns translating it into pixels for the playhead line). Whether
+    // the *whole* effect loops is an OR across tracks (there's no single canonical "root" —
+    // an effect can have several top-level systems): if any track loops, elapsed grows
+    // unbounded and we wrap it at timelineSpan. If none loop, finishing a run snaps playback
+    // straight back to frame 0 (paused) — a one-shot preview parked and ready for the next Play.
+    const anyLooping = useMemo(() => rows.some((r) => r.kind === 'track' && r.looping), [rows]);
+    // Tracks elapsed from the previous tick so the finish-reset below only fires on a genuine
+    // crossing during live playback. Without this, manually dragging the playhead to (or past)
+    // the end pins elapsed at timelineSpan while scrubbing=true skips the reset — but the very
+    // next tick after release would otherwise see elapsed >= timelineSpan with no memory of
+    // *how* it got there, and wrongly treat a drag as a finished run.
+    const prevElapsedRef = useRef(0);
     React.useEffect(() => {
         let raf;
         const tick = () => {
+            const state = playbackRef.current;
+            const elapsed = state.elapsed;
+            let shown = elapsed;
+            if (anyLooping) {
+                shown = timelineSpan > 0 ? elapsed % timelineSpan : 0;
+            }
+            else if (elapsed >= timelineSpan) {
+                shown = timelineSpan;
+                const justFinishedPlaying = !state.scrubbing && !state.paused && prevElapsedRef.current < timelineSpan;
+                if (justFinishedPlaying) {
+                    scrubTo(binding, renderer, 0);
+                    state.elapsed = 0;
+                    state.paused = true;
+                    setPaused(true);
+                    scene.render();
+                    shown = 0;
+                }
+            }
+            prevElapsedRef.current = elapsed;
             if (playheadRef.current) {
-                const wrapped = timelineSpan > 0 ? playbackRef.current.elapsed % timelineSpan : 0;
-                playheadRef.current.style.left = `${LABEL_WIDTH + TIMELINE_INSET + wrapped * pxPerSecond}px`;
+                playheadRef.current.style.left = `${LABEL_WIDTH + TIMELINE_INSET + shown * pxPerSecond}px`;
             }
             raf = requestAnimationFrame(tick);
         };
         raf = requestAnimationFrame(tick);
         return () => cancelAnimationFrame(raf);
-    }, [pxPerSecond, timelineSpan, playbackRef, playheadRef]);
+    }, [pxPerSecond, timelineSpan, anyLooping, playbackRef, playheadRef, setPaused, binding, renderer, scene]);
     const visibleRows = useMemo(() => {
         let hideUntilDepth = null;
         const visible = rows.filter((row) => {
@@ -174,6 +206,8 @@ export function TimelinePanel(props) {
             fontFamily: theme.font,
             color: theme.text,
         }, children: [_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 6, padding: '6px 10px', borderBottom: `1px solid ${theme.border}` }, children: [_jsx("button", { className: "qe-hover", style: overlayButton, title: paused ? 'Play' : 'Pause', onClick: () => {
+                            // A finished one-shot effect already snapped itself back to frame 0 and
+                            // paused (see the tick effect above), so a plain toggle is enough here.
                             playbackRef.current.paused = !paused;
                             setPaused(!paused);
                         }, children: paused ? '▶' : '⏸' }), _jsx("button", { className: "qe-hover", style: overlayButton, title: "Step one frame", disabled: !paused, onClick: () => (playbackRef.current.stepQueued = true), children: "\u23ED" }), _jsx("button", { className: "qe-hover", style: overlayButton, title: "Restart", onClick: restart, children: "\u27F2" }), _jsx("select", { className: "qe-hover", style: { ...overlayButton, padding: '5px 4px' }, title: "Playback speed", value: speed, onChange: (e) => {
@@ -200,11 +234,27 @@ export function TimelinePanel(props) {
                                 }, onPointerUp: (e) => {
                                     playbackRef.current.scrubbing = false;
                                     e.target.releasePointerCapture?.(e.pointerId);
-                                }, children: ticks.map((t) => (_jsxs("div", { style: { position: 'absolute', left: TIMELINE_INSET + t * pxPerSecond, top: 0, bottom: 0, borderLeft: `1px solid ${theme.border}`, fontSize: 10, color: theme.textDim, paddingLeft: 3 }, children: [t, "s"] }, t))) })] }), _jsx("div", { style: {
+                                }, children: ticks.map((t) => (_jsxs("div", { style: { position: 'absolute', left: TIMELINE_INSET + t * pxPerSecond, top: 0, bottom: 0, borderLeft: `1px solid ${theme.border}`, fontSize: 10, color: theme.textDim, paddingLeft: 3 }, children: [t, "s"] }, t))) })] }), _jsxs("div", { className: "qe-hover-bg", title: "Preview parent \u2014 simulates effect.parent = someNode; not saved in the exported JSON", style: {
                             position: 'absolute',
                             top: RULER_HEIGHT,
                             left: 0,
                             right: 0,
+                            height: STAGE_ROW_HEIGHT,
+                            display: 'flex',
+                            alignItems: 'center',
+                            gap: 6,
+                            padding: '0 8px',
+                            fontSize: 12.5,
+                            fontStyle: 'italic',
+                            cursor: 'pointer',
+                            color: selectedNode === null ? theme.text : theme.textDim,
+                            borderBottom: `1px solid ${theme.border}`,
+                            ...(selectedNode === null ? { background: 'rgba(60, 105, 209, 0.3)' } : {}),
+                        }, onClick: () => onSelectNode(null), children: [_jsx("span", { style: { fontSize: 10, width: 10 }, children: "\u25CE" }), _jsx("span", { children: "Stage (preview parent)" })] }), _jsx("div", { style: {
+                            position: 'absolute',
+                            top: RULER_HEIGHT + STAGE_ROW_HEIGHT,
+                            left: 0,
+                            right: 0,
                             bottom: 0,
                             overflowY: 'auto',
                             overflowX: 'hidden',
@@ -212,7 +262,7 @@ export function TimelinePanel(props) {
                                 display: 'grid',
                                 gridTemplateColumns: `${LABEL_WIDTH}px 1fr`,
                                 gridAutoRows: 'min-content',
-                            }, children: visibleRows.map((row) => (_jsx(TimelineTrackRow, { row: row, binding: binding, selected: row.kind === 'track' && row.system === selectedSystem, onSelect: onSelect, pxPerSecond: pxPerSecond, offsetPx: TIMELINE_INSET, collapsed: row.kind === 'group' && collapsedGroups.has(row.node), onToggleCollapse: row.kind === 'group' ? () => toggleCollapse(row.node) : undefined, hidden: row.kind === 'track' && hiddenSystems.has(row.system), onToggleVisible: row.kind === 'track' ? () => toggleVisible(row.system) : undefined, groupSelected: groupSelection.has(row.node), onToggleGroupSelect: () => toggleGroupSelect(row.node) }, row.node.uniqueId))) }) }), _jsx("div", { style: { position: 'absolute', top: 0, bottom: 0, left: LABEL_WIDTH, width: 1, background: theme.border, pointerEvents: 'none', zIndex: 3 } }), _jsx("div", { ref: playheadRef, style: {
+                            }, children: visibleRows.map((row) => (_jsx(TimelineTrackRow, { row: row, binding: binding, selected: row.node === selectedNode, onSelectNode: onSelectNode, pxPerSecond: pxPerSecond, offsetPx: TIMELINE_INSET, collapsed: row.kind === 'group' && collapsedGroups.has(row.node), onToggleCollapse: row.kind === 'group' ? () => toggleCollapse(row.node) : undefined, hidden: row.kind === 'track' && hiddenSystems.has(row.system), onToggleVisible: row.kind === 'track' ? () => toggleVisible(row.system) : undefined, groupSelected: groupSelection.has(row.node), onToggleGroupSelect: () => toggleGroupSelect(row.node) }, row.node.uniqueId))) }) }), _jsx("div", { style: { position: 'absolute', top: 0, bottom: 0, left: LABEL_WIDTH, width: 1, background: theme.border, pointerEvents: 'none', zIndex: 3 } }), _jsx("div", { ref: playheadRef, style: {
                             position: 'absolute',
                             top: 0,
                             bottom: 0,

package/dist/react/TimelineTrackRow.d.ts

@@ -1,12 +1,12 @@
 import React from 'react';
-import type { ParticleSystem } from 'babylon.quarks';
+import type { TransformNode } from '@babylonjs/core/Meshes/transformNode';
 import type { EffectBinding } from '../core/binding';
 import type { TimelineRow } from '../core/timeline';
 export interface TimelineTrackRowProps {
     row: TimelineRow;
     binding: EffectBinding;
     selected: boolean;
-    onSelect: (system: ParticleSystem) => void;
+    onSelectNode: (node: TransformNode | null) => void;
     pxPerSecond: number;
     /** Matches the ruler's left gutter so bars line up under the correct tick. */
     offsetPx: number;

package/dist/react/TimelineTrackRow.js

@@ -10,7 +10,7 @@ const ROW_HEIGHT = 28;
 const checkboxButton = { ...iconButton, fontSize: 12, width: 12 };
 /** One row of the timeline: a label cell (name + actions) and, for tracks, a bar cell. */
 export function TimelineTrackRow(props) {
-    const { row, binding, selected, onSelect, pxPerSecond, offsetPx, collapsed, onToggleCollapse, hidden, onToggleVisible, groupSelected, onToggleGroupSelect } = props;
+    const { row, binding, selected, onSelectNode, pxPerSecond, offsetPx, collapsed, onToggleCollapse, hidden, onToggleVisible, groupSelected, onToggleGroupSelect } = props;
     const [renaming, setRenaming] = useState(false);
     const isRoot = row.node === binding.root;
     const labelStyle = {
@@ -23,17 +23,21 @@ export function TimelineTrackRow(props) {
         borderRadius: 6,
         cursor: row.kind === 'track' ? 'pointer' : onToggleCollapse ? 'pointer' : 'default',
         fontSize: 12.5,
-        color: row.kind === 'track' && selected ? theme.text : theme.textDim,
+        color: selected ? theme.text : theme.textDim,
         whiteSpace: 'nowrap',
+        boxSizing: 'border-box',
         // Left unset (rather than 'transparent') when not selected so the .qe-row-bg hover
         // tint isn't shadowed by an inline background of the same property.
-        ...(row.kind === 'track' && selected ? { background: 'rgba(60, 105, 209, 0.3)' } : {}),
+        ...(selected ? { background: 'rgba(60, 105, 209, 0.3)' } : {}),
     };
     if (row.kind === 'group') {
-        return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "qe-hover-bg", style: { ...labelStyle, borderTop: `1px solid ${theme.border}` }, onClick: onToggleCollapse, children: [!isRoot && (_jsx("button", { className: "qe-hover", title: groupSelected ? 'Remove from group selection' : 'Select for grouping', style: { ...checkboxButton, color: groupSelected ? theme.accent : theme.textDim }, onClick: (e) => {
+        return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "qe-hover-bg", style: { ...labelStyle, borderTop: `1px solid ${theme.border}` }, onClick: () => onSelectNode(row.node), children: [!isRoot && (_jsx("button", { className: "qe-hover", title: groupSelected ? 'Remove from group selection' : 'Select for grouping', style: { ...checkboxButton, color: groupSelected ? theme.accent : theme.textDim }, onClick: (e) => {
                                 e.stopPropagation();
                                 onToggleGroupSelect();
-                            }, children: groupSelected ? '☑' : '☐' })), _jsx("span", { style: { color: theme.textDim, fontSize: 10, width: 10 }, children: collapsed ? '▸' : '▾' }), _jsx("span", { style: { flex: 1, overflow: 'hidden', textOverflow: 'ellipsis' }, children: row.name }), _jsx("button", { className: "qe-hover", title: "Add system to this group", style: { ...iconButton, color: theme.accent, fontSize: 13 }, onClick: (e) => {
+                            }, children: groupSelected ? '☑' : '☐' })), _jsx("span", { className: "qe-hover", title: collapsed ? 'Expand' : 'Collapse', style: { color: theme.textDim, fontSize: 10, width: 10, cursor: 'pointer' }, onClick: (e) => {
+                                e.stopPropagation();
+                                onToggleCollapse?.();
+                            }, children: collapsed ? '▸' : '▾' }), _jsx("span", { style: { flex: 1, overflow: 'hidden', textOverflow: 'ellipsis' }, children: row.name }), _jsx("button", { className: "qe-hover", title: "Add system to this group", style: { ...iconButton, color: theme.accent, fontSize: 13 }, onClick: (e) => {
                                 e.stopPropagation();
                                 let created;
                                 binding.apply(() => {
@@ -45,7 +49,7 @@ export function TimelineTrackRow(props) {
                                 });
                                 if (created) {
                                     binding.addSubSystem(created);
-                                    onSelect(created);
+                                    onSelectNode(created.emitter);
                                 }
                             }, children: "+" }), !isRoot && (_jsx("button", { className: "qe-hover", title: "Rename", style: { ...iconButton, color: theme.textDim }, onClick: (e) => {
                                 e.stopPropagation();
@@ -55,9 +59,9 @@ export function TimelineTrackRow(props) {
                                 binding.apply(() => ungroupNode(row.node));
                             }, children: "\u26F6" })), !isRoot && (_jsx("button", { className: "qe-hover", title: "Remove group", style: { ...iconButton, color: '#e08c8c', fontSize: 12 }, onClick: (e) => {
                                 e.stopPropagation();
-                                removeSystems(binding, collectSystems(buildEffectTree(row.node)), onSelect);
+                                removeSystems(binding, collectSystems(buildEffectTree(row.node)), (s) => onSelectNode(s.emitter));
                                 binding.apply(() => row.node.dispose(true, false));
-                            }, children: "\u2715" }))] }), _jsx("div", { className: "qe-hover-bg", style: { height: ROW_HEIGHT, borderTop: `1px solid ${theme.border}` }, onClick: onToggleCollapse }), renaming && (_jsx(PromptDialog, { title: "Rename", defaultValue: row.name, onSubmit: (name) => {
+                            }, children: "\u2715" }))] }), _jsx("div", { className: "qe-hover-bg", style: { height: ROW_HEIGHT, borderTop: `1px solid ${theme.border}` }, onClick: () => onSelectNode(row.node) }), renaming && (_jsx(PromptDialog, { title: "Rename", defaultValue: row.name, onSubmit: (name) => {
                         binding.apply(() => (row.node.name = name));
                         setRenaming(false);
                     }, onCancel: () => setRenaming(false) }))] }));
@@ -65,7 +69,7 @@ export function TimelineTrackRow(props) {
     const { system } = row;
     const barLeft = offsetPx + row.startOffset * pxPerSecond;
     const barWidth = Math.max(2, row.duration * pxPerSecond);
-    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "qe-hover-bg", style: { ...labelStyle, opacity: hidden ? 0.5 : 1 }, onClick: () => onSelect(system), children: [!isRoot && (_jsx("button", { className: "qe-hover", title: groupSelected ? 'Remove from group selection' : 'Select for grouping', style: { ...checkboxButton, color: groupSelected ? theme.accent : theme.textDim }, onClick: (e) => {
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "qe-hover-bg", style: { ...labelStyle, opacity: hidden ? 0.5 : 1 }, onClick: () => onSelectNode(row.node), children: [!isRoot && (_jsx("button", { className: "qe-hover", title: groupSelected ? 'Remove from group selection' : 'Select for grouping', style: { ...checkboxButton, color: groupSelected ? theme.accent : theme.textDim }, onClick: (e) => {
                             e.stopPropagation();
                             onToggleGroupSelect();
                         }, children: groupSelected ? '☑' : '☐' })), _jsx("button", { className: "qe-hover", title: hidden ? 'Show in viewport' : 'Hide in viewport', style: { ...iconButton, color: hidden ? theme.textDim : theme.accent, fontSize: 12 }, onClick: (e) => {
@@ -76,7 +80,7 @@ export function TimelineTrackRow(props) {
                             setRenaming(true);
                         }, children: "\u270E" })), !isRoot && row.removable && (_jsx("button", { className: "qe-hover", title: "Remove system", style: { ...iconButton, color: '#e08c8c', fontSize: 12 }, onClick: (e) => {
                             e.stopPropagation();
-                            removeSystems(binding, [system], onSelect);
+                            removeSystems(binding, [system], (s) => onSelectNode(s.emitter));
                         }, children: "\u2715" })), selected && (_jsx("button", { className: "qe-hover", title: "Add child system", style: { ...iconButton, color: theme.accent, fontSize: 13 }, onClick: (e) => {
                             e.stopPropagation();
                             let created;
@@ -86,9 +90,9 @@ export function TimelineTrackRow(props) {
                             });
                             if (created) {
                                 binding.addSubSystem(created);
-                                onSelect(created);
+                                onSelectNode(created.emitter);
                             }
-                        }, children: "+" }))] }), _jsx("div", { className: "qe-hover-bg", style: { position: 'relative', height: ROW_HEIGHT }, onClick: () => onSelect(system), children: _jsx("div", { className: "qe-hover", title: row.startOffsetVariable ? 'Start time varies per spawn' : undefined, style: {
+                        }, children: "+" }))] }), _jsx("div", { className: "qe-hover-bg", style: { position: 'relative', height: ROW_HEIGHT }, onClick: () => onSelectNode(row.node), children: _jsx("div", { className: "qe-hover", title: row.startOffsetVariable ? 'Start time varies per spawn' : undefined, style: {
                         position: 'absolute',
                         left: barLeft,
                         width: barWidth,

package/dist/react/theme.js

@@ -54,25 +54,48 @@ export const buttonStyle = {
  *   rows), since brightening transparent does nothing. Must not be combined with an inline
  *   `background` on the same element or the tint would need `!important` to show through.
  */
-export const globalEditorStyles = `
-.qe-hover, .qe-hover-bg {
-    transition: filter 0.12s ease, background 0.12s ease;
-}
-.qe-hover:hover:not(:disabled) {
-    filter: brightness(1.3);
-}
-.qe-hover:active:not(:disabled) {
-    filter: brightness(0.85);
-}
-.qe-hover:disabled {
-    opacity: 0.45;
-    cursor: default;
-}
-.qe-hover-bg:hover {
-    background: rgba(255, 255, 255, 0.07);
-}
-select.qe-hover:hover, input.qe-hover:hover, select.qe-hover:focus, input.qe-hover:focus {
-    border-color: ${theme.borderActive};
-    filter: none;
-}
+export const globalEditorStyles = `
+.qe-hover, .qe-hover-bg {
+    transition: filter 0.12s ease, background 0.12s ease;
+}
+.qe-hover:hover:not(:disabled) {
+    filter: brightness(1.3);
+}
+.qe-hover:active:not(:disabled) {
+    filter: brightness(0.85);
+}
+.qe-hover:disabled {
+    opacity: 0.45;
+    cursor: default;
+}
+.qe-hover-bg:hover {
+    background: rgba(255, 255, 255, 0.07);
+}
+select.qe-hover:hover, input.qe-hover:hover, select.qe-hover:focus, input.qe-hover:focus {
+    border-color: ${theme.borderActive};
+    filter: none;
+}
+.qe-root, .qe-root * {
+    scrollbar-width: thin;
+    scrollbar-color: ${theme.border} transparent;
+}
+.qe-root ::-webkit-scrollbar {
+    width: 10px;
+    height: 10px;
+}
+.qe-root ::-webkit-scrollbar-track {
+    background: transparent;
+}
+.qe-root ::-webkit-scrollbar-thumb {
+    background-color: ${theme.border};
+    background-clip: padding-box;
+    border: 2px solid transparent;
+    border-radius: 8px;
+}
+.qe-root ::-webkit-scrollbar-thumb:hover {
+    background-color: ${theme.borderActive};
+}
+.qe-root ::-webkit-scrollbar-corner {
+    background: transparent;
+}
 `;