babylon.quarks-editor 0.26.0 → 0.28.0

package/dist/core/editorSession.js

@@ -0,0 +1,983 @@
+import { ArcRotateCamera } from '@babylonjs/core/Cameras/arcRotateCamera.js';
+// scene.pick lives in Ray's side effect (Babylon 9.31 no longer pulls it in); gizmos pick through it.
+import '@babylonjs/core/Culling/ray.js';
+import { PointerEventTypes } from '@babylonjs/core/Events/pointerEvents.js';
+import { GizmoManager } from '@babylonjs/core/Gizmos/gizmoManager.js';
+import { DirectionalLight } from '@babylonjs/core/Lights/directionalLight.js';
+import { Color3, Color4 } from '@babylonjs/core/Maths/math.color.js';
+import { Vector3 } from '@babylonjs/core/Maths/math.vector.js';
+import { MeshBuilder } from '@babylonjs/core/Meshes/meshBuilder.js';
+import { UtilityLayerRenderer } from '@babylonjs/core/Rendering/utilityLayerRenderer.js';
+import { Scene } from '@babylonjs/core/scene.js';
+import { GridMaterial } from '@babylonjs/materials/grid/gridMaterial.js';
+import { BatchedRenderer, QuarksUtil } from 'babylon.quarks';
+import { getAssetDragSession, setAssetDragSession } from './assetDragSession.js';
+import { describeAssetDrag, readAssetDrag } from './assetTree.js';
+import { createEffectAsset, loadEffectAssets, mergeAssets, removeAssets, } from './assets.js';
+import { createSceneDefaultEntry } from './defaultEffect.js';
+import { serializeEffectTree } from './effectTree.js';
+import { EmitterShapeWireframes } from './emitterShapeWireframe.js';
+import { GalleryDropMarker } from './galleryDropMarker.js';
+import { cancelGalleryCameraFocus, focusGalleryEntry } from './galleryLayout.js';
+import { applyGalleryPlayback, countGalleryParticles, hasActivePreview, pauseFinishedPreviews, } from './galleryPlayback.js';
+import { pickGroundPosition, placeSceneEntriesAt, setSceneEntryVisible } from './galleryScene.js';
+import { GallerySelectionMarker } from './gallerySelectionMarker.js';
+import { EffectHistory } from './history.js';
+import { parseEffectFromJson } from './loadEffect.js';
+import { clearFocusFinished, getFocusElapsed, isFocusFinished, markFocusFinished, setFocusElapsed, } from './playback.js';
+import { logRenderMismatch } from './renderDebug.js';
+import { bindingFromSceneEntry, disposeSceneEntry, instantiateSceneEntry } from './sceneEntries.js';
+import { pauseFocus, scrubFocusToSettled } from './scrub.js';
+import { computeTimelineRows, computeTimelineSpan } from './timeline.js';
+import { notifyTransformChanged, subscribeTransform } from './transformStore.js';
+import { GalleryViewportPicker } from './viewportPicker.js';
+const SCENE_SAVE_INFO_KEY = 'babylon.quarks-editor:scene-save-info-seen';
+function toStoredAsset(asset) {
+    return { path: asset.path, name: asset.name, json: asset.json, missingFiles: asset.missingFiles };
+}
+/** `Folder/Name` typed by the user → a clean asset path ending in `.json`. */
+export function normalizeAssetPath(input) {
+    const segments = input
+        .replace(/\\/g, '/')
+        .split('/')
+        .map((part) => part.trim())
+        .filter(Boolean);
+    const path = segments.join('/') || 'Effect';
+    return /\.json$/i.test(path) ? path : `${path}.json`;
+}
+/** Position of `node` in its effect tree (0 = root), to find the same node after a rebuild. */
+export function nodeIndexInEffect(root, node) {
+    if (!node || node === root)
+        return 0;
+    return root.getDescendants(false).indexOf(node) + 1;
+}
+/** The node at `index` in an effect tree, as {@link nodeIndexInEffect} counts; the root when out of range. */
+export function nodeAtIndex(root, index) {
+    if (index <= 0)
+        return root;
+    return root.getDescendants(false)[index - 1] ?? root;
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Builds the editor's scene on `options.engine`; call `start()` once the host is ready for callbacks. */
+export function createEditorSession(options) {
+    const { engine, playback } = options;
+    let disposed = false;
+    let started = false;
+    /** The host's view, silenced once the session is disposed; missing callbacks are no-ops. */
+    const view = new Proxy(options.view, {
+        get: (target, key) => {
+            const callback = Reflect.get(target, key);
+            return (...args) => {
+                if (!disposed && typeof callback === 'function') {
+                    callback.apply(target, args);
+                }
+            };
+        },
+    });
+    const canvas = engine.getRenderingCanvas();
+    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 Vector3(0, 1.4, 0), scene);
+    if (canvas) {
+        camera.attachControl(canvas, true);
+    }
+    camera.wheelDeltaPercentage = 0.01;
+    // Mesh render mode particles are lit (billboard modes ignore these); the grid is visual
+    // reference only and is not a physics collider.
+    scene.ambientColor = new Color3(1, 1, 1);
+    const sunLight = new DirectionalLight('sun', new Vector3(-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;
+    // Draw only the lines. Babylon < 9.31 did this by itself for opacity < 1; 9.31 needs the flag,
+    // or the whole plane is filled with the main color.
+    groundMaterial.linesOnly = true;
+    const ground = MeshBuilder.CreateGround('ground', { width: 100, height: 100 }, scene);
+    ground.material = groundMaterial;
+    const gizmoUtilityLayer = new UtilityLayerRenderer(scene);
+    const gizmoManager = new GizmoManager(scene, undefined, gizmoUtilityLayer);
+    gizmoManager.usePointerToAttachGizmos = false;
+    const renderer = new BatchedRenderer('quarks-editor', scene);
+    const history = new EffectHistory();
+    /** Undo/redo of effects that are not focused right now, by root uniqueId. */
+    const historyByRoot = new Map();
+    const dropMarker = new GalleryDropMarker(scene);
+    const selectionMarker = new GallerySelectionMarker(scene);
+    const emitterWireframes = new EmitterShapeWireframes(scene);
+    const viewportPicker = new GalleryViewportPicker(scene);
+    let binding = null;
+    let sceneEntries = [];
+    let visibleRootIds = [];
+    let assets = [];
+    let focusTimelineMeta = { rootId: -1, revision: -1, span: 1, anyLooping: false };
+    const handleViewportPointerLeave = () => viewportPicker.setHover(null);
+    canvas?.addEventListener('pointerleave', handleViewportPointerLeave);
+    const pointerObserver = scene.onPointerObservable.add((pointerInfo) => {
+        if (options.isAssetDragActive?.()) {
+            return;
+        }
+        const event = pointerInfo.event;
+        if (pointerInfo.type === PointerEventTypes.POINTERMOVE) {
+            const effectRoot = viewportPicker.pick(event.clientX, event.clientY);
+            const focused = binding?.root ?? null;
+            viewportPicker.setHover(effectRoot && effectRoot !== focused ? effectRoot : null);
+            return;
+        }
+        if (pointerInfo.type !== PointerEventTypes.POINTERDOWN || event.button !== 0) {
+            return;
+        }
+        const effectRoot = viewportPicker.pick(event.clientX, event.clientY);
+        if (!effectRoot) {
+            return;
+        }
+        const entry = sceneEntries.find((item) => item.root === effectRoot);
+        if (entry && binding?.root !== effectRoot) {
+            focusEntry(entry);
+        }
+        view.selectedNodeChanged(effectRoot);
+    });
+    const hideDropPreview = () => {
+        dropMarker.hide();
+        view.dragHoverChanged(null);
+    };
+    const clearDropPreview = () => {
+        hideDropPreview();
+        setAssetDragSession(null);
+    };
+    // ---- state commits ------------------------------------------------------------------
+    /**
+     * The open prefab, if any: its asset, and the scene set aside while it is edited. In prefab
+     * mode `sceneEntries` holds just the prefab's instance, so playback, picking, undo and the
+     * timeline all work on it unchanged.
+     */
+    let prefab = null;
+    let prefabChanged = false;
+    /** Scene changes since the last save; suppressed while a project scene loads. */
+    let dirty = false;
+    let loadingScene = Boolean(options.project);
+    const markDirty = () => {
+        if (prefab) {
+            if (!prefabChanged) {
+                prefabChanged = true;
+                view.prefabDirtyChanged(true);
+            }
+            return;
+        }
+        if (!loadingScene && !dirty) {
+            dirty = true;
+            view.sceneDirtyChanged(true);
+        }
+    };
+    const markClean = () => {
+        dirty = false;
+        view.sceneDirtyChanged(false);
+    };
+    const setPrefabClean = () => {
+        prefabChanged = false;
+        view.prefabDirtyChanged(false);
+    };
+    const unsubscribeTransform = subscribeTransform(markDirty);
+    /** Sets the entries and their visibility without marking the scene changed. */
+    const replaceEntries = (entries, visible) => {
+        sceneEntries = entries;
+        view.entriesChanged(entries);
+        visibleRootIds = visible;
+        view.visibleChanged(visible);
+    };
+    const commitEntries = (next) => {
+        sceneEntries = next;
+        view.entriesChanged(next);
+        markDirty();
+    };
+    const commitAssets = (next) => {
+        assets = next;
+        view.assetsChanged(next);
+    };
+    const commitVisible = (next) => {
+        visibleRootIds = next;
+        view.visibleChanged(next);
+        markDirty();
+    };
+    const onBindingChange = () => {
+        view.refresh();
+        markDirty();
+    };
+    const isVisible = (entry) => visibleRootIds.includes(entry.root.uniqueId);
+    const refreshPlayback = () => {
+        applyGalleryPlayback(sceneEntries, new Set(visibleRootIds), playback.stagePlaying, playback.focusFinishedByRoot);
+        renderer.refreshBatches();
+        scene.render();
+        view.refresh();
+    };
+    // ---- focus ----------------------------------------------------------------------------
+    const setFocus = (next) => {
+        binding = next;
+        view.bindingChanged(next);
+    };
+    const attachBinding = (next) => {
+        const previous = binding;
+        if (previous && !previous.root.isDisposed()) {
+            historyByRoot.set(previous.root.uniqueId, history.saveStacks());
+        }
+        history.restoreStacks(next ? historyByRoot.get(next.root.uniqueId) : undefined);
+        if (next) {
+            history.attach(next);
+            next.subscribe(onBindingChange);
+        }
+        setFocus(next);
+    };
+    const focusEntry = (entry, moveCamera = true) => {
+        attachBinding(entry ? bindingFromSceneEntry(entry) : null);
+        view.selectedNodeChanged(entry?.root ?? null);
+        view.focusedRootChanged(entry?.root ?? null);
+        playback.focusRootId = entry?.root.uniqueId ?? null;
+        if (entry && isVisible(entry)) {
+            selectionMarker.show(entry.root);
+            if (moveCamera) {
+                focusGalleryEntry(camera, entry.root);
+            }
+        }
+        else {
+            selectionMarker.hide();
+        }
+        view.ready(makeHandle());
+    };
+    // ---- scene entries ------------------------------------------------------------------
+    /** Adds entries to the scene (visible) and focuses the first. */
+    const addEntries = (entries, center) => {
+        if (entries.length === 0) {
+            return;
+        }
+        placeSceneEntriesAt(entries, center);
+        for (const entry of entries) {
+            entry.root.setEnabled(true);
+        }
+        commitEntries([...sceneEntries, ...entries]);
+        commitVisible([...visibleRootIds, ...entries.map((entry) => entry.root.uniqueId)]);
+        focusEntry(entries[0], false);
+        refreshPlayback();
+    };
+    const refuseInPrefabMode = () => {
+        if (!prefab)
+            return false;
+        view.toast('Effects go into the scene — go back to the scene (← Scene) to add them');
+        return true;
+    };
+    const cameraGroundTarget = () => new Vector3(camera.target.x, 0, camera.target.z);
+    const instantiateAssets = (toPlace, center) => {
+        if (refuseInPrefabMode()) {
+            return;
+        }
+        const created = [];
+        for (const asset of toPlace) {
+            try {
+                const entry = instantiateSceneEntry(scene, renderer, asset, [...sceneEntries, ...created]);
+                if (entry) {
+                    created.push(entry);
+                }
+            }
+            catch (err) {
+                console.warn(`[Quarks editor] Could not instantiate "${asset.path}":`, err);
+            }
+        }
+        if (created.length < toPlace.length) {
+            view.message('Add to scene', `${toPlace.length - created.length} of ${toPlace.length} effect(s) could not be loaded — see the console.`);
+        }
+        addEntries(created, center);
+    };
+    const toggleVisible = (entry) => {
+        const id = entry.root.uniqueId;
+        const show = !isVisible(entry);
+        setSceneEntryVisible(entry, renderer, show);
+        clearFocusFinished(playback, id);
+        commitVisible(show ? [...visibleRootIds, id] : visibleRootIds.filter((rootId) => rootId !== id));
+        if (binding?.root === entry.root) {
+            if (show) {
+                selectionMarker.show(entry.root);
+            }
+            else {
+                selectionMarker.hide();
+            }
+        }
+        refreshPlayback();
+    };
+    /** Entry shown alone, and the entries solo hid (shown again when it ends). */
+    let solo = null;
+    const exitSolo = () => {
+        if (!solo) {
+            return;
+        }
+        const hidden = new Set(solo.hidden);
+        solo = null;
+        view.soloChanged(null);
+        const toShow = sceneEntries.filter((entry) => hidden.has(entry.root.uniqueId) && !isVisible(entry));
+        for (const entry of toShow) {
+            setSceneEntryVisible(entry, renderer, true);
+            clearFocusFinished(playback, entry.root.uniqueId);
+        }
+        commitVisible([...visibleRootIds, ...toShow.map((entry) => entry.root.uniqueId)]);
+    };
+    const toggleSolo = (entry) => {
+        if (prefab)
+            return;
+        const id = entry.root.uniqueId;
+        const wasSolo = solo?.rootId === id;
+        exitSolo();
+        if (!wasSolo) {
+            const others = sceneEntries.filter((item) => item !== entry && isVisible(item));
+            for (const other of others) {
+                setSceneEntryVisible(other, renderer, false);
+            }
+            const hiddenIds = others.map((other) => other.root.uniqueId);
+            const visible = visibleRootIds.filter((rootId) => !hiddenIds.includes(rootId));
+            if (!visible.includes(id)) {
+                setSceneEntryVisible(entry, renderer, true);
+                visible.push(id);
+            }
+            commitVisible(visible);
+            solo = { rootId: id, hidden: hiddenIds };
+            view.soloChanged(id);
+            if (binding?.root !== entry.root) {
+                focusEntry(entry);
+            }
+            else {
+                selectionMarker.show(entry.root);
+                focusGalleryEntry(camera, entry.root);
+            }
+        }
+        refreshPlayback();
+    };
+    const deleteEntry = (entry) => {
+        if (prefab)
+            return;
+        const index = sceneEntries.indexOf(entry);
+        if (index < 0) {
+            return;
+        }
+        const id = entry.root.uniqueId;
+        if (solo?.rootId === id) {
+            exitSolo();
+        }
+        const wasFocused = binding?.root === entry.root;
+        if (wasFocused) {
+            selectionMarker.hide();
+        }
+        disposeSceneEntry(entry, renderer);
+        const remaining = sceneEntries.filter((item) => item !== entry);
+        commitEntries(remaining);
+        commitVisible(visibleRootIds.filter((rootId) => rootId !== id));
+        clearFocusFinished(playback, id);
+        playback.focusElapsedByRoot.delete(id);
+        if (wasFocused) {
+            focusEntry(remaining[Math.min(index, remaining.length - 1)] ?? null, false);
+        }
+        historyByRoot.delete(id);
+        refreshPlayback();
+    };
+    const deleteFocused = () => {
+        const entry = sceneEntries.find((item) => item.root === binding?.root);
+        if (!entry || prefab) {
+            return false;
+        }
+        deleteEntry(entry);
+        return true;
+    };
+    const createDefault = () => {
+        if (refuseInPrefabMode()) {
+            return;
+        }
+        const entry = createSceneDefaultEntry(scene, sceneEntries, {
+            resolveTexture: options.resolveTexture,
+            textureUrl: options.defaultTextureUrl,
+        });
+        for (const system of entry.systems) {
+            renderer.addSystem(system);
+        }
+        addEntries([entry], cameraGroundTarget());
+    };
+    // ---- assets ---------------------------------------------------------------------------
+    const previewDrop = (clientX, clientY) => {
+        const payload = getAssetDragSession();
+        if (!payload)
+            return;
+        const described = describeAssetDrag(assets, payload);
+        if (described.assets.length === 0)
+            return;
+        dropMarker.show(pickGroundPosition(scene, clientX, clientY), described.assets.length);
+        view.dragHoverChanged({ label: described.label, count: described.assets.length });
+    };
+    const placeDrop = (clientX, clientY, dataTransfer) => {
+        const payload = (dataTransfer && readAssetDrag(dataTransfer)) ?? getAssetDragSession();
+        clearDropPreview();
+        if (!payload) {
+            return;
+        }
+        const { assets: toPlace } = describeAssetDrag(assets, payload);
+        instantiateAssets(toPlace, pickGroundPosition(scene, clientX, clientY));
+    };
+    const addToScene = (payload) => {
+        const { assets: toPlace } = describeAssetDrag(assets, payload);
+        instantiateAssets(toPlace, cameraGroundTarget());
+    };
+    /** Writes asset changes through to the project; failures are reported, not thrown. */
+    const persist = (action) => {
+        const project = options.project;
+        if (!project)
+            return;
+        action(project.store, project.id).catch((err) => {
+            console.error('[Quarks editor] Could not save to the project:', err);
+            view.message('Project storage', errorText(err));
+        });
+    };
+    const deleteAssets = (payload) => {
+        const next = removeAssets(assets, payload);
+        const removed = assets.filter((asset) => !next.includes(asset)).map((asset) => asset.path);
+        commitAssets(next);
+        persist((store, id) => store.deleteAssets(id, removed));
+    };
+    const importAssets = async (files) => {
+        view.assetsLoadingChanged({ done: 0, total: 0, loaded: 0, failed: 0 });
+        let incoming;
+        try {
+            incoming = await loadEffectAssets(files, (progress) => view.assetsLoadingChanged(progress));
+        }
+        finally {
+            view.assetsLoadingChanged(null);
+        }
+        if (disposed)
+            return;
+        const { merged, added } = mergeAssets(assets, incoming);
+        commitAssets(merged);
+        view.assetsRevealed();
+        if (added.length > 0) {
+            persist((store, id) => store.putAssets(id, added.map(toStoredAsset)));
+        }
+        if (incoming.length === 0) {
+            throw new Error('No particle effects found in the selected file(s).');
+        }
+        if (added.length === 0) {
+            throw new Error('All selected effects are already in Assets.');
+        }
+    };
+    /** New asset at `rawPath` (`Folder/Name`, a free path — never overwrites) from an effect tree. */
+    const createAssetFromRoot = (root, rawPath) => {
+        const taken = new Set(assets.map((asset) => asset.path));
+        const wanted = normalizeAssetPath(rawPath);
+        let path = wanted;
+        for (let n = 2; taken.has(path); n++) {
+            path = wanted.replace(/\.json$/i, ` ${n}.json`);
+        }
+        const name = path
+            .split('/')
+            .pop()
+            .replace(/\.json$/i, '');
+        const asset = createEffectAsset(name, path, JSON.parse(serializeEffectTree(root, name)));
+        commitAssets([...assets, asset]);
+        persist((store, id) => store.putAssets(id, [toStoredAsset(asset)]));
+        return asset;
+    };
+    const saveEntryAsAsset = (entry, rawPath) => {
+        const asset = createAssetFromRoot(entry.root, rawPath);
+        entry.assetId = asset.id;
+        entry.path = asset.path;
+        commitEntries([...sceneEntries]);
+        view.assetsRevealed();
+        view.toast(`Saved as asset “${asset.path.replace(/\.json$/i, '')}”`);
+    };
+    // ---- prefab mode ------------------------------------------------------------------------
+    /** Scene instances made from the open prefab — they keep their own copy when it is saved. */
+    const prefabInstanceCount = () => prefab ? prefab.stash.entries.filter((entry) => entry.assetId === prefab.asset.id).length : 0;
+    /** Drops the prefab instance(s) currently in `sceneEntries`, with their history. */
+    const disposePrefabInstances = () => {
+        for (const entry of sceneEntries) {
+            const id = entry.root.uniqueId;
+            disposeSceneEntry(entry, renderer);
+            historyByRoot.delete(id);
+            clearFocusFinished(playback, id);
+            playback.focusElapsedByRoot.delete(id);
+        }
+    };
+    /** Shows `entry` as the open prefab's only instance, with `asset` as the prefab. */
+    const showPrefab = (asset, entry) => {
+        setPrefabClean();
+        view.prefabChanged({ name: asset.name, path: asset.path });
+        entry.root.setEnabled(true);
+        replaceEntries([entry], [entry.root.uniqueId]);
+        focusEntry(entry);
+        refreshPlayback();
+    };
+    /**
+     * Opens an asset as a prefab. With another prefab open it is swapped in place — the scene stays
+     * set aside — after asking about unsaved edits unless `discardChanges`.
+     */
+    const openPrefab = (assetId, discardChanges = false) => {
+        if (prefab?.asset.id === assetId) {
+            return;
+        }
+        const asset = assets.find((item) => item.id === assetId);
+        if (!asset)
+            return;
+        if (prefab && prefabChanged && !discardChanges) {
+            view.prefabSwitchRequested({ id: asset.id, name: asset.name });
+            return;
+        }
+        let entry = null;
+        try {
+            entry = instantiateSceneEntry(scene, renderer, asset, []);
+        }
+        catch (err) {
+            console.warn(`[Quarks editor] Could not open prefab "${asset.path}":`, err);
+        }
+        if (!entry) {
+            view.message('Open prefab', `“${asset.name}” has no particle systems to edit.`);
+            return;
+        }
+        if (prefab) {
+            selectionMarker.hide();
+            disposePrefabInstances();
+            prefab.asset = asset;
+            showPrefab(asset, entry);
+            return;
+        }
+        exitSolo();
+        const stash = {
+            entries: sceneEntries,
+            visible: visibleRootIds,
+            focusedRoot: binding?.root ?? null,
+            camera: { target: camera.target.clone(), radius: camera.radius, alpha: camera.alpha, beta: camera.beta },
+        };
+        // Hide the scene without touching its saved visibility.
+        for (const item of stash.entries) {
+            if (stash.visible.includes(item.root.uniqueId)) {
+                setSceneEntryVisible(item, renderer, false);
+            }
+        }
+        selectionMarker.hide();
+        prefab = { asset, stash };
+        showPrefab(asset, entry);
+    };
+    /** Leaves prefab mode without saving: drops the prefab instance and brings the scene back. */
+    const closePrefab = () => {
+        if (!prefab)
+            return;
+        const { stash } = prefab;
+        prefab = null;
+        selectionMarker.hide();
+        disposePrefabInstances();
+        replaceEntries(stash.entries, stash.visible);
+        for (const entry of stash.entries) {
+            if (stash.visible.includes(entry.root.uniqueId)) {
+                setSceneEntryVisible(entry, renderer, true);
+                clearFocusFinished(playback, entry.root.uniqueId);
+            }
+        }
+        cancelGalleryCameraFocus();
+        camera.setTarget(stash.camera.target);
+        camera.radius = stash.camera.radius;
+        camera.alpha = stash.camera.alpha;
+        camera.beta = stash.camera.beta;
+        setPrefabClean();
+        view.prefabChanged(null);
+        focusEntry(stash.entries.find((entry) => entry.root === stash.focusedRoot) ?? null, false);
+        refreshPlayback();
+    };
+    /** Overwrites the open prefab's asset with the edited instance. Scene instances keep theirs. */
+    const overwritePrefab = () => {
+        const root = sceneEntries[0]?.root;
+        if (!prefab || !root)
+            return;
+        const updated = {
+            ...prefab.asset,
+            json: JSON.parse(serializeEffectTree(root, prefab.asset.name)),
+        };
+        const exists = assets.some((asset) => asset.id === updated.id);
+        commitAssets(exists ? assets.map((asset) => (asset.id === updated.id ? updated : asset)) : [...assets, updated]);
+        persist((store, id) => store.putAssets(id, [toStoredAsset(updated)]));
+        prefab.asset = updated;
+        setPrefabClean();
+        view.toast(`Prefab “${updated.name}” saved · scene unchanged`);
+    };
+    /** Saves the edited prefab as a new asset and keeps editing that one. */
+    const savePrefabAsNew = (rawPath) => {
+        const root = sceneEntries[0]?.root;
+        if (!prefab || !root)
+            return;
+        const asset = createAssetFromRoot(root, rawPath);
+        prefab.asset = asset;
+        setPrefabClean();
+        view.prefabChanged({ name: asset.name, path: asset.path });
+        view.toast(`Saved as new prefab “${asset.path.replace(/\.json$/i, '')}”`);
+    };
+    // ---- project scene ----------------------------------------------------------------------
+    /** Saves the scene to the project; resolves to false when it could not. */
+    const saveScene = async () => {
+        const project = options.project;
+        if (!project || prefab)
+            return false;
+        const visibleIds = new Set(visibleRootIds);
+        const assetPathById = new Map(assets.map((asset) => [asset.id, asset.path]));
+        const stored = {
+            savedAt: Date.now(),
+            entries: sceneEntries.map((entry) => ({
+                name: entry.name,
+                assetPath: entry.assetId != null ? (assetPathById.get(entry.assetId) ?? null) : null,
+                json: JSON.parse(serializeEffectTree(entry.root, entry.name)),
+                visible: visibleIds.has(entry.root.uniqueId),
+            })),
+        };
+        try {
+            await project.store.saveScene(project.id, stored);
+        }
+        catch (err) {
+            console.error('[Quarks editor] Could not save the scene:', err);
+            view.message('Save scene', errorText(err));
+            return false;
+        }
+        markClean();
+        let infoSeen = true;
+        try {
+            infoSeen = localStorage.getItem(SCENE_SAVE_INFO_KEY) === '1';
+            localStorage.setItem(SCENE_SAVE_INFO_KEY, '1');
+        }
+        catch {
+            // Storage blocked — fall back to the toast.
+        }
+        if (infoSeen) {
+            view.toast('Scene saved · assets unchanged');
+        }
+        else {
+            view.message('Scene saved', 'Saving the scene stores the effects placed in it, with their own edits.\n\n' +
+                'It does not change the assets they came from. To keep an edited effect as an asset, ' +
+                'right-click it in the Scene list → “Save as new asset…”.');
+        }
+        return true;
+    };
+    const loadProject = async (project) => {
+        try {
+            const [storedAssets, storedScene] = await Promise.all([
+                project.store.loadAssets(project.id),
+                project.store.loadScene(project.id),
+            ]);
+            if (disposed)
+                return;
+            const loadedAssets = storedAssets.map((stored) => ({
+                ...createEffectAsset(stored.name, stored.path, stored.json),
+                missingFiles: stored.missingFiles,
+            }));
+            commitAssets(loadedAssets);
+            const assetIdByPath = new Map(loadedAssets.map((asset) => [asset.path, asset.id]));
+            if (!storedScene) {
+                createDefault();
+                return;
+            }
+            const created = [];
+            const visible = [];
+            for (const stored of storedScene.entries) {
+                const entry = instantiateSceneEntry(scene, renderer, { id: -1, name: stored.name, path: stored.assetPath ?? '', json: stored.json, missingFiles: [] }, created);
+                if (!entry)
+                    continue;
+                entry.name = stored.name;
+                entry.root.name = stored.name;
+                entry.assetId = stored.assetPath != null ? (assetIdByPath.get(stored.assetPath) ?? null) : null;
+                entry.path = stored.assetPath ?? `_created/${stored.name}.json`;
+                setSceneEntryVisible(entry, renderer, stored.visible);
+                if (stored.visible)
+                    visible.push(entry.root.uniqueId);
+                created.push(entry);
+            }
+            commitEntries(created);
+            commitVisible(visible);
+            focusEntry(created[0] ?? null, false);
+            refreshPlayback();
+        }
+        catch (err) {
+            console.error('[Quarks editor] Could not open the project:', err);
+            view.message('Open project', errorText(err));
+        }
+        finally {
+            loadingScene = false;
+            markClean();
+            view.projectLoaded();
+        }
+    };
+    // ---- undo / redo ----------------------------------------------------------------------
+    /** Rebuilds the focused entry from a history snapshot, in place in the scene list. */
+    const historyStep = (redo) => {
+        const current = binding;
+        if (!current) {
+            return;
+        }
+        const json = redo ? history.redo() : history.undo();
+        const index = sceneEntries.findIndex((entry) => entry.root === current.root);
+        const prev = index >= 0 ? sceneEntries[index] : null;
+        if (!json || !prev) {
+            view.refresh();
+            return;
+        }
+        const selectedIndex = nodeIndexInEffect(current.root, options.getSelectedNode?.() ?? null);
+        const visible = isVisible(prev);
+        const { root, systems } = parseEffectFromJson(scene, renderer, json, {
+            registerRenderer: true,
+            autoplay: false,
+        });
+        if (systems.length === 0) {
+            disposeSceneEntry({ ...prev, root, systems }, renderer);
+            view.refresh();
+            return;
+        }
+        disposeSceneEntry(prev, renderer);
+        // The snapshot carries the root transform too, so a moved effect moves back.
+        root.parent = null;
+        root.name = prev.name;
+        const nextEntry = { ...prev, root, systems };
+        setSceneEntryVisible(nextEntry, renderer, visible);
+        const entries = [...sceneEntries];
+        entries[index] = nextEntry;
+        commitEntries(entries);
+        commitVisible(visibleRootIds.map((id) => (id === prev.root.uniqueId ? root.uniqueId : id)));
+        if (solo) {
+            if (solo.rootId === prev.root.uniqueId) {
+                solo.rootId = root.uniqueId;
+                view.soloChanged(root.uniqueId);
+            }
+            solo.hidden = solo.hidden.map((id) => (id === prev.root.uniqueId ? root.uniqueId : id));
+        }
+        const next = bindingFromSceneEntry(nextEntry);
+        history.attach(next);
+        next.subscribe(onBindingChange);
+        setFocus(next);
+        view.selectedNodeChanged(nodeAtIndex(root, selectedIndex));
+        view.focusedRootChanged(root);
+        playback.focusRootId = root.uniqueId;
+        if (visible) {
+            selectionMarker.show(root);
+        }
+        notifyTransformChanged();
+        refreshPlayback();
+    };
+    // ---- handle -----------------------------------------------------------------------------
+    const makeHandle = () => ({
+        get binding() {
+            if (!binding) {
+                throw new Error('No effect is focused — add one to the scene first.');
+            }
+            return binding;
+        },
+        history,
+        scene,
+        renderer,
+        importJson,
+        importAssets,
+        importGallery: importAssets,
+        exportJson: () => makeHandle().binding.exportJSON('EditorEffect'),
+    });
+    /** Adds `json` to Assets and returns its single instance; throws when it has no systems. */
+    const openJson = (json, name = 'Effect') => {
+        const asset = createEffectAsset(name, `_opened/${name}.json`, json);
+        const entry = instantiateSceneEntry(scene, renderer, asset, sceneEntries);
+        if (!entry) {
+            throw new Error('No particle systems found in the JSON.');
+        }
+        asset.name = entry.name;
+        asset.path = `_opened/${entry.name}.json`;
+        commitAssets([...assets, asset]);
+        return entry;
+    };
+    const importJson = (json) => {
+        closePrefab();
+        const entry = openJson(json);
+        for (const existing of sceneEntries) {
+            disposeSceneEntry(existing, renderer);
+        }
+        historyByRoot.clear();
+        solo = null;
+        view.soloChanged(null);
+        commitEntries([]);
+        commitVisible([]);
+        addEntries([entry], Vector3.Zero());
+    };
+    // ---- frame ------------------------------------------------------------------------------
+    const renderFrame = () => {
+        const entries = sceneEntries;
+        const visibleIds = new Set(visibleRootIds);
+        const focusBinding = binding;
+        if (!playback.scrubbing) {
+            let delta = (engine.getDeltaTime() / 1000) * playback.speed;
+            const stepQueued = playback.stepQueued;
+            if (!playback.stagePlaying) {
+                delta = stepQueued ? 1 / 60 : 0;
+                playback.stepQueued = false;
+            }
+            if (delta > 0) {
+                const simulate = hasActivePreview(entries, visibleIds) && (playback.stagePlaying || stepQueued);
+                if (simulate) {
+                    renderer.update(delta);
+                    let needsRefresh = false;
+                    if (pauseFinishedPreviews(entries, visibleIds, playback.focusFinishedByRoot)) {
+                        needsRefresh = true;
+                    }
+                    const focusId = playback.focusRootId ?? focusBinding?.root.uniqueId ?? null;
+                    if (focusId != null &&
+                        focusBinding &&
+                        playback.stagePlaying &&
+                        !playback.focusFinishedByRoot.has(focusId) &&
+                        !focusTimelineMeta.anyLooping &&
+                        QuarksUtil.isEffectFinished(focusBinding.root)) {
+                        const settleAt = getFocusElapsed(playback, focusId);
+                        scrubFocusToSettled(focusBinding, renderer, settleAt);
+                        markFocusFinished(playback, focusId);
+                        pauseFocus(focusBinding);
+                        needsRefresh = true;
+                    }
+                    else if (focusId != null && playback.stagePlaying && !playback.focusFinishedByRoot.has(focusId)) {
+                        const prev = getFocusElapsed(playback, focusId);
+                        setFocusElapsed(playback, focusId, prev + delta);
+                    }
+                    if (needsRefresh) {
+                        renderer.refreshBatches();
+                    }
+                    logRenderMismatch(renderer, countGalleryParticles(entries, visibleIds));
+                }
+                else if (entries.length > 0) {
+                    renderer.refreshBatches();
+                }
+            }
+        }
+        scene.render();
+        selectionMarker.follow();
+        viewportPicker.follow();
+        if (focusBinding) {
+            emitterWireframes.sync([focusBinding.system, ...focusBinding.subSystems], `${focusBinding.root.uniqueId}:${focusBinding.getRevision()}`);
+        }
+        const pickKey = entries
+            .map((entry) => `${entry.root.uniqueId}:${visibleIds.has(entry.root.uniqueId) ? 1 : 0}`)
+            .join('|');
+        viewportPicker.sync(entries, null, `${pickKey}::${focusBinding?.root.uniqueId ?? 'none'}`);
+        if (focusBinding &&
+            (focusBinding.root.uniqueId !== focusTimelineMeta.rootId ||
+                focusBinding.getRevision() !== focusTimelineMeta.revision)) {
+            const rows = computeTimelineRows(focusBinding);
+            focusTimelineMeta = {
+                rootId: focusBinding.root.uniqueId,
+                revision: focusBinding.getRevision(),
+                span: computeTimelineSpan(rows),
+                anyLooping: rows.some((row) => row.kind === 'track' && row.looping),
+            };
+        }
+        const count = countGalleryParticles(entries, visibleIds);
+        const focused = entries.find((entry) => entry.root === focusBinding?.root);
+        const focusId = playback.focusRootId ?? focused?.root.uniqueId ?? null;
+        const focusElapsed = focusId != null ? getFocusElapsed(playback, focusId) : 0;
+        const focusEnded = focusId != null && isFocusFinished(playback, focusId);
+        const meta = focusTimelineMeta;
+        const timeLabel = meta.anyLooping
+            ? `${focusElapsed.toFixed(1)}s ⟳`
+            : focusEnded
+                ? `${focusElapsed.toFixed(1)}s / ${meta.span.toFixed(1)}s (end)`
+                : `${focusElapsed.toFixed(1)}s / ${meta.span.toFixed(1)}s`;
+        view.frame({
+            fps: Math.round(engine.getFps()),
+            counter: focused ? `${timeLabel} · ${count} particles` : `${count} particles`,
+        });
+    };
+    const syncPlayback = () => {
+        applyGalleryPlayback(sceneEntries, new Set(visibleRootIds), playback.stagePlaying, playback.focusFinishedByRoot);
+        if (!playback.stagePlaying) {
+            renderer.refreshBatches();
+        }
+    };
+    const start = () => {
+        if (started || disposed)
+            return;
+        started = true;
+        if (options.project) {
+            void loadProject(options.project);
+        }
+        else if (options.effectJson) {
+            addEntries([openJson(options.effectJson)], Vector3.Zero());
+        }
+        else {
+            createDefault();
+        }
+        engine.runRenderLoop(renderFrame);
+    };
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        unsubscribeTransform();
+        clearDropPreview();
+        cancelGalleryCameraFocus();
+        dropMarker.dispose();
+        selectionMarker.dispose();
+        emitterWireframes.dispose();
+        viewportPicker.dispose();
+        canvas?.removeEventListener('pointerleave', handleViewportPointerLeave);
+        scene.onPointerObservable.remove(pointerObserver);
+        gizmoManager.dispose();
+        gizmoUtilityLayer.dispose();
+        engine.stopRenderLoop(renderFrame);
+        scene.dispose();
+    };
+    return {
+        engine,
+        scene,
+        camera,
+        ground,
+        renderer,
+        history,
+        gizmoManager,
+        get binding() {
+            return binding;
+        },
+        get sceneEntries() {
+            return sceneEntries;
+        },
+        get visibleRootIds() {
+            return visibleRootIds;
+        },
+        get assets() {
+            return assets;
+        },
+        get isPrefabOpen() {
+            return prefab !== null;
+        },
+        importAssets,
+        importJson,
+        focusEntry,
+        toggleVisible,
+        toggleSolo,
+        deleteEntry,
+        deleteFocused,
+        createDefault,
+        previewDrop,
+        placeDrop,
+        hideDropPreview,
+        clearDropPreview,
+        setEmitterWireframesVisible: (visible) => emitterWireframes.setVisible(visible),
+        addToScene,
+        deleteAssets,
+        saveEntryAsAsset,
+        saveScene,
+        openPrefab,
+        overwritePrefab,
+        savePrefabAsNew,
+        closePrefab,
+        prefabInstanceCount,
+        historyStep,
+        syncPlayback,
+        makeHandle,
+        start,
+        dispose,
+    };
+}