babylon.quarks-editor 0.17.8 → 0.17.9

package/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to the `babylon.quarks-editor` package are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project follows the `quarks.core` 0.x version line.
 
+## [0.17.9] — 2026-07-14
+
+### Added
+
+- **Effect gallery** — catalog panel with folder import, virtualized tree, drag-and-drop into
+  the viewport, and multi-effect scene layout.
+- **Preview set vs focus** — checkbox / Ctrl+click adds effects to stage preview; click selects
+  one effect for the inspector and timeline (Unity-style).
+- **Stage vs focus playback** — stage Play/Pause drives all preview effects; timeline
+  playhead/scrub/restart apply only to the focused effect. One-shot focus parks at the end
+  without stopping looping previews.
+- `core/playback.ts` — decoupled `stagePlaying`, per-root `focusElapsed`, and `focusFinished`
+  state.
+- `scrubFocusTo()` — scrubs only the focused binding via `system.update()` without advancing
+  other previews through the shared renderer.
+- Gallery scene helpers — drop marker, selection marker, emitter-shape wireframes, camera
+  focus on select.
+- **Inspector tooltips** — info icons on module titles and field labels with English
+  descriptions (`inspectorHints.ts`); themed portal tooltips (`Tooltip` / `InspectorInfoIcon`).
+- `pickGalleryJsonFiles()` — native folder picker via File System Access API when available.
+- `MessageDialog`, Heroicons-based toolbar/gallery icons, `@tanstack/react-virtual` for the
+  gallery list.
+
+### Changed
+
+- `EffectEditorHost` — gallery state, preview set, transport counter, render loop wired to
+  the new playback model.
+- `TimelinePanel` — stage transport controls, focus-only restart/scrub, catalog-only disabled
+  state with drop hint.
+- `galleryPlayback` — `play()` on all systems in preview entries (including sub-emitters).
+- `binding.restart()` — also calls `play()` on sub-emitter systems.
+- `RendererModule` — material metadata display and patch helpers; timeline span uses duration
+  only (no particle-life tail).
+- Burst editor rows in Emission module use shared `Row` layout with tooltips.
+
+### Fixed
+
+- Finishing a one-shot **focused** effect no longer pauses looping effects in the preview set.
+- `pickGalleryFiles.ts` — TypeScript typing for directory `entries()` without invalid
+  `extends FileSystemDirectoryHandle` override.
+
+### Related: Unity exporter 0.2.0
+
+- Batch **Export Folder of Effects to JSON** pairs with the editor gallery folder import
+  (export a tree of prefabs in Unity → import the folder in the effect editor catalog).
+
 ## [0.17.7] — 2026-07-09
 
 ### Added

package/README.md

@@ -7,7 +7,7 @@ Shuriken-style effect editor for [babylon.quarks](https://www.npmjs.com/package/
 ## Install
 
 ```bash
-npm install babylon.quarks-editor babylon.quarks @babylonjs/core react
+npm install babylon.quarks-editor babylon.quarks @babylonjs/core react @heroicons/react @tanstack/react-virtual
 ```
 
 ## Usage

package/dist/core/binding.js

@@ -63,13 +63,10 @@ export class EffectBinding {
         }
     }
     restart() {
-        // Replay every independent system; sub-emitter targets (onlyUsedByOther) are only
-        // reset — their parents re-drive them, so playing them directly would double-emit.
+        // onlyUsedByOther systems skip self-emission in update(); play() only unpauses sim.
         for (const system of [this.system, ...this.subSystems]) {
             system.restart();
-            if (!system.onlyUsedByOther) {
-                system.play();
-            }
+            system.play();
         }
     }
     /**

package/dist/core/defaultEffect.d.ts

@@ -0,0 +1,12 @@
+import type { Scene } from '@babylonjs/core/scene';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { ParticleSystem } from 'babylon.quarks';
+import type { GalleryEntry } from './loadEffectGallery';
+export interface CreateGalleryDefaultOptions {
+    resolveTexture?: (url: string, scene: Scene) => unknown;
+    textureUrl?: string;
+}
+/** Creates a simple cone burst preset for new editor effects. */
+export declare function createDefaultEffect(scene: Scene, resolveTexture?: (url: string, scene: Scene) => unknown, textureUrl?: string): ParticleSystem;
+/** Adds a blank preset effect to the hidden gallery catalog (not in the renderer yet). */
+export declare function createGalleryDefaultEntry(scene: Scene, catalogRoot: TransformNode, existing: GalleryEntry[], options?: CreateGalleryDefaultOptions): GalleryEntry;

