babylon.quarks-editor 0.17.7 → 0.17.9

package/dist/core/galleryLayout.js

@@ -0,0 +1,68 @@
+import { Vector3 } from '@babylonjs/core/Maths/math.vector';
+/** Default gap between neighbouring effects in a folder gallery import. */
+export const DEFAULT_GALLERY_SPACING = 4;
+/** Square-grid column count for `count` items. */
+export function galleryColumnCount(count) {
+    return Math.max(1, Math.ceil(Math.sqrt(count)));
+}
+/** World X/Z offset for the `index`th effect in a square grid. */
+export function galleryGridPosition(index, count, spacing = DEFAULT_GALLERY_SPACING) {
+    const cols = galleryColumnCount(count);
+    const rows = Math.ceil(count / cols);
+    const col = index % cols;
+    const row = Math.floor(index / cols);
+    return {
+        x: (col - (cols - 1) / 2) * spacing,
+        z: (row - (rows - 1) / 2) * spacing,
+    };
+}
+/** Longest side of the grid footprint in world units. */
+export function gallerySpan(count, spacing = DEFAULT_GALLERY_SPACING) {
+    const cols = galleryColumnCount(count);
+    const rows = Math.ceil(count / cols);
+    return Math.max((cols - 1) * spacing, (rows - 1) * spacing, spacing);
+}
+/** Pulls the camera back and scales the ground plane to frame a gallery grid. */
+export function fitGalleryView(camera, ground, count, spacing = DEFAULT_GALLERY_SPACING) {
+    const span = gallerySpan(count, spacing);
+    camera.setTarget(new Vector3(0, 1.4, 0));
+    camera.radius = Math.max(span * 0.85, 12);
+    camera.beta = Math.min(camera.beta, 1.1);
+    const groundSize = Math.max(span + spacing * 4, 100);
+    ground.scaling.x = groundSize / 100;
+    ground.scaling.z = groundSize / 100;
+}
+let cameraFocusFrame = 0;
+function easeOutCubic(t) {
+    return 1 - (1 - t) ** 3;
+}
+/** Stops an in-flight gallery camera focus animation. */
+export function cancelGalleryCameraFocus() {
+    if (cameraFocusFrame) {
+        cancelAnimationFrame(cameraFocusFrame);
+        cameraFocusFrame = 0;
+    }
+}
+/** Smoothly frames the camera on an in-scene gallery effect. */
+export function focusGalleryEntry(camera, entryRoot, durationMs = 450) {
+    cancelGalleryCameraFocus();
+    const pos = entryRoot.getAbsolutePosition();
+    const target = new Vector3(pos.x, pos.y + 1.4, pos.z);
+    const startTarget = camera.target.clone();
+    const startRadius = camera.radius;
+    const jumpDist = Vector3.Distance(startTarget, target);
+    const desiredRadius = jumpDist > 3 ? 12 : Math.min(startRadius, 16);
+    const start = performance.now();
+    const tick = () => {
+        const t = easeOutCubic(Math.min(1, (performance.now() - start) / durationMs));
+        camera.setTarget(Vector3.Lerp(startTarget, target, t));
+        camera.radius = startRadius + (desiredRadius - startRadius) * t;
+        if (t < 1) {
+            cameraFocusFrame = requestAnimationFrame(tick);
+        }
+        else {
+            cameraFocusFrame = 0;
+        }
+    };
+    cameraFocusFrame = requestAnimationFrame(tick);
+}

package/dist/core/galleryPlayback.d.ts

@@ -0,0 +1,9 @@
+import type { GalleryEntry } from './loadEffectGallery';
+/** Freezes every gallery entry; unpauses all in-scene entries in the preview set when transport is playing. */
+export declare function applyGalleryPlayback(entries: GalleryEntry[], previewRootIds: ReadonlySet<number>, transportPlaying: boolean): void;
+/** Whether any preview effect on stage should keep simulating. */
+export declare function hasActivePreview(entries: GalleryEntry[], previewRootIds: ReadonlySet<number>): boolean;
+/** In-scene preview effects currently in the preview set. */
+export declare function countActivePreviews(entries: GalleryEntry[], previewRootIds: ReadonlySet<number>): number;
+/** Particle count across all active preview effects. */
+export declare function countGalleryParticles(entries: GalleryEntry[], previewRootIds: ReadonlySet<number>): number;

package/dist/core/galleryPlayback.js