package/dist/core/defaultEffect.js

@@ -0,0 +1,43 @@
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { ColorOverLife, ConeEmitter, ConstantColor, ConstantValue, IntervalValue, ParticleSystem, RenderMode, Vector4, } from 'babylon.quarks';
+import { DEFAULT_GRADIENT_STOPS, buildGradient } from './colors';
+/** Creates a simple cone burst preset for new editor effects. */
+export 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),
+        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)));
+    system.emitter.rotation.x = -Math.PI / 2;
+    return system;
+}
+/** Adds a blank preset effect to the hidden gallery catalog (not in the renderer yet). */
+export function createGalleryDefaultEntry(scene, catalogRoot, existing, options = {}) {
+    const takenNames = new Set(existing.map((entry) => entry.name));
+    const takenPaths = new Set(existing.map((entry) => entry.path));
+    let name = existing.length === 0 ? 'Effect' : 'New Effect';
+    let suffix = 2;
+    while (takenNames.has(name) || takenPaths.has(`_created/${name}.json`)) {
+        name = `New Effect ${suffix}`;
+        suffix++;
+    }
+    const path = `_created/${name}.json`;
+    const system = createDefaultEffect(scene, options.resolveTexture, options.textureUrl);
+    system.pause();
+    const root = new TransformNode(name, scene);
+    system.emitter.parent = root;
+    root.parent = catalogRoot;
+    root.setEnabled(false);
+    return { name, path, root, systems: [system], inScene: false };
+}

package/dist/core/editorScene.d.ts

@@ -0,0 +1,7 @@
+import type { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+/** Marks meshes/nodes created only for editor interaction or overlays (not part of the effect). */
+export declare const EDITOR_SCENE_NODE_METADATA: {
+    quarksEditorSceneNode: true;
+};
+/** True for viewport pick proxies, shape wireframes, and other non-exportable scene helpers. */
+export declare function isEditorSceneNode(node: TransformNode): boolean;

package/dist/core/editorScene.js

@@ -0,0 +1,11 @@
+/** Marks meshes/nodes created only for editor interaction or overlays (not part of the effect). */
+export const EDITOR_SCENE_NODE_METADATA = { quarksEditorSceneNode: true };
+/** True for viewport pick proxies, shape wireframes, and other non-exportable scene helpers. */
+export function isEditorSceneNode(node) {
+    const meta = node.metadata;
+    if (meta?.quarksEditorPick || meta?.quarksEditorSceneNode) {
+        return true;
+    }
+    const name = node.name;
+    return name.startsWith('viewport-pick-root-') || name.startsWith('wf-');
+}

package/dist/core/effectTree.js

@@ -1,6 +1,7 @@
 import { ParticleEmitter } from 'babylon.quarks';
 import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
 import { Matrix, Quaternion } from '@babylonjs/core/Maths/math.vector';
+import { isEditorSceneNode } from './editorScene';
 /** Walks a loaded root TransformNode into the editor tree (groups + emitters). */
 export function buildEffectTree(root, depth = 0) {
     const system = root instanceof ParticleEmitter ? root.system : undefined;
@@ -12,7 +13,7 @@ export function buildEffectTree(root, depth = 0) {
         children: [],
     };
     for (const child of root.getChildren()) {
-        if (child instanceof TransformNode) {
+        if (child instanceof TransformNode && !isEditorSceneNode(child)) {
             treeNode.children.push(buildEffectTree(child, depth + 1));
         }
     }

package/dist/core/emitterShapeWireframe.d.ts

@@ -0,0 +1,20 @@
+import type { ParticleSystem } from 'babylon.quarks';
+import type { Scene } from '@babylonjs/core/scene';
+/**
+ * Optional wireframe overlays for every emitter shape in the current effect.
+ * Geometry follows quarks.core spawn math (local XY spawn plane, +Z emit axis).
+ */
+export declare class EmitterShapeWireframes {
+    private readonly scene;
+    private readonly container;
+    private meshes;
+    private visible;
+    private syncKey;
+    constructor(scene: Scene);
+    setVisible(on: boolean): void;
+    /** Rebuilds overlays when the binding revision changes. */
+    sync(systems: ParticleSystem[], syncKey: string): void;
+    dispose(): void;
+    private rebuild;
+    private clearMeshes;
+}

package/dist/core/emitterShapeWireframe.js

@@ -0,0 +1,329 @@
+import { Color3 } from '@babylonjs/core/Maths/math.color';
+import { Vector3 } from '@babylonjs/core/Maths/math.vector';
+import { MeshBuilder } from '@babylonjs/core/Meshes/meshBuilder';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { getShapeType, readShapeParams } from './shapes';
+import { EDITOR_SCENE_NODE_METADATA } from './editorScene';
+const LINE_COLOR = new Color3(0.45, 0.82, 1);
+const DIRECTION_COLOR = new Color3(0.75, 0.92, 1);
+/**
+ * Optional wireframe overlays for every emitter shape in the current effect.
+ * Geometry follows quarks.core spawn math (local XY spawn plane, +Z emit axis).
+ */
+export class EmitterShapeWireframes {
+    constructor(scene) {
+        this.meshes = [];
+        this.visible = false;
+        this.syncKey = '';
+        this.scene = scene;
+        this.container = new TransformNode('emitter-wireframes', scene);
+        this.container.setEnabled(false);
+    }
+    setVisible(on) {
+        this.visible = on;
+        if (!on) {
+            this.clearMeshes();
+            this.container.setEnabled(false);
+            this.syncKey = '';
+        }
+    }
+    /** Rebuilds overlays when the binding revision changes. */
+    sync(systems, syncKey) {
+        if (!this.visible) {
+            return;
+        }
+        if (syncKey === this.syncKey) {
+            return;
+        }
+        this.syncKey = syncKey;
+        this.rebuild(systems);
+    }
+    dispose() {
+        this.setVisible(false);
+        this.container.dispose();
+    }
+    rebuild(systems) {
+        this.clearMeshes();
+        this.container.setEnabled(true);
+        for (const system of systems) {
+            if (system.emitter.isDisposed()) {
+                continue;
+            }
+            for (const mesh of buildEmitterWireframe(system, this.scene)) {
+                mesh.parent = system.emitter;
+                mesh.metadata = { ...(mesh.metadata ?? {}), ...EDITOR_SCENE_NODE_METADATA };
+                mesh.isPickable = false;
+                mesh.renderingGroupId = 1;
+                this.meshes.push(mesh);
+            }
+        }
+    }
+    clearMeshes() {
+        for (const mesh of this.meshes) {
+            mesh.dispose();
+        }
+        this.meshes = [];
+    }
+}
+function buildEmitterWireframe(system, scene) {
+    const type = getShapeType(system.emitterShape);
+    const params = readShapeParams(system.emitterShape);
+    const meshes = [];
+    const lines = (name, points, color = LINE_COLOR) => {
+        if (points.length < 2) {
+            return;
+        }
+        const mesh = MeshBuilder.CreateLines(name, { points }, scene);
+        mesh.color = color.clone();
+        mesh.isPickable = false;
+        meshes.push(mesh);
+    };
+    switch (type) {
+        case 'point': {
+            // Spawn at origin; velocity is random in a unit ball.
+            const s = 0.12;
+            lines('wf-point-x', [new Vector3(-s, 0, 0), new Vector3(s, 0, 0)]);
+            lines('wf-point-y', [new Vector3(0, -s, 0), new Vector3(0, s, 0)]);
+            lines('wf-point-z', [new Vector3(0, 0, -s), new Vector3(0, 0, s)], DIRECTION_COLOR);
+            break;
+        }
+        case 'cone': {
+            // Spawn: disk/ring on XY at z=0 (radius, thickness, arc).
+            // Velocity: +Z with spread angle — rim dir = (sinα·û, cosα).
+            const radius = Math.max(params.radius, 0.001);
+            const angle = Math.max(0, params.angle);
+            const arc = clampArc(params.arc);
+            const thickness = clamp01(params.thickness);
+            lines('wf-cone-outer', xyArc(radius, arc));
+            if (thickness < 1) {
+                lines('wf-cone-inner', xyArc(radius * (1 - thickness), arc));
+            }
+            if (arc < Math.PI * 2 - 1e-3) {
+                lines('wf-cone-spoke-a', [Vector3.Zero(), arcPoint(radius, 0)]);
+                lines('wf-cone-spoke-b', [Vector3.Zero(), arcPoint(radius, arc)]);
+            }
+            const preview = Math.max(radius * 2, 1.25);
+            const farRadius = radius + preview * Math.tan(angle);
+            const spokeCount = Math.max(4, Math.ceil((arc / (Math.PI * 2)) * 12));
+            for (let i = 0; i <= spokeCount; i++) {
+                const theta = (i / spokeCount) * arc;
+                const rim = arcPoint(radius, theta);
+                const dir = new Vector3(Math.sin(angle) * Math.cos(theta), Math.sin(angle) * Math.sin(theta), Math.cos(angle));
+                const travel = preview / Math.max(Math.cos(angle), 0.05);
+                lines(`wf-cone-ray-${i}`, [rim, rim.add(dir.scale(travel))], DIRECTION_COLOR);
+            }
+            lines('wf-cone-far', xyArc(farRadius, arc, 32, preview), DIRECTION_COLOR);
+            break;
+        }
+        case 'sphere': {
+            // Spawn on spherical shell/volume; velocity radial from center.
+            const radius = Math.max(params.radius, 0.001);
+            const arc = clampArc(params.arc);
+            const thickness = clamp01(params.thickness);
+            drawSphereShell(lines, 'wf-sphere', radius, arc);
+            if (thickness < 1) {
+                drawSphereShell(lines, 'wf-sphere-inner', radius * (1 - thickness), arc);
+            }
+            break;
+        }
+        case 'hemisphere': {
+            // Spawn on +Z hemisphere (phi 0..π/2): flat on XY through origin, dome toward +Z.
+            const radius = Math.max(params.radius, 0.001);
+            const arc = clampArc(params.arc);
+            const thickness = clamp01(params.thickness);
+            drawHemisphereShell(lines, 'wf-hemi', radius, arc);
+            lines('wf-hemi-base', xyArc(radius, arc));
+            if (thickness < 1) {
+                drawHemisphereShell(lines, 'wf-hemi-inner', radius * (1 - thickness), arc);
+                lines('wf-hemi-base-inner', xyArc(radius * (1 - thickness), arc));
+            }
+            break;
+        }
+        case 'circle': {
+            // Spawn on circle/ring in XY; velocity radial in XY.
+            const radius = Math.max(params.radius, 0.001);
+            const arc = clampArc(params.arc);
+            const thickness = clamp01(params.thickness);
+            lines('wf-circle', xyArc(radius, arc));
+            if (thickness < 1) {
+                lines('wf-circle-inner', xyArc(radius * (1 - thickness), arc));
+            }
+            if (arc < Math.PI * 2 - 1e-3) {
+                lines('wf-circle-spoke-a', [Vector3.Zero(), arcPoint(radius, 0)]);
+                lines('wf-circle-spoke-b', [Vector3.Zero(), arcPoint(radius, arc)]);
+            }
+            break;
+        }
+        case 'donut': {
+            // Spawn on torus: major ring of `radius` in XY, tube radius `donutRadius`.
+            const radius = Math.max(params.radius, 0.001);
+            const tube = Math.max(params.donutRadius, 0.001);
+            const arc = clampArc(params.arc);
+            const thickness = clamp01(params.thickness);
+            lines('wf-donut-major', xyArc(radius, arc));
+            lines('wf-donut-outer', xyArc(radius + tube, arc));
+            lines('wf-donut-inner', xyArc(Math.max(radius - tube, 0), arc));
+            if (thickness < 1) {
+                lines('wf-donut-tube-inner', xyArc(radius + tube * (1 - thickness), arc));
+            }
+            const tubeSamples = Math.max(4, Math.ceil((arc / (Math.PI * 2)) * 8));
+            for (let i = 0; i <= tubeSamples; i++) {
+                const theta = (i / tubeSamples) * arc;
+                lines(`wf-donut-tube-${i}`, torusTubeRing(radius, tube, theta));
+            }
+            break;
+        }
+        case 'rectangle': {
+            // Spawn on rectangle perimeter (thickness fills toward center); velocity outward in XY.
+            const thickness = clamp01(params.thickness);
+            lines('wf-rect', xyRect(params.width, params.height));
+            if (thickness > 0 && thickness < 1) {
+                lines('wf-rect-inner', xyRect(params.width * (1 - thickness), params.height * (1 - thickness)));
+            }
+            break;
+        }
+        case 'grid': {
+            // Discrete spawn cells in XY; velocity straight +Z.
+            const cols = Math.max(1, Math.floor(params.column));
+            const rows = Math.max(1, Math.floor(params.row));
+            const halfW = params.width / 2;
+            const halfH = params.height / 2;
+            lines('wf-grid-border', xyRect(params.width, params.height));
+            const mark = Math.min(params.width / cols, params.height / rows, 0.12) * 0.35;
+            const ray = Math.max(mark * 4, 0.25);
+            for (let c = 0; c < cols; c++) {
+                for (let r = 0; r < rows; r++) {
+                    const x = (c * params.width) / cols - halfW;
+                    const y = (r * params.height) / rows - halfH;
+                    const p = new Vector3(x, y, 0);
+                    lines(`wf-grid-x-${c}-${r}`, [new Vector3(x - mark, y, 0), new Vector3(x + mark, y, 0)]);
+                    lines(`wf-grid-y-${c}-${r}`, [new Vector3(x, y - mark, 0), new Vector3(x, y + mark, 0)]);
+                    lines(`wf-grid-ray-${c}-${r}`, [p, new Vector3(x, y, ray)], DIRECTION_COLOR);
+                }
+            }
+            break;
+        }
+        case 'mesh_surface': {
+            const source = params.mesh;
+            if (source && !source.isDisposed()) {
+                const positions = source.getVerticesData('position');
+                const indices = source.getIndices();
+                if (positions && indices && indices.length >= 3) {
+                    const edgeSet = new Set();
+                    const pushEdge = (a, b) => {
+                        const key = a < b ? `${a}_${b}` : `${b}_${a}`;
+                        if (edgeSet.has(key)) {
+                            return;
+                        }
+                        edgeSet.add(key);
+                        lines(`wf-mesh-e-${key}`, [
+                            new Vector3(positions[a * 3], positions[a * 3 + 1], positions[a * 3 + 2]),
+                            new Vector3(positions[b * 3], positions[b * 3 + 1], positions[b * 3 + 2]),
+                        ]);
+                    };
+                    const maxTris = Math.min(indices.length / 3, 400);
+                    for (let t = 0; t < maxTris; t++) {
+                        const i = t * 3;
+                        pushEdge(indices[i], indices[i + 1]);
+                        pushEdge(indices[i + 1], indices[i + 2]);
+                        pushEdge(indices[i + 2], indices[i]);
+                    }
+                }
+                else {
+                    lines('wf-mesh-missing', xyRect(0.6, 0.6));
+                }
+            }
+            else {
+                lines('wf-mesh-missing', xyRect(0.6, 0.6));
+            }
+            break;
+        }
+        default:
+            break;
+    }
+    return meshes;
+}
+function drawSphereShell(lines, prefix, radius, arc) {
+    // Latitude rings + longitude arcs matching spherical spawn (theta around Z via arc).
+    const latCount = 4;
+    for (let i = 1; i < latCount; i++) {
+        const phi = (i / latCount) * Math.PI;
+        const ringR = radius * Math.sin(phi);
+        const z = radius * Math.cos(phi);
+        lines(`${prefix}-lat-${i}`, xyArc(ringR, arc, 48, z));
+    }
+    const lonCount = Math.max(4, Math.ceil((arc / (Math.PI * 2)) * 8));
+    for (let i = 0; i <= lonCount; i++) {
+        const theta = (i / lonCount) * arc;
+        const points = [];
+        for (let j = 0; j <= 16; j++) {
+            const phi = (j / 16) * Math.PI;
+            points.push(new Vector3(radius * Math.sin(phi) * Math.cos(theta), radius * Math.sin(phi) * Math.sin(theta), radius * Math.cos(phi)));
+        }
+        lines(`${prefix}-lon-${i}`, points);
+    }
+}
+function drawHemisphereShell(lines, prefix, radius, arc) {
+    // Quarks: phi = acos(v) ∈ [0, π/2] → z = cos(phi) ∈ [0, 1].
+    const latCount = 3;
+    for (let i = 1; i <= latCount; i++) {
+        const phi = (i / (latCount + 1)) * (Math.PI / 2);
+        const ringR = radius * Math.sin(phi);
+        const z = radius * Math.cos(phi);
+        lines(`${prefix}-lat-${i}`, xyArc(ringR, arc, 32, z));
+    }
+    const lonCount = Math.max(4, Math.ceil((arc / (Math.PI * 2)) * 8));
+    for (let i = 0; i <= lonCount; i++) {
+        const theta = (i / lonCount) * arc;
+        const points = [new Vector3(0, 0, radius)];
+        for (let j = 1; j <= 12; j++) {
+            const phi = (j / 12) * (Math.PI / 2);
+            points.push(new Vector3(radius * Math.sin(phi) * Math.cos(theta), radius * Math.sin(phi) * Math.sin(theta), radius * Math.cos(phi)));
+        }
+        lines(`${prefix}-lon-${i}`, points);
+    }
+}
+function torusTubeRing(major, tube, theta) {
+    const cos = Math.cos(theta);
+    const sin = Math.sin(theta);
+    const points = [];
+    for (let i = 0; i <= 16; i++) {
+        const phi = (i / 16) * Math.PI * 2;
+        points.push(new Vector3((major + tube * Math.cos(phi)) * cos, (major + tube * Math.cos(phi)) * sin, tube * Math.sin(phi)));
+    }
+    return points;
+}
+function xyArc(radius, arc, segments = 48, z = 0) {
+    const points = [];
+    const steps = Math.max(8, Math.ceil(segments * (arc / (Math.PI * 2))));
+    for (let i = 0; i <= steps; i++) {
+        points.push(arcPoint(radius, (i / steps) * arc, z));
+    }
+    return points;
+}
+function arcPoint(radius, theta, z = 0) {
+    return new Vector3(Math.cos(theta) * radius, Math.sin(theta) * radius, z);
+}
+function xyRect(width, height) {
+    const halfW = width / 2;
+    const halfH = height / 2;
+    return [
+        new Vector3(-halfW, -halfH, 0),
+        new Vector3(halfW, -halfH, 0),
+        new Vector3(halfW, halfH, 0),
+        new Vector3(-halfW, halfH, 0),
+        new Vector3(-halfW, -halfH, 0),
+    ];
+}
+function clampArc(arc) {
+    if (!Number.isFinite(arc) || arc <= 0) {
+        return Math.PI * 2;
+    }
+    return Math.min(Math.PI * 2, arc);
+}
+function clamp01(value) {
+    if (!Number.isFinite(value)) {
+        return 1;
+    }
+    return Math.min(1, Math.max(0, value));
+}

package/dist/core/galleryDragSession.d.ts

@@ -0,0 +1,4 @@
+import type { GalleryDragPayload } from './galleryTree';
+/** Stores the current gallery drag payload for viewport preview (getData is drop-only in most browsers). */
+export declare function setGalleryDragSession(payload: GalleryDragPayload | null): void;
+export declare function getGalleryDragSession(): GalleryDragPayload | null;

package/dist/core/galleryDragSession.js

@@ -0,0 +1,8 @@
+let activeDrag = null;
+/** Stores the current gallery drag payload for viewport preview (getData is drop-only in most browsers). */
+export function setGalleryDragSession(payload) {
+    activeDrag = payload;
+}
+export function getGalleryDragSession() {
+    return activeDrag;
+}

package/dist/core/galleryDropMarker.d.ts

@@ -0,0 +1,13 @@
+import { Vector3 } from '@babylonjs/core/Maths/math.vector';
+import type { Scene } from '@babylonjs/core/scene';
+/** Ground decal shown while dragging gallery items over the viewport. */
+export declare class GalleryDropMarker {
+    private readonly root;
+    private readonly disc;
+    private readonly material;
+    constructor(scene: Scene);
+    /** Positions the marker for a single effect or a folder grid footprint. */
+    show(position: Vector3, effectCount: number, spacing?: number): void;
+    hide(): void;
+    dispose(): void;
+}

package/dist/core/galleryDropMarker.js

@@ -0,0 +1,42 @@
+import { Color3 } from '@babylonjs/core/Maths/math.color';
+import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
+import { Mesh } from '@babylonjs/core/Meshes/mesh';
+import { MeshBuilder } from '@babylonjs/core/Meshes/meshBuilder';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { DEFAULT_GALLERY_SPACING, gallerySpan } from './galleryLayout';
+/** Ground decal shown while dragging gallery items over the viewport. */
+export class GalleryDropMarker {
+    constructor(scene) {
+        this.root = new TransformNode('gallery-drop-root', scene);
+        this.disc = MeshBuilder.CreateDisc('gallery-drop-fill', { radius: 1, tessellation: 48, sideOrientation: Mesh.DOUBLESIDE }, scene);
+        this.disc.parent = this.root;
+        this.disc.rotation.x = Math.PI / 2;
+        this.material = new StandardMaterial('gallery-drop-fill-mat', scene);
+        this.material.emissiveColor = new Color3(0.35, 0.55, 1);
+        this.material.alpha = 0.24;
+        this.material.disableLighting = true;
+        this.material.backFaceCulling = false;
+        this.disc.material = this.material;
+        this.disc.isPickable = false;
+        this.disc.renderingGroupId = 1;
+        this.hide();
+    }
+    /** Positions the marker for a single effect or a folder grid footprint. */
+    show(position, effectCount, spacing = DEFAULT_GALLERY_SPACING) {
+        const span = Math.max(gallerySpan(effectCount, spacing), spacing);
+        const radius = Math.max(0.375, span * 0.25 + spacing * 0.175);
+        this.root.position.set(position.x, 0.03, position.z);
+        this.root.scaling.set(radius, radius, radius);
+        this.material.alpha = effectCount > 1 ? 0.16 : 0.24;
+        this.material.emissiveColor = effectCount > 1 ? new Color3(0.45, 0.9, 0.75) : new Color3(0.55, 0.78, 1);
+        this.root.setEnabled(true);
+    }
+    hide() {
+        this.root.setEnabled(false);
+    }
+    dispose() {
+        this.material.dispose();
+        this.disc.dispose();
+        this.root.dispose();
+    }
+}

package/dist/core/galleryLayout.d.ts

@@ -0,0 +1,20 @@
+import type { ArcRotateCamera } from '@babylonjs/core/Cameras/arcRotateCamera';
+import type { Mesh } from '@babylonjs/core/Meshes/mesh';
+import type { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+/** Default gap between neighbouring effects in a folder gallery import. */
+export declare const DEFAULT_GALLERY_SPACING = 4;
+/** Square-grid column count for `count` items. */
+export declare function galleryColumnCount(count: number): number;
+/** World X/Z offset for the `index`th effect in a square grid. */
+export declare function galleryGridPosition(index: number, count: number, spacing?: number): {
+    x: number;
+    z: number;
+};
+/** Longest side of the grid footprint in world units. */
+export declare function gallerySpan(count: number, spacing?: number): number;
+/** Pulls the camera back and scales the ground plane to frame a gallery grid. */
+export declare function fitGalleryView(camera: ArcRotateCamera, ground: Mesh, count: number, spacing?: number): void;
+/** Stops an in-flight gallery camera focus animation. */
+export declare function cancelGalleryCameraFocus(): void;
+/** Smoothly frames the camera on an in-scene gallery effect. */
+export declare function focusGalleryEntry(camera: ArcRotateCamera, entryRoot: TransformNode, durationMs?: number): void;