@@ -0,0 +1,43 @@
+function isPreviewEntry(entry, previewRootIds) {
+    return entry.inScene && previewRootIds.has(entry.root.uniqueId);
+}
+/** Freezes every gallery entry; unpauses all in-scene entries in the preview set when transport is playing. */
+export function applyGalleryPlayback(entries, previewRootIds, transportPlaying) {
+    for (const entry of entries) {
+        for (const system of entry.systems) {
+            system.pause();
+        }
+    }
+    if (!transportPlaying) {
+        return;
+    }
+    for (const entry of entries) {
+        if (!isPreviewEntry(entry, previewRootIds)) {
+            continue;
+        }
+        for (const system of entry.systems) {
+            system.play();
+        }
+    }
+}
+/** Whether any preview effect on stage should keep simulating. */
+export function hasActivePreview(entries, previewRootIds) {
+    return entries.some((entry) => isPreviewEntry(entry, previewRootIds));
+}
+/** In-scene preview effects currently in the preview set. */
+export function countActivePreviews(entries, previewRootIds) {
+    return entries.filter((entry) => isPreviewEntry(entry, previewRootIds)).length;
+}
+/** Particle count across all active preview effects. */
+export function countGalleryParticles(entries, previewRootIds) {
+    let count = 0;
+    for (const entry of entries) {
+        if (!isPreviewEntry(entry, previewRootIds)) {
+            continue;
+        }
+        for (const system of entry.systems) {
+            count += system.particleNum;
+        }
+    }
+    return count;
+}

package/dist/core/galleryScene.d.ts

@@ -0,0 +1,12 @@
+import { Vector3 } from '@babylonjs/core/Maths/math.vector';
+import type { Scene } from '@babylonjs/core/scene';
+import type { BatchedRenderer } from 'babylon.quarks';
+import type { GalleryEntry } from './loadEffectGallery';
+/** Parents a catalog entry into the live scene and registers its systems with the renderer. */
+export declare function placeGalleryEntryInScene(entry: GalleryEntry, renderer: BatchedRenderer, worldPosition: Vector3): void;
+/** Spawns a batch of catalog effects in a square grid centered on `center`. */
+export declare function placeGalleryEntriesAt(entries: GalleryEntry[], renderer: BatchedRenderer, center: Vector3, spacing?: number): void;
+/** Raycasts the editor ground plane from canvas/client coordinates. */
+export declare function pickGroundPosition(scene: Scene, clientX: number, clientY: number): Vector3;
+/** Finds a gallery entry by Babylon node id from a drag payload. */
+export declare function findGalleryEntryById(entries: GalleryEntry[], id: string): GalleryEntry | undefined;

package/dist/core/galleryScene.js

@@ -0,0 +1,41 @@
+import { Vector3 } from '@babylonjs/core/Maths/math.vector';
+import { DEFAULT_GALLERY_SPACING, galleryGridPosition } from './galleryLayout';
+/** Parents a catalog entry into the live scene and registers its systems with the renderer. */
+export function placeGalleryEntryInScene(entry, renderer, worldPosition) {
+    entry.root.setEnabled(true);
+    entry.root.parent = null;
+    entry.root.position.copyFrom(worldPosition);
+    if (!entry.inScene) {
+        for (const system of entry.systems) {
+            renderer.addSystem(system);
+            system.pause();
+        }
+        entry.inScene = true;
+    }
+}
+/** Spawns a batch of catalog effects in a square grid centered on `center`. */
+export function placeGalleryEntriesAt(entries, renderer, center, spacing = DEFAULT_GALLERY_SPACING) {
+    entries.forEach((entry, index) => {
+        const offset = galleryGridPosition(index, entries.length, spacing);
+        const position = center.add(new Vector3(offset.x, 0, offset.z));
+        placeGalleryEntryInScene(entry, renderer, position);
+    });
+}
+/** Raycasts the editor ground plane from canvas/client coordinates. */
+export function pickGroundPosition(scene, clientX, clientY) {
+    const canvas = scene.getEngine().getRenderingCanvas();
+    if (!canvas) {
+        return Vector3.Zero();
+    }
+    const rect = canvas.getBoundingClientRect();
+    const pick = scene.pick(clientX - rect.left, clientY - rect.top, (mesh) => mesh.name === 'ground');
+    return pick?.pickedPoint?.clone() ?? Vector3.Zero();
+}
+/** Finds a gallery entry by Babylon node id from a drag payload. */
+export function findGalleryEntryById(entries, id) {
+    const numericId = Number(id);
+    if (!Number.isFinite(numericId)) {
+        return undefined;
+    }
+    return entries.find((entry) => entry.root.uniqueId === numericId);
+}

package/dist/core/gallerySelectionMarker.d.ts

@@ -0,0 +1,25 @@
+import { Color3 } from '@babylonjs/core/Maths/math.color';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import type { Scene } from '@babylonjs/core/scene';
+export declare const GROUND_RING_RADIUS = 1.2;
+/** Flat ground ring that tracks a transform on the XZ plane. */
+declare class GroundRingMarker {
+    private readonly anchor;
+    private readonly ring;
+    private trackedRoot;
+    constructor(scene: Scene, name: string, color: Color3);
+    show(entryRoot: TransformNode): void;
+    hide(): void;
+    follow(): void;
+    dispose(): void;
+    private syncPosition;
+}
+/** Flat blue selection ring on the ground under the focused in-scene effect. */
+export declare class GallerySelectionMarker extends GroundRingMarker {
+    constructor(scene: Scene);
+}
+/** Same ring as selection, yellow — shown while hovering an effect root in the viewport. */
+export declare class GalleryHoverMarker extends GroundRingMarker {
+    constructor(scene: Scene);
+}
+export {};

package/dist/core/gallerySelectionMarker.js

@@ -0,0 +1,69 @@
+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';
+export const GROUND_RING_RADIUS = 1.2;
+const RING_SEGMENTS = 64;
+const RING_Y = 0.03;
+const SELECTION_RING_COLOR = new Color3(0.55, 0.78, 1);
+const HOVER_RING_COLOR = new Color3(1, 0.86, 0.35);
+function buildGroundRingPoints(radius) {
+    const points = [];
+    for (let i = 0; i <= RING_SEGMENTS; i++) {
+        const t = (i / RING_SEGMENTS) * Math.PI * 2;
+        points.push(new Vector3(Math.cos(t) * radius, 0, Math.sin(t) * radius));
+    }
+    return points;
+}
+/** Flat ground ring that tracks a transform on the XZ plane. */
+class GroundRingMarker {
+    constructor(scene, name, color) {
+        this.trackedRoot = null;
+        this.anchor = new TransformNode(`${name}-root`, scene);
+        this.ring = MeshBuilder.CreateLines(`${name}-ring`, { points: buildGroundRingPoints(GROUND_RING_RADIUS) }, scene);
+        this.ring.color = color;
+        this.ring.parent = this.anchor;
+        this.ring.isPickable = false;
+        this.ring.renderingGroupId = 1;
+        this.hide();
+    }
+    show(entryRoot) {
+        this.trackedRoot = entryRoot;
+        this.syncPosition();
+        this.anchor.setEnabled(true);
+    }
+    hide() {
+        this.trackedRoot = null;
+        this.anchor.setEnabled(false);
+    }
+    follow() {
+        if (!this.trackedRoot || this.trackedRoot.isDisposed()) {
+            return;
+        }
+        this.syncPosition();
+    }
+    dispose() {
+        this.hide();
+        this.ring.dispose();
+        this.anchor.dispose();
+    }
+    syncPosition() {
+        if (!this.trackedRoot) {
+            return;
+        }
+        const pos = this.trackedRoot.getAbsolutePosition();
+        this.anchor.position.set(pos.x, RING_Y, pos.z);
+    }
+}
+/** Flat blue selection ring on the ground under the focused in-scene effect. */
+export class GallerySelectionMarker extends GroundRingMarker {
+    constructor(scene) {
+        super(scene, 'gallery-selection', SELECTION_RING_COLOR);
+    }
+}
+/** Same ring as selection, yellow — shown while hovering an effect root in the viewport. */
+export class GalleryHoverMarker extends GroundRingMarker {
+    constructor(scene) {
+        super(scene, 'gallery-hover', HOVER_RING_COLOR);
+    }
+}

package/dist/core/galleryTree.d.ts

@@ -0,0 +1,49 @@
+import type { GalleryEntry } from './loadEffectGallery';
+export interface GalleryTreeFolder {
+    kind: 'folder';
+    name: string;
+    path: string;
+    children: GalleryTreeNode[];
+}
+export interface GalleryTreeEffect {
+    kind: 'effect';
+    name: string;
+    path: string;
+    entry: GalleryEntry;
+}
+export type GalleryTreeNode = GalleryTreeFolder | GalleryTreeEffect;
+/** Builds a folder tree from gallery entry relative paths (e.g. `VFX/Fire/Explosion.json`). */
+export declare function buildGalleryTree(entries: GalleryEntry[]): GalleryTreeNode[];
+/** Filters a folder tree while preserving ancestors of matching effects. */
+export declare function filterGalleryTree(nodes: GalleryTreeNode[], query: string): GalleryTreeNode[];
+export declare const GALLERY_DRAG_MIME = "application/x-quarks-gallery-drop";
+export type GalleryDragPayload = {
+    kind: 'effect';
+    id: number;
+} | {
+    kind: 'folder';
+    path: string;
+};
+export declare function writeGalleryDrag(dataTransfer: DataTransfer, payload: GalleryDragPayload): void;
+export declare function readGalleryDrag(dataTransfer: DataTransfer): GalleryDragPayload | null;
+/** Returns every effect whose JSON path sits inside `folderPath` (recursive). */
+export declare function collectEntriesInFolder(entries: GalleryEntry[], folderPath: string): GalleryEntry[];
+/** Collects all effects under a folder tree node. */
+export declare function collectFolderEntries(node: GalleryTreeFolder): GalleryEntry[];
+export type GalleryFlatRow = {
+    kind: 'folder';
+    depth: number;
+    node: GalleryTreeFolder;
+    effectCount: number;
+} | {
+    kind: 'effect';
+    depth: number;
+    node: GalleryTreeEffect;
+};
+/** Flattens the visible folder tree into rows for virtual scrolling. */
+export declare function flattenVisibleGalleryRows(nodes: GalleryTreeNode[], closedFolders: ReadonlySet<string>, expandAll: boolean, depth?: number): GalleryFlatRow[];
+/** Resolves a drag payload to the entries that would be placed on drop. */
+export declare function describeGalleryDrag(entries: GalleryEntry[], payload: GalleryDragPayload): {
+    entries: GalleryEntry[];
+    label: string;
+};

package/dist/core/galleryTree.js

@@ -0,0 +1,138 @@
+function compareNodes(a, b) {
+    if (a.kind !== b.kind) {
+        return a.kind === 'folder' ? -1 : 1;
+    }
+    return a.name.localeCompare(b.name, undefined, { sensitivity: 'base' });
+}
+/** Builds a folder tree from gallery entry relative paths (e.g. `VFX/Fire/Explosion.json`). */
+export function buildGalleryTree(entries) {
+    const roots = [];
+    for (const entry of entries) {
+        const normalized = entry.path.replace(/\\/g, '/');
+        const segments = normalized.replace(/\.json$/i, '').split('/').filter(Boolean);
+        const fileName = segments.pop() ?? entry.name;
+        let level = roots;
+        let pathSoFar = '';
+        for (const segment of segments) {
+            pathSoFar = pathSoFar ? `${pathSoFar}/${segment}` : segment;
+            let folder = level.find((node) => node.kind === 'folder' && node.name === segment);
+            if (!folder) {
+                folder = { kind: 'folder', name: segment, path: pathSoFar, children: [] };
+                level.push(folder);
+            }
+            level = folder.children;
+        }
+        level.push({
+            kind: 'effect',
+            name: fileName,
+            path: entry.path,
+            entry,
+        });
+    }
+    const sortTree = (nodes) => {
+        nodes.sort(compareNodes);
+        for (const node of nodes) {
+            if (node.kind === 'folder') {
+                sortTree(node.children);
+            }
+        }
+    };
+    sortTree(roots);
+    return roots;
+}
+/** Filters a folder tree while preserving ancestors of matching effects. */
+export function filterGalleryTree(nodes, query) {
+    const q = query.trim().toLowerCase();
+    if (!q) {
+        return nodes;
+    }
+    const walk = (node) => {
+        if (node.kind === 'effect') {
+            const haystack = `${node.path} ${node.name}`.toLowerCase();
+            return haystack.includes(q) ? node : null;
+        }
+        const children = node.children.map(walk).filter((child) => child !== null);
+        if (children.length === 0) {
+            return null;
+        }
+        return { ...node, children };
+    };
+    return nodes.map(walk).filter((node) => node !== null);
+}
+export const GALLERY_DRAG_MIME = 'application/x-quarks-gallery-drop';
+export function writeGalleryDrag(dataTransfer, payload) {
+    dataTransfer.setData(GALLERY_DRAG_MIME, JSON.stringify(payload));
+    dataTransfer.effectAllowed = 'copy';
+}
+export function readGalleryDrag(dataTransfer) {
+    const raw = dataTransfer.getData(GALLERY_DRAG_MIME);
+    if (!raw) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed?.kind === 'effect' && typeof parsed.id === 'number') {
+            return parsed;
+        }
+        if (parsed?.kind === 'folder' && typeof parsed.path === 'string') {
+            return parsed;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/** Returns every effect whose JSON path sits inside `folderPath` (recursive). */
+export function collectEntriesInFolder(entries, folderPath) {
+    const prefix = folderPath.replace(/\\/g, '/');
+    return entries.filter((entry) => {
+        const path = entry.path.replace(/\\/g, '/');
+        const parent = path.replace(/\/[^/]+\.json$/i, '');
+        return parent === prefix || parent.startsWith(`${prefix}/`);
+    });
+}
+/** Collects all effects under a folder tree node. */
+export function collectFolderEntries(node) {
+    const collected = [];
+    const walk = (nodes) => {
+        for (const child of nodes) {
+            if (child.kind === 'effect') {
+                collected.push(child.entry);
+            }
+            else {
+                walk(child.children);
+            }
+        }
+    };
+    walk(node.children);
+    return collected;
+}
+/** Flattens the visible folder tree into rows for virtual scrolling. */
+export function flattenVisibleGalleryRows(nodes, closedFolders, expandAll, depth = 0) {
+    const rows = [];
+    for (const node of nodes) {
+        if (node.kind === 'folder') {
+            const effectCount = collectFolderEntries(node).length;
+            rows.push({ kind: 'folder', depth, node, effectCount });
+            const open = expandAll || !closedFolders.has(node.path);
+            if (open) {
+                rows.push(...flattenVisibleGalleryRows(node.children, closedFolders, expandAll, depth + 1));
+            }
+        }
+        else {
+            rows.push({ kind: 'effect', depth, node });
+        }
+    }
+    return rows;
+}
+/** Resolves a drag payload to the entries that would be placed on drop. */
+export function describeGalleryDrag(entries, payload) {
+    if (payload.kind === 'effect') {
+        const entry = entries.find((item) => item.root.uniqueId === payload.id);
+        return { entries: entry ? [entry] : [], label: entry?.name ?? 'Effect' };
+    }
+    const folderEntries = collectEntriesInFolder(entries, payload.path);
+    const label = payload.path.split('/').filter(Boolean).pop() ?? payload.path;
+    return { entries: folderEntries, label };
+}

package/dist/core/loadEffect.d.ts

@@ -1,6 +1,19 @@
 import type { BatchedRenderer, ParticleSystem } from 'babylon.quarks';
 import type { Scene } from '@babylonjs/core/scene';
 import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+export interface LoadEffectOptions {
+    /** Registers systems with the batched renderer (default true). */
+    registerRenderer?: boolean;
+    /** Restarts and unpauses after load (default matches registerRenderer). */
+    autoplay?: boolean;
+}
+/** Disposes a loaded effect's systems and its remaining group tree. */
+export declare function disposeLoadedEffect(root: TransformNode, systems: ParticleSystem[], renderer: BatchedRenderer, inRenderer?: boolean): void;
+/** Parses Quarks JSON into a live hierarchy without optional renderer registration / playback. */
+export declare function parseEffectFromJson(scene: Scene, renderer: BatchedRenderer | null, json: unknown, options?: LoadEffectOptions, baseUrl?: string): {
+    root: TransformNode;
+    systems: ParticleSystem[];
+};
 /** Parses a Quarks JSON export, registers all systems with the renderer and starts playback. */
 export declare function loadEffectFromJson(scene: Scene, renderer: BatchedRenderer, json: unknown, baseUrl?: string): {
     root: TransformNode;

package/dist/core/loadEffect.js

@@ -19,15 +19,6 @@ function collapseInto(wrapper, only, parent) {
     only.setParent(parent);
     wrapper.dispose(true, false);
 }
-/**
- * Collapses redundant organizational groups left over by importers — Unity's
- * one-GameObject-per-component convention turns every visual layer into its own Group, so a
- * single particle system becomes "Sparks" > unnamed emitter, and a component quarks doesn't
- * understand (e.g. a Light) becomes an empty Group with nothing under it. Recurses
- * bottom-up so nested wrapper chains collapse all the way down. The tree root itself is
- * handled separately by `promoteIfSingleChildRoot`, since collapsing it means returning a
- * different node as the effect's root.
- */
 function flattenRedundantGroups(node) {
     for (const child of node.getChildren()) {
         if (child instanceof TransformNode) {
@@ -51,10 +42,6 @@ function flattenRedundantGroups(node) {
     }
     collapseInto(node, only, node.parent);
 }
-/** If the tree root itself only ever wraps a single child (after `flattenRedundantGroups`
- * has settled everything below it), that wrapper adds a tree level with nothing to organize —
- * promote the child to be the new root instead. Loops in case that child is, in turn, also a
- * single-child wrapper. */
 function promoteIfSingleChildRoot(root) {
     let current = root;
     while (!(current instanceof ParticleEmitter)) {
@@ -69,8 +56,22 @@ function promoteIfSingleChildRoot(root) {
     }
     return current;
 }
-/** Parses a Quarks JSON export, registers all systems with the renderer and starts playback. */
-export function loadEffectFromJson(scene, renderer, json, baseUrl = '') {
+/** Disposes a loaded effect's systems and its remaining group tree. */
+export function disposeLoadedEffect(root, systems, renderer, inRenderer = true) {
+    for (const system of systems) {
+        if (inRenderer) {
+            renderer.deleteSystem(system);
+        }
+        system.dispose();
+    }
+    if (!systems.some((system) => system.emitter === root)) {
+        root.dispose(false, true);
+    }
+}
+/** Parses Quarks JSON into a live hierarchy without optional renderer registration / playback. */
+export function parseEffectFromJson(scene, renderer, json, options = {}, baseUrl = '') {
+    const registerRenderer = options.registerRenderer ?? true;
+    const autoplay = options.autoplay ?? registerRenderer;
     const loader = new QuarksLoader(scene, { baseUrl });
     let root = loader.parse(json, baseUrl);
     flattenRedundantGroups(root);
@@ -78,10 +79,23 @@ export function loadEffectFromJson(scene, renderer, json, baseUrl = '') {
     const systems = [];
     QuarksUtil.runOnAllParticleEmitters(root, (emitter) => {
         const system = emitter.system;
-        renderer.addSystem(system);
+        if (registerRenderer && renderer) {
+            renderer.addSystem(system);
+        }
         systems.push(system);
     });
     QuarksUtil.restart(root);
-    QuarksUtil.play(root);
+    if (autoplay) {
+        QuarksUtil.play(root);
+    }
+    else {
+        for (const system of systems) {
+            system.pause();
+        }
+    }
     return { root, systems };
 }
+/** Parses a Quarks JSON export, registers all systems with the renderer and starts playback. */
+export function loadEffectFromJson(scene, renderer, json, baseUrl = '') {
+    return parseEffectFromJson(scene, renderer, json, { registerRenderer: true, autoplay: true }, baseUrl);
+}

package/dist/core/loadEffectGallery.d.ts

@@ -0,0 +1,36 @@
+import type { ParticleSystem } from 'babylon.quarks';
+import type { Scene } from '@babylonjs/core/scene';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { EffectBinding } from './binding';
+export interface GalleryEntry {
+    name: string;
+    /** Relative path inside the imported folder (preserves subfolders). */
+    path: string;
+    root: TransformNode;
+    systems: ParticleSystem[];
+    /** True once the user has dropped this effect into the viewport. */
+    inScene: boolean;
+}
+export interface GalleryLoadProgress {
+    done: number;
+    total: number;
+    loaded: number;
+    failed: number;
+}
+/** Collects `.json` files from a folder picker result, sorted by relative path. */
+export declare function collectJsonFiles(files: FileList | File[]): File[];
+/**
+ * Parses every JSON effect into a hidden catalog — not registered with the renderer until the
+ * user drops the effect into the viewport.
+ */
+export declare function loadEffectGallery(scene: Scene, files: FileList | File[], catalogRoot: TransformNode, onProgress: (progress: GalleryLoadProgress) => void): Promise<GalleryEntry[]>;
+/** Builds an edit binding for one catalog entry without unloading the rest. */
+export declare function bindingFromGalleryEntry(entry: GalleryEntry): EffectBinding;
+/** Merges newly loaded catalog entries, skipping duplicate paths. */
+export declare function mergeGalleryEntries(existing: GalleryEntry[], incoming: GalleryEntry[], renderer: import('babylon.quarks').BatchedRenderer | null): {
+    merged: GalleryEntry[];
+    added: GalleryEntry[];
+    skipped: number;
+};
+/** Disposes every catalog entry and the hidden catalog root. */
+export declare function disposeGallery(catalogRoot: TransformNode | null, entries: GalleryEntry[], renderer: import('babylon.quarks').BatchedRenderer): void